[ViewVC] Annotation of: cvs/Games-Go-SimpleBoard/README

NAME
    Games::Go::SimpleBoard - represent a simple go board

SYNOPSIS
       use Games::Go::SimpleBoard;

DESCRIPTION
    Please supply a description )

  EXPORTED CONSTANTS
    Marker types for each board position (ORed together):

       MARK_B            # normal black stone
       MARK_W            # normal whit stone
       MARK_GRAYED       # in conjunction with MARK_[BW], grays the stone

       MARK_SMALL_B      # small stone, used for scoring or marking
       MARK_SMALL_W      # small stone, used for scoring or marking
       MARK_SMALL_GRAYED # in conjunction with MARK_SMALL_[BW], grays the stone

       MARK_TRIANGLE     # triangle mark
       MARK_SQUARE       # square mark
       MARK_CIRCLE       # circle mark
       MARK_CROSS        # cross mark

       MARK_LABEL        # a text label
       MARK_HOSHI        # this is a hoshi point (not used much)
       MARK_MOVE         # this is a regular move
       MARK_KO           # this is a ko position
       MARK_REDRAW       # ignored, can be used for your own purposes

       COLOUR_WHITE      # guaranteed to be 0
       COLOUR_BLACK      # guaranteed to be 1

       MOVE_HANDICAP     # used as "x-coordinate" for handicap moves
       MOVE_PASS         # can be used as "x-coordinate" for pass moves

  METHODS
    my $board = new $size
        Creates a new empty board of the given size.

        "$board->{size}" stores the board size.

        "$board->{max}" stores the maximum board coordinate (size-1).

        "$board->{captures}[COLOUR_xxx]" stores the number of captured
        stones for the given colour.

        "$board->{board}" stores a two-dimensional array with board
        contents.

    $hint = $board->update ([update-structures...])
        Each update-structure itself is also an array-ref:

           [$x, $y, $clr, $set, $label, $hint] # update or move
           [MOVE_HANDICAP, $handicap]          # black move, setup handicap
           [MOVE_PASS]                         # pass
           []                                  # also pass (deprecated!)

        It changes the board or executes a move, by first clearing the bits
        specified in $clr, then setting bits specified in $set.

        If $set includes "MARK_LABEL", the label text must be given in
        $label.

        If $set contains "MARK_MOVE" then surrounded stones will be removed
        from the board and (simple) Kos are detected and marked with square
        symbols and "MARK_KO", after removing other marking symbols. The
        markings are also removed with the next next update structure that
        uses "MARK_MOVE", so this flag is suited well for marking, well,
        moves. Note that you can make invalid "moves" (such as suicide) and
        "update" will try to cope with it. You can use "is_valid_move" to
        avoid making illegal moves.

        For handicap "moves", currently only board sizes 9, 13 and 19 are
        supported and only handicap values from 2 to 9. The placement
        follows the IGS rules, if you want other placements, you have to set
        it up yourself.

        This function modifies the $hint member of the specified structure
        to speed up repeated board generation and updates with the same
        update structures.

        If the hint member is a reference the scalar pointed to by the
        reference is updated instead.

        If all this hint member thing is confusing, just ignore it and
        specify it as "undef" or leave it out of the array entirely. Do make
        sure that you keep your update structures around as long as previous
        updates don't change, however, as regenerating a full board position
        from hinted update structures is *much* faster then recreating it
        from fresh update structures.

        Example, make two silly moves:

          $board->update ([[0, 18, -1, MARK_B | MARK_MOVE],
                           [0, 17, -1, MARK_W | MARK_MOVE]]);

    $board->is_valid_move ($colour, $x, $y[, $may_suicide])
        Returns true if the move of the given colour on the given
        coordinates is valid or not. Kos are taken into account as long as
        they are marked with "MARK_KO". Suicides are invalid unless
        $may_suicide is true (e.g. for new zealand rules)

  AUTHOR
    Marc Lehmann <schmorp@schmorp.de>

  SEE ALSO
    Gtk2::GoBoard.

