Provided by: sgf2dg_4.026-10build1_amd64 bug

NAME

       Games::Go::Diagram - Perl extension to make go diagrams similar to printed diagrams

SYNOPSIS

        use Games::Go::Diagram

        my $diagram = Games::Go::Diagram->new (options);
        $diagram->put($coords, 'white' | 'black', ? number ?);
        $diagram->mark($coords);
        $diagram->label($coords, 'a');
        $diagram->get($coords);
        my $new_diagram = $diagram->next;

DESCRIPTION

       A Games::Go::Diagram object represents a diagram similar to those seen in go textbooks and
       magazines.  The caller puts 'white' or 'black' stones (possibly numbered), on the
       intersection selected by $coords.  The caller may also mark and label intersections and
       stones.

       putting, marking, labeling and propertying are 'actions'.  Actions are provisional until
       the node method is called.  If any provisioanl actions cause a conflict, none of the
       actions associated with the node are applied, and the node method either calls a user-
       defined callback function, or returns an error.

       When a conflict occurs, the caller should dispose of the current Diagram by getting the
       information from each intersection and doing something (like printing it).  Then the
       caller converts the Diagram to the starting point of the next diagram by calling the clear
       method.  Alternatively, the caller may save the current Diagram and create the starting
       point for the next diagram by calling the next method.  clear and next may also be called
       at arbitrary times (for example, to launch a variation diagram).

       'coords' may be any unique identifier for the intersection.  For example:

           my $coords = 'qd';          # SGF format
           my $coords = 'a4';          # NNGS / IGS style coordinates
           my $coords = "$x,$y";       # real coordinates
           my $coords = 'George';      # as long as there's only one George