Revision:	1.3
Committed:	Tue Jul 29 10:09:53 2008 UTC (15 years, 9 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_01, HEAD
Changes since 1.2:	+22 -18 lines
Log Message:	1.01
#	User	Rev	Content
1	root	1.1	NAME
2			Games::Go::SimpleBoard - represent a simple go board
3
4			SYNOPSIS
5			use Games::Go::SimpleBoard;
6
7			DESCRIPTION
8			Please supply a description )
9
10			EXPORTED CONSTANTS
11			Marker types for each board position (ORed together):
12
13	root	1.3	MARK_B # normal black stone
14			MARK_W # normal whit stone
15			MARK_GRAYED # in conjunction with MARK_[BW], grays the stone
16
17			MARK_SMALL_B # small stone, used for scoring or marking
18			MARK_SMALL_W # small stone, used for scoring or marking
19			MARK_SMALL_GRAYED # in conjunction with MARK_SMALL_[BW], grays the stone
20
21			MARK_TRIANGLE # triangle mark
22			MARK_SQUARE # square mark
23			MARK_CIRCLE # circle mark
24			MARK_CROSS # cross mark
25
26			MARK_LABEL # a text label
27			MARK_HOSHI # this is a hoshi point (not used much)
28			MARK_MOVE # this is a regular move
29			MARK_KO # this is a ko position
30			MARK_REDRAW # ignored, can be used for your own purposes
31	root	1.1
32	root	1.3	COLOUR_WHITE # guaranteed to be 0
33			COLOUR_BLACK # guaranteed to be 1
34	root	1.2
35	root	1.3	MOVE_HANDICAP # used as "x-coordinate" for handicap moves
36			MOVE_PASS # can be used as "x-coordinate" for pass moves
37	root	1.1
38			METHODS
39			my $board = new $size
40			Creates a new empty board of the given size.
41
42	root	1.2	"$board->{size}" stores the board size.
43
44	root	1.1	"$board->{max}" stores the maximum board coordinate (size-1).
45
46	root	1.2	"$board->{captures}[COLOUR_xxx]" stores the number of captured
47			stones for the given colour.
48	root	1.1
49			"$board->{board}" stores a two-dimensional array with board
50			contents.
51
52	root	1.2	$hint = $board->update ([update-structures...])
53			Each update-structure itself is also an array-ref:
54	root	1.1
55			[$x, $y, $clr, $set, $label, $hint] # update or move
56	root	1.2	[MOVE_HANDICAP, $handicap] # black move, setup handicap
57			[MOVE_PASS] # pass
58			[] # also pass (deprecated!)
59	root	1.1
60	root	1.2	It changes the board or executes a move, by first clearing the bits
61	root	1.1	specified in $clr, then setting bits specified in $set.
62
63			If $set includes "MARK_LABEL", the label text must be given in
64			$label.
65
66	root	1.2	If $set contains "MARK_MOVE" then surrounded stones will be removed
67			from the board and (simple) Kos are detected and marked with square
68			symbols and "MARK_KO", after removing other marking symbols. The
69			markings are also removed with the next next update structure that
70			uses "MARK_MOVE", so this flag is suited well for marking, well,
71			moves. Note that you can make invalid "moves" (such as suicide) and
72			"update" will try to cope with it. You can use "is_valid_move" to
73			avoid making illegal moves.
74
75			For handicap "moves", currently only board sizes 9, 13 and 19 are
76			supported and only handicap values from 2 to 9. The placement
77			follows the IGS rules, if you want other placements, you have to set
78			it up yourself.
79
80			This function modifies the $hint member of the specified structure
81			to speed up repeated board generation and updates with the same
82			update structures.
83	root	1.1
84			If the hint member is a reference the scalar pointed to by the
85			reference is updated instead.
86
87	root	1.2	If all this hint member thing is confusing, just ignore it and
88			specify it as "undef" or leave it out of the array entirely. Do make
89			sure that you keep your update structures around as long as previous
90			updates don't change, however, as regenerating a full board position
91			from hinted update structures is much faster then recreating it
92			from fresh update structures.
93
94	root	1.1	Example, make two silly moves:
95
96	root	1.2	$board->update ([[0, 18, -1, MARK_B \| MARK_MOVE],
97			[0, 17, -1, MARK_W \| MARK_MOVE]]);
98	root	1.1
99			$board->is_valid_move ($colour, $x, $y[, $may_suicide])
100			Returns true if the move of the given colour on the given
101	root	1.2	coordinates is valid or not. Kos are taken into account as long as
102			they are marked with "MARK_KO". Suicides are invalid unless
103			$may_suicide is true (e.g. for new zealand rules)
104	root	1.1
105			AUTHOR
106			Marc Lehmann <schmorp@schmorp.de>
107
108			SEE ALSO
109	root	1.2	Gtk2::GoBoard.
110	root	1.1