METHODS

       my $diagram = Games::Go::Diagram->new (?options?)
           A new Games::Go::Diagram can take the following options:

           Options:

           hoshi => ['coords', ...]
               A reference to a list of coordinates where the Diagram should place hoshi points.

           black => ['coords', ...]
               A reference to a list of coordinates where the Diagram should start with black
               stones already in place.

           white => ['coords', ...]
               A reference to a list of coordinates where the Diagram should start with white
               stones already in place.

           callback => \&user_defined_callback
               A reference to a user defined callback function.  The user callback is called
               (with a reference to the Diagram as the only argument) when node is called after
               conflict is detected.

               The user callback should either save the current Diagram and call <next>, or flush
               the Diagram (by printing for example) and call <clear>.

               If the user callback is defined, a call to node always returns non-zero (the
               current node number).

           enable_overstones => true | false
               If true (default), overstones are enabled and may be created by the Diagram during
               a call to the put method.  The user must be prepared to deal with overstones
               information in response to a call to the get method.

           overstone_eq_mark => true | false
               If true (default), overstones are assumed to be indistinguishable from marks which
               means there can be conflicts between marks and overstones.  If false, marks and
               overstones are assumed to use different symbols and there are no conflicts between
               them.

       $diagram->clear
           Clears the Diagram.  All marks, labels, and numbers are removed from the stones and
           intersections.  All captured stones are removed, and all overstones are deleted (at
           which point, the Diagram is in the same state as a new Diagram).  Pending actions that
           were not applied due to conflicts are now applied to the cleared Diagram.

           The following options are preserved:

           •   node    (gets incremented)

           •   callback

           •   enable_overstones

           •   overstone_eq_mark

       my $nextDiagram = $diagram->next
           Creates a new Diagram object starting from the current Diagram.  $nextDiagram is the
           starting point for the next Diagram in a series, or for a variation.

           As with the clear method, all captured stones are removed, and all overstones are
           deleted.  Pending actions that were not applied due to conflicts are now applied to
           the next Diagram.

           The following options are preserved:

           •   node    (gets incremented)

           •   callback

           •   enable_overstones

           •   overstone_eq_mark

       $diagram->hoshi(@hoshi_coords)
           Adds the coords listed in @hoshi_coords to any existing hoshi points.  In array
           context, returns the list of coords that are hoshi points.  In scalar context, returns
           a reference to the list.

       $diagram->node
           All actions (put, mark, label and property) are provisional until node is called.
           This makes a collection of actions atomic.  A Diagram node is analogous to a Smart Go
           Format (SGF) node.  If there are no conflicts with the collected provisional actions,
           node incorporates them into the Diagram and returns non-zero (the current node
           number).

           If there is a conflict and a user callback is defined, node calls the callback with a
           reference to the Diagram ($diagram) as the only argument.  The user callback should
           either flush the Diagram and call clear (to reuse the Diagram) or save the current
           Diagram, and call next (to generate a new Diagram).

           If there is a conflict and no user callback is defined, node returns 0.  The user
           should either:

           •   flush the current Diagram and call $diagram->clear to continue working with the
               current Diagram, or:

           •   save the current Diagram (and call $diagram->next to create a new Diagram to
               continue working with)

           Calling either next or clear causes the pending collection of conflicting actions to
           be incorporated into the resulting Diagram.

       $diagram->put ('coords', 'black' | 'white',  ? number ? )
           put a black or white stone on the Diagram at coords.  The stone color is must be
           'black' or 'white' (case insensitive, 'b' and 'w' also work).  Optional number is the
           number on the stone.  If not defined, the stone is un-numbered (which is probably a
           mistake except at the very start of a Diagram.

           putting can cause any of the following conflicts:

           •   stone is numbered and number is already used

           •   stone is numbered and the intersection is already labeled

           In certain situations, (notably ko and snapbacks but also some other capturing
           situations), put stones may become overstones.  overstones are stones played on an
           intersection that contains a stone that has been captured, but not yet removed from
           the Diagram.  There are two kinds of overstones: normal and marked, depending on the
           state of the underlying (captured but not yet removed) stone.

           If the underlying stone is numbered or labeled, the overstone is normal and there will
           be no conflicts (unless the number is already used!).

           If the underlying stone is un-numbered and un-labeled, the Diagram attempts to convert
           it into a marked stone.  If the conversion succeeds, the overstone becomes a marked
           overstone, and there is no conflict.

           The conversion of the underlying stone causes a conflict if:

           •   a stone of the same color as the underlying stone has already been converted
               elsewhere in the Diagram, or

           •   overstone_eq_mark is true and a mark of the same color as the underlying stone
               exists elsewhere in the Diagram.

           See the get method for details of how overstone information is returned.

       $diagram->renumber($coords, $color, $old_num, $new_num);
           Changes the number of a stone already on the board.  $color, and $old_num must match
           the existing color and number for the stone at $coords ($old_num or $new_num may be
           undef for an un-numbered stone).  Only the displayed stone is compared for the match,
           overstones (game_stones) are not considered.

           Fails and returns 0 if:

           •   there is no diagram stone on the intersection, or

           •   $color or $old_num don't match, or

           •   $new_num is already used, or

           •   a property item exists for $old_num and $new_num is undef

           If none of the above, renumber sets the new number and returns 1.

       my $offset = $diagram->offset($new_offset);
           Set a new offset for the diagram if $new_offset is defined.  Returns the current value
           of the offset, or 0 if no offset has been set.

           Note that Diagram doesn't use the offset for anything, but external programs (like a
           converter) can use it to adjust the numbering.

       $diagram->label('coords', 'char');
           Place a label on an intersection.  char must be a single letter from A to Z or from a
           to z.

           The same label can be applied to several intersections only if they are all labeled
           within a single node.

           If the intersection or stone is already labeled, or occupied by a marked, or numbered
           stone, or if the label has already been used outside the labeling group, label causes
           a conflict.

       $diagram->mark('coords');
           Place a mark on a stone (empty intersections cannot be marked).

           The mark can be applied to several stones only if they are either:

           •   different color stones (black, white)

           •   all marked within one node.

           The mark causes a conflict if:

           •   the stone is a labelled or numbered stone, or

           •   the same color mark already exists in the Diagram for a different marking group,
               or

           •   overstone_eq_mark is true and there is already an overstone of the same color in
               the Diagram.

       my $nameListRef = $diagram->name (? name, ... ?)
           Adds name(s) to the current Diagram.  Names accumulate by getting pushed onto a list.

           In array context, name returns the current name list.  In scalar context, name returns
           a reference to the list of names.

       $diagram->property ($number, $propName, $propValue, ? $propValue... ?);
       my $prop_ref = $diagram->property ($number);
       my $all_props_ref = $diagram->property ();
           If $propName and $propVal are defined, pushes them onto the collection of properties
           associated with move $number.

           Note that renumbering a move also renumbers the properties.

           If $number is defined and $propName/$propValue are not, property returns a reference
           to the (possibly empty) hash of property IDs and property Values associated with the
           move number:

               my $prop_value = $prop_ref->{$propID}->[$idx].

           If $number is not defined, returns a reference to the (possibly empty) hash of
           properties stored in the Diagram.  Hash keys are the move number, and each hash value
           is in turn a hash.  The keys of the property hashes are (short) property IDs and the
           hash values are lists of property values for each property ID:

               my $prop_value = $all_props_ref->{$moveNumber}->{$propID}->[$idx]

           property (when $propName and $propValue are defined) is an action (it is provisional
           until node is called) because properties are associated with a node in the SGF.
           However, property never causes a conflict.

       $diagram->capture ('coords')
           Captures the stone at the intersection.

           Note that capture has no visible affect on the diagram.  Rather, it marks the stone so
           that it is removed when creating the next Diagram.

           capture is not considered an action because it cannot cause a conflict or change the
           visible status of the board.

       $diagram->remove ('coords')
           Removes the stone at the intersection.

           Unlike capture, remove changes the visible status of the Diagram: the stone is
           deleted, along with all marks and letters (only the 'hoshi', if any, is retained).

           remove is typically used at the start of a variation to remove any stones that are
           improperly placed for the variation.  It is closely related to the AddEmpty (AE) SGF
           property.

       my $stone = $diagram->game_stone(coords);
           Returns 'black' or 'white' if there is a stone currently on the intersection,
           otherwise returns undef.

           Note that the return value is determined by the game perspective, not the diagram
           perspective.  If a stone is put and later captured, game_stone returns undef even
           though the diagram should still show the original stone.  If a white stone is put and
           later captured, and then a black stone is put, game_stone returns 'black', and get
           indicates that a white stone should be displayed on the diagram.

           Note also that since put is provisional until node is called.  If you use game_stone
           to check for liberties and captures, it must be done after the call to node that
           realizes the put.

       $diagram->get ('coords')
           Return the current status of the intersection.  Status is returned as a reference to a
           hash.  The keys of the hash indicate the items of interest, and the values of the hash
           are the indices where the item was applied, except where noted below.

           Only keys that have been applied are returned - an empty hash means an empty
           intersection.

           The hash keys can be any of:

           'hoshi'
               This intersection is a hoshi point.  Note that since hoshi points are determined
               at new time, the value of this hash entry is always 0.  This key is returned even
               if a stone has been placed on the intersection.

           'white'
               The color of a stone at this intersection.

           'black'
               The color of a stone at this intersection.

           'number'
               The hash value is the number on the stone.  The node for number is found in the
               'black' or 'white' hash value.

           'capture'
               The stone on this intersection has been captured, the intersection is currently
               empty from the perspective of the game.

           'mark'
               The intersection or stone is marked.

           'overstone'
               If overstone_eq_mark is false, this hash entry gets the current node when an un-
               numbered, un-labeled stone is converted to an overstone.  If overstone_eq_mark is
               false, this hash entry is never set (under the same circumstances, the
               intersection is 'mark'ed instead).

           'label'
               The hash key is the word 'label', and the value is the single character passed to
               the label method.  Note that the node can be retrieved with:

                   my $intersection = $diagram->get;
                   my $label = $intersection->{label};
                   my $label_node = $intersection->{$label};

           label
               The hash key is the single character a-z or A-Z that is the label for this
               intersection or stone.  The hash value is the node.

           'overstones'
               If this hash entry exists it means that one or more stones were overlayed on the
               stone that is currently displayed on this intersection of the Diagram.

               The hash value is a reference to an array of color/number pairs.  The colors and
               numbers were passed to the put method which decided to convert the stone into an
               overstone.

               This is typically seen as notes to the side of the diagram saying something like
               "black 33 was played at the marked white stone".  In this example. the information
               returned by get describes 'the marked white stone', while 'black' will be the
               first item in the 'overstones' array, and '33' will be the second.

           The hash reference returned by get points to the data in the Diagram object - don't
           change it unless you know what you are doing.

       my $first_number = $diagram->first_number
           Returns the lowest number put on the Diagram, or 0 if no numbered stones have been
           put.

       my $last_number = $diagram->last_number
           Returns the highest number put on the Diagram, or 0 if no numbered stones have been
           put.

       my $parentDiagram = $diagram->parent (? $parent ?)
           If $parent is defined, sets the parent for this diagram.

           Always returns the current value of parent (possibly undef).

       my $move_number = $diagram->var_on_move (? $new_number ?)
           If $new_number is defined, sets the var_on_move for this diagram.  This is intended to
           be used in conjunction with the <Bparent> information to title diagrams such as

               my $title = "Variation 2 on move " .
                           $diagram->var_on_move .
                           " in " .
                           $diagram->parent->name;

           Always returns the current value of var_on_move (possibly undef).

       my $overListRef = $diagram->getoverlist
           Returns a reference to the list of intersections with overstones.  The list members
           are the same intersection hash references returned by the get method.

           The list is sorted by the order the intersections first had an overstone put on.  If
           there are no intersections with overstones, returns a reference to an empty list.

       my $user = $diagram->user ( ? $new_user ? )
           If $new_user is defined, sets the user value for the Diagram.  Note that the user is
           not used within Diagram, but can be used by external code for any purpose.  Most
           useful is probably if $new_user is a reference to a hash of user-defined items of
           interest.

           Returns the current user value (default is undef).

SEE ALSO

       sgf2dg(1)
           Script to convert SGF format files to Go diagrams

BUGS

       With the current architecture, conflicts within a node are not detected.  I think this
       would probably be malformed SGF.  This deficiency could be fixed by adding a 'shadow'
       diagram to which provisional actions are applied.

AUTHOR

       Reid Augustin, <reid@netchip.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2005 by Reid Augustin

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of
       Perl 5 you may have available.