.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Games::Go::Sgf2Dg::Diagram 3pm" .TH Games::Go::Sgf2Dg::Diagram 3pm "2019-10-27" "perl v5.30.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Games::Go::Sgf2Dg::Diagram \- Encapsulate a go diagram .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Games::Go::Sgf2Dg::Diagram \& \& my $diagram = Games::Go::Sgf2Dg::Diagram\->new (options); \& $diagram\->put($coords, \*(Aqwhite\*(Aq | \*(Aqblack\*(Aq, ? number ?); \& $diagram\->mark($coords); \& $diagram\->label($coords, \*(Aqa\*(Aq); \& $diagram\->get($coords); \& my $new_diagram = $diagram\->next; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A Games::Go::Sgf2Dg::Diagram object represents a diagram similar to those seen in go textbooks and magazines. Most of the properties defined in \s-1SGF\s0 FF[4] are supported. .PP The caller \fBput\fRs 'white' or 'black' stones (possibly \fBnumber\fRed), on the intersection selected by \f(CW$coords\fR. The caller may \fBmark\fR and \fBlabel\fR intersections and stones. .PP \&\fBput\fR, \fBmark\fR, \fBlabel\fR and \fBproperty\fR are 'actions'. Actions are provisional until the \fBnode\fR method is called. If any provisioanl actions cause a conflict, none of the actions associated with the node are applied, and the \fBnode\fR method either calls a user-defined callback function, or returns an error. .PP When a conflict occurs, the caller should dispose of the current \&\fBDiagram\fR by \fBget\fRting the information from each intersection and doing something (like printing it). Then the caller converts the \&\fBDiagram\fR to the starting point of the next diagram by calling the \&\fBclear\fR method. Alternatively, the caller may save the current \&\fBDiagram\fR and create the starting point for the next diagram by calling the \fBnext\fR method. \fBclear\fR and \fBnext\fR may also be called at arbitrary times (for example, to launch a variation diagram). .PP \&'coords' may be any unique identifier for the intersection. For example: .PP .Vb 4 \& my $coords = \*(Aqqd\*(Aq; # SGF format \& my $coords = \*(Aqa4\*(Aq; # NNGS / IGS style coordinates \& my $coords = "$x,$y"; # real coordinates \& my $coords = \*(AqGeorge\*(Aq; # as long as there\*(Aqs only one George .Ve .SH "NEW" .IX Header "NEW" .ie n .IP "my $diagram = Games::Go::Sgf2Dg::Diagram\->\fBnew\fR (?options?)" 4 .el .IP "my \f(CW$diagram\fR = Games::Go::Sgf2Dg::Diagram\->\fBnew\fR (?options?)" 4 .IX Item "my $diagram = Games::Go::Sgf2Dg::Diagram->new (?options?)" .PP A \fBnew\fR Games::Go::Sgf2Dg::Diagram can take the following options: .IP "\fBhoshi\fR => ['coords', ...]" 8 .IX Item "hoshi => ['coords', ...]" A reference to a list of coordinates where the Diagram should place hoshi points. .IP "\fBblack\fR => ['coords', ...]" 8 .IX Item "black => ['coords', ...]" A reference to a list of coordinates where the Diagram should start with black stones already in place. .IP "\fBwhite\fR => ['coords', ...]" 8 .IX Item "white => ['coords', ...]" A reference to a list of coordinates where the Diagram should start with white stones already in place. .IP "\fBcoord_style\fR => 'normal' | 'sgf' | numeric" 8 .IX Item "coord_style => 'normal' | 'sgf' | numeric" Defines the coordinate translation system. Note that while \&\fBGames::Go::Sgf2Dg::Diagram\fR doesn't use this coordinate system directly, sgf2dg converters may call the coordinate translator methods \fBxcoord\fR and \&\fBycoord\fR, which rely on \fBcoord_style\fR and \fBboardSizeX/Y\fR (below). .Sp Legal values are: .RS 8 .IP "'normal'" 4 .IX Item "'normal'" This is the standard coordinate system used for drawing diagrams: the vertical coordinates start with 1 at the bottom and increase towards the top edge. The horizontal coordinates are letters starting with A on the left, and increasing towards the right, but skipping over 'I'. This is the default coordinate style. .IP "'sgf'" 4 .IX Item "'sgf'" Coordinates within \s-1SGF\s0 files are single letters, lower case first, then upper case. The origin (aa) is the top left corner. 'A' follows 'z', so the point at (26, 27) translates to (zA). .IP "numeric: '++' | '+\-' | '\-+' | '\-\-'" 4 .IX Item "numeric: '++' | '+-' | '-+' | '--'" Number coordinates can be either increasing or decreasing. '++' starts with (0, 0) in the upper left corner, '\-+' has (0, 0) in the upper right corner, etc. .RE .RS 8 .RE .IP "\fBboardSizeX\fR => number" 8 .IX Item "boardSizeX => number" .PD 0 .IP "\fBboardSizeY\fR => number" 8 .IX Item "boardSizeY => number" .PD \&\fBboardSizeX/Y\fR are used by the coordinate translation methods (\fBxcoord\fR and \fBycoord\fR to calculate the appropriate coordinate string. .IP "\fBcallback\fR => \e&user_defined_callback" 8 .IX Item "callback => &user_defined_callback" A reference to a user defined callback function. The user callback is called (with a reference to the \fBDiagram\fR as the only argument) when \fBnode\fR is called after conflict is detected. .Sp The user callback should either save the current \fBDiagram\fR and call , or flush the \fBDiagram\fR (by printing for example) and call . .Sp If the user callback is defined, a call to \fBnode\fR always returns non-zero (the current node number). .IP "\fBenable_overstones\fR => true | false" 8 .IX Item "enable_overstones => true | false" If true (default), overstones are enabled and may be created by the \fBDiagram\fR during a call to the \fBput\fR method. The user must be prepared to deal with overstones information in response to a call to the \fBget\fR method. .SH "METHODS" .IX Header "METHODS" .ie n .IP "$diagram\->\fBclear\fR" 4 .el .IP "\f(CW$diagram\fR\->\fBclear\fR" 4 .IX Item "$diagram->clear" Clears the \fBDiagram\fR. All \fBmark\fRs, \fBlabel\fRs, and \fBnumber\fRs are removed from the stones and intersections. All \fBcapture\fRd stones are removed, and all overstones are deleted (at which point, the \&\fBDiagram\fR is in the same state as a \fBnew\fR \fBDiagram\fR). Pending actions that were not applied due to conflicts are now applied to the \fBclear\fRed \fBDiagram\fR. .Sp The following options are preserved: .RS 4 .IP "\(bu" 4 node (gets incremented) .IP "\(bu" 4 callback .IP "\(bu" 4 enable_overstones .RE .RS 4 .RE .ie n .IP "$diagram\->\fBforce_conflict(? \f(CB$msg\fB ?)\fR" 4 .el .IP "\f(CW$diagram\fR\->\fBforce_conflict(? \f(CB$msg\fB ?)\fR" 4 .IX Item "$diagram->force_conflict(? $msg ?)" Set the conflict flag to force pending actions to be flushed and a new \&\f(CW$diagram\fR created. It's a good idea to pass a short \f(CW$msg\fR explaining the conflict is being created. \f(CW$msg\fR is printed in \-verbose mode of sgf2dg. If no \f(CW$msg\fR is defined, a generic (and probably not very helpful) message is produced. .ie n .IP "my $pending_count = $diagram\->\fBactions_pending\fR" 4 .el .IP "my \f(CW$pending_count\fR = \f(CW$diagram\fR\->\fBactions_pending\fR" 4 .IX Item "my $pending_count = $diagram->actions_pending" Returns the number of actions that would be executed if \fBnode\fR were called. .ie n .IP "my $done_count = $diagram\->\fBactions_done\fR" 4 .el .IP "my \f(CW$done_count\fR = \f(CW$diagram\fR\->\fBactions_done\fR" 4 .IX Item "my $done_count = $diagram->actions_done" Returns the number of actions that have been done for the current \f(CW$diagram\fR. .ie n .IP "my $nextDiagram = $diagram\->\fBnext\fR" 4 .el .IP "my \f(CW$nextDiagram\fR = \f(CW$diagram\fR\->\fBnext\fR" 4 .IX Item "my $nextDiagram = $diagram->next" Creates a new \fBDiagram\fR object starting from the current \&\fBDiagram\fR. \f(CW$nextDiagram\fR is the starting point for the next \&\fBDiagram\fR in a series, or for a variation. .Sp As with the \fBclear\fR method, all \fBcapture\fRd stones are removed, and all overstones are deleted. Pending actions that were not applied due to conflicts are now applied to the \fBnext\fR \fBDiagram\fR. .Sp The following options are preserved: .RS 4 .IP "\(bu" 4 node (gets incremented) .IP "\(bu" 4 callback .IP "\(bu" 4 enable_overstones .IP "\(bu" 4 .RE .RS 4 .RE .ie n .IP "$diagram\->\fBhoshi(@hoshi_coords)\fR" 4 .el .IP "\f(CW$diagram\fR\->\fBhoshi(@hoshi_coords)\fR" 4 .IX Item "$diagram->hoshi(@hoshi_coords)" Adds the coords listed in \f(CW@hoshi_coords\fR 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. .ie n .IP "$diagram\->\fBnode\fR" 4 .el .IP "\f(CW$diagram\fR\->\fBnode\fR" 4 .IX Item "$diagram->node" All actions (\fBput\fR, \fBmark\fR, \fBlabel\fR and \fBproperty\fR) are provisional until \fBnode\fR is called. This makes a collection of actions atomic. A \fBDiagram\fR node is analogous to a Smart Go Format (\s-1SGF\s0) node. If there are no conflicts with the collected provisional actions, \fBnode\fR incorporates them into the \fBDiagram\fR and returns non-zero (the current node number). .Sp If there is a conflict and a user \fBcallback\fR is defined, \fBnode\fR calls the callback with a reference to the \fBDiagram\fR ($diagram) as the only argument. The user callback should either flush the \&\fBDiagram\fR and call \fBclear\fR (to reuse the \fBDiagram\fR) or save the current \fBDiagram\fR, and call \fBnext\fR (to generate a new \fBDiagram\fR). .Sp If there is a conflict and no user \fBcallback\fR is defined, \fBnode\fR returns 0. The user should either: .RS 4 .IP "\(bu" 4 flush the current \fBDiagram\fR and call \f(CW$diagram\fR\->\fBclear\fR to continue working with the current \fBDiagram\fR, or: .IP "\(bu" 4 save the current \fBDiagram\fR (and call \f(CW$diagram\fR\->\fBnext\fR to create a new \fBDiagram\fR to continue working with) .RE .RS 4 .Sp Calling either \fBnext\fR or \fBclear\fR causes the pending collection of conflicting actions to be incorporated into the resulting \&\fBDiagram\fR. .RE .ie n .IP "$diagram\->\fBput\fR ('coords', 'black' | 'white', ? number ? )" 4 .el .IP "\f(CW$diagram\fR\->\fBput\fR ('coords', 'black' | 'white', ? number ? )" 4 .IX Item "$diagram->put ('coords', 'black' | 'white', ? number ? )" \&\fBput\fR a black or white stone on the \fBDiagram\fR at \fBcoords\fR. The stone color is must be 'black' or 'white' (case insensitive, 'b' and \&'w' also work). Optional \fBnumber\fR 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 \fBDiagram\fR. .Sp \&\fBput\fRting can cause any of the following conflicts: .RS 4 .IP "\(bu" 4 stone is numbered and number is already used .IP "\(bu" 4 stone is numbered and the intersection is already labeled .RE .RS 4 .Sp In certain situations, (notably ko and snapbacks but also some other capturing situations), \fBput\fR stones may become overstones. overstones are stones played on an intersection that contains a stone that has been \fBcapture\fRd, but not yet removed from the \&\fBDiagram\fR. There are two kinds of overstones: normal and \&\fBmark\fRed, depending on the state of the underlying (\fBcapture\fRd but not yet removed) stone. .Sp If the underlying stone is \fBnumber\fRed, B>mark>ed or \fBlabel\fRed, the overstone is normal and there will be no conflicts (unless the number is already used!). .Sp If the underlying stone is un\-\fBnumber\fRed and un\-\fBlabel\fRed, the \&\fBDiagram\fR attempts to convert it into a \fBmark\fRed stone. If the conversion succeeds, the overstone becomes a marked overstone, and there is no conflict. .Sp The conversion of the underlying stone causes a conflict if: .IP "\(bu" 4 a stone of the same color as the underlying stone has already been converted elsewhere in the \fBDiagram\fR, or .IP "\(bu" 4 a mark of the same color as the underlying stone exists elsewhere in the \&\fBDiagram\fR. .RE .RS 4 .Sp See the \fBget\fR method for details of how overstone information is returned. .RE .ie n .IP "$diagram\->\fBrenumber\fR($coords, $color, $old_num, $new_num);" 4 .el .IP "\f(CW$diagram\fR\->\fBrenumber\fR($coords, \f(CW$color\fR, \f(CW$old_num\fR, \f(CW$new_num\fR);" 4 .IX Item "$diagram->renumber($coords, $color, $old_num, $new_num);" Changes the number of a stone already on the board. \f(CW$color\fR, and \&\f(CW$old_num\fR must match the existing color and number for the stone at \&\f(CW$coords\fR ($old_num or \f(CW$new_num\fR may be undef for an un-numbered stone). Only the displayed stone is compared for the match, overstones (\fBgame_stone\fRs) are not considered. .Sp Fails and returns 0 if: .RS 4 .IP "\(bu" 4 there is no diagram stone on the intersection, or .IP "\(bu" 4 \&\f(CW$color\fR or \f(CW$old_num\fR don't match, or .IP "\(bu" 4 \&\f(CW$new_num\fR is already used, or .IP "\(bu" 4 a \fBproperty\fR item exists for \f(CW$old_num\fR and \f(CW$new_num\fR is undef .RE .RS 4 .Sp If none of the above, \fBrenumber\fR sets the new number and returns 1. .RE .ie n .IP "my $offset = $diagram\->\fBoffset\fR($new_offset);" 4 .el .IP "my \f(CW$offset\fR = \f(CW$diagram\fR\->\fBoffset\fR($new_offset);" 4 .IX Item "my $offset = $diagram->offset($new_offset);" Set a new offset for the diagram if \f(CW$new_offset\fR is defined. Returns the current value of the offset, or 0 if no offset has been set. .Sp Note that \fBDiagram\fR doesn't use the offset for anything, but external programs (like a converter) can use it to adjust the numbering. .ie n .IP "$diagram\->\fBlabel\fR('coords', 'text');" 4 .el .IP "\f(CW$diagram\fR\->\fBlabel\fR('coords', 'text');" 4 .IX Item "$diagram->label('coords', 'text');" Place a label on an intersection. \fBtext\fR may be any text, but notice that long strings may overflow a stone or intersection. If 'text' is empty ('') any existing label is removed. .Sp The same label can be applied to several intersections only if they are all labeled within a single \fBnode\fR. .Sp 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, \fBlabel\fR causes a conflict. .ie n .IP "$diagram\->\fBmark\fR('coords', ? 'mark_type' ?);" 4 .el .IP "\f(CW$diagram\fR\->\fBmark\fR('coords', ? 'mark_type' ?);" 4 .IX Item "$diagram->mark('coords', ? 'mark_type' ?);" Place a mark on a stone or intersection. The 'mark_type' can be any text, but is usually the \s-1SGF\s0 property: .RS 4 .IP "\s-1CR\s0 circle" 4 .IX Item "CR circle" .PD 0 .IP "\s-1MA\s0 an X mark" 4 .IX Item "MA an X mark" .IP "\s-1SQ\s0 square" 4 .IX Item "SQ square" .IP "\s-1TR\s0 triangle" 4 .IX Item "TR triangle" .RE .RS 4 .PD .Sp If 'mark_type' is not supplied (or undef), \s-1MA\s0 is assumed. .Sp The \fBmark\fR raises a conflict if: .IP "\(bu" 4 the intersection is already \fBlabel\fRled or numbered, or .IP "\(bu" 4 the same color and 'mark_type' already exists in the \fBDiagram\fR for a previous node (possibly from creating an understone). .RE .RS 4 .RE .ie n .IP "my $diagram\->\fBterritory\fR ($propID, $coords);" 4 .el .IP "my \f(CW$diagram\fR\->\fBterritory\fR ($propID, \f(CW$coords\fR);" 4 .IX Item "my $diagram->territory ($propID, $coords);" \&\f(CW$propID\fR should be one of '\s-1TB\s0', '\s-1TW\s0', or undef. \fBterritory\fR marks the intersection \f(CW$coords\fR as being white or black territory (see '\s-1TB\s0', '\s-1TW\s0' in the \fBget\fR method below). If \f(CW$number\fR is undef, any previous territory marking is removed. .ie n .IP "my $diagram\->\fBview\fR ($coords);" 4 .el .IP "my \f(CW$diagram\fR\->\fBview\fR ($coords);" 4 .IX Item "my $diagram->view ($coords);" If \f(CW$coords\fR is defined, then the game-level \s-1VW\s0 property is set, and the intersection at \f(CW$coords\fR is marked as viewable (hash key is '\s-1VW\s0'). If \&\f(CW$coords\fR is '' or undef, then the game-level \s-1VW\s0 property is deleted, and the \s-1VW\s0 mark is removed from all intersections. .ie n .IP "my $nameListRef = $diagram\->\fBname\fR (? name, ... ?)" 4 .el .IP "my \f(CW$nameListRef\fR = \f(CW$diagram\fR\->\fBname\fR (? name, ... ?)" 4 .IX Item "my $nameListRef = $diagram->name (? name, ... ?)" Adds \fBname\fR(s) to the current \fBDiagram\fR. Names accumulate by getting pushed onto a list. .Sp In array context, \fBname\fR returns the current name list. In scalar context, \fBname\fR returns a reference to the list of names. .ie n .IP "$diagram\->\fBproperty\fR ($number, $propName, $propValue, ? $propValue... ?);" 4 .el .IP "\f(CW$diagram\fR\->\fBproperty\fR ($number, \f(CW$propName\fR, \f(CW$propValue\fR, ? \f(CW$propValue\fR... ?);" 4 .IX Item "$diagram->property ($number, $propName, $propValue, ? $propValue... ?);" .PD 0 .ie n .IP "my $prop_ref = $diagram\->\fBproperty\fR ($number);" 4 .el .IP "my \f(CW$prop_ref\fR = \f(CW$diagram\fR\->\fBproperty\fR ($number);" 4 .IX Item "my $prop_ref = $diagram->property ($number);" .ie n .IP "my $all_props_ref = $diagram\->\fBproperty\fR ();" 4 .el .IP "my \f(CW$all_props_ref\fR = \f(CW$diagram\fR\->\fBproperty\fR ();" 4 .IX Item "my $all_props_ref = $diagram->property ();" .PD If \f(CW$propName\fR and \f(CW$propVal\fR are defined, pushes them onto the collection of properties associated with move \f(CW$number\fR. .Sp Note that \fBrenumber\fRing a move also \fBrenumber\fRs the properties. .Sp If \f(CW$number\fR and \f(CW$propName\fR are defined and \f(CW$propValue\fR is not ( or is empty), the \f(CW$propName\fR property is removed. .Sp If \f(CW$number\fR is defined and \f(CW$propName\fR/$propValue are not, \fBproperty\fR returns a reference to the (possibly empty) hash of property IDs and property Values associated with the move number: .Sp .Vb 2 \& my $prop_ref = $diagram\->property($number); \& my $prop_value = $prop_ref\->{$propID}\->[$idx]; .Ve .Sp If \f(CW$number\fR is not defined, returns a reference to the (possibly empty) hash of properties stored in the \fBDiagram\fR. 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 \s-1ID:\s0 .Sp .Vb 2 \& my $all_prop_ref = $diagram\->property(); \& my $prop_value = $all_props_ref\->{$moveNumber}\->{$propID}\->[$idx] .Ve .Sp \&\fBproperty\fR (when \f(CW$propName\fR and \f(CW$propValue\fR are defined) is an action (it is provisional until \fBnode\fR is called) because properties are associated with a node in the \s-1SGF.\s0 However, \fBproperty\fR never causes a conflict. .Sp Note that sgf2dg stores the following properties: .Sp .Vb 10 \& propID number propVal comment \& \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\- \& Move properties \& W[] or W[tt] move \*(Aqpass\*(Aq white pass \& B[] or B[tt] move \*(Aqpass\*(Aq black pass \& KO move \*(Aq\*(Aq force move \& PL[W|B] move \*(AqW\*(Aq | \*(AqB\*(Aq set player \& Node annotation properties \& C[text] move text move comment \& DM[dbl] move 0 | 1 Even position \& GB[dbl] move 0 | 1 Good for black \& GW[dbl] move 0 | 1 Good for white \& HO[dbl] move 0 | 1 Hotspot \& UC[dbl] move 0 | 1 Unclear \& N[stxt] move simple_text Name (node name) \& V[real] move real Value (estimated game score) \& Move annotation properties \& BM[dbl] move 0 | 1 Bad move \& DO move \*(Aq\*(Aq Doubtful move \& IT move \*(Aq\*(Aq Interesting move \& TE[dbl] move 0 | 1 Tesuji (good move) \& Markup properties \& AR[c_pt] move \*(Aqpt:pt\*(Aq Arrow \& DD[elst] move \*(Aqpt?\*(Aq Dim points: DD[] clears \& LN[c_pt] move \*(Aqpt:pt\*(Aq Line \& SL[lst] move \*(Aqpt\*(Aq Select points (markup unknown) \& Root properties \& AP[stxt:stxt] 0 \*(Aqstxt:stxt\*(Aq Application_name:version \& CA[stxt] 0 \*(Aqcharset\*(Aq character set \& FF[1\-4] 0 0 \- 4 FileFormat \& GM[1\-16] 0 0 \- 16 Game \& ST[0\-3] 0 0 \- 3 How to show variations (style?) \& Game info properties \& AN[stxt] 0 simple_text Annotater (name) \& BT[stxt] 0 simple_text Black team \& WT[stxt] 0 simple_text White team \& CP[stxt] 0 simple_text Copyright \& ON[stxt] 0 simple_text Opening information \& OT[stxt] 0 simple_text Overtime description (byo\-yomi) \& PC[stxt] 0 simple_text Place game was played \& RE[stxt] 0 simple_text Result \& RO[stxt] 0 simple_text Round \& RU[stxt] 0 simple_text Rules \& SO[stxt] 0 simple_text Source \& US[stxt] 0 simple_text User/program who entered the game \& GC[text] 0 text Game comment \& TM[real] 0 real_number Time limits \& Timing properties \& BL[real] move real_number BlackLeft (time) \& WL[real] move real_number WhiteLeft (time) \& OB[num] move number Black moves left (after this move) \& OW[num] move number White moves left \& Go\-specific properties \& HA[num] 0 number Handicap \& KM[real] 0 real_number Komi \& Misc. properties \& PM[num] move number Print mode \- see FF4 spec \& BS[stext] move stext BlackSpecies (deprecated) \& WS[stext] move stext WhiteSpecies (deprecated) \& FG[pt:stext] move bitmask:stext Figure: see FF4 spec .Ve .ie n .IP "@title_lines = $diagram\->\fBgameProps_to_title\fR (\e&emph_sub)" 4 .el .IP "\f(CW@title_lines\fR = \f(CW$diagram\fR\->\fBgameProps_to_title\fR (\e&emph_sub)" 4 .IX Item "@title_lines = $diagram->gameProps_to_title (&emph_sub)" \&\fBgameProps_to_title\fR converts game (node 0) properties extracted from the \&\s-1SGF\s0 file. The properties are scanned in the order listed here: .RS 4 .IP "\s-1GN\s0 GameName" 4 .IX Item "GN GameName" .PD 0 .IP "\s-1EV\s0 EVent" 4 .IX Item "EV EVent" .IP "\s-1RO\s0 ROund (joined to EVent)" 4 .IX Item "RO ROund (joined to EVent)" .IP "\s-1DT\s0 DaTe" 4 .IX Item "DT DaTe" .IP "\s-1PC\s0 PlaCe" 4 .IX Item "PC PlaCe" .ie n .IP "\s-1PW\s0 PlayerWhite ""White:""" 4 .el .IP "\s-1PW\s0 PlayerWhite ``White:''" 4 .IX Item "PW PlayerWhite White:" .IP "\s-1WR\s0 WhiteRank (joined to \s-1PW\s0)" 4 .IX Item "WR WhiteRank (joined to PW)" .ie n .IP "\s-1PB\s0 PlayerBlack ""Black""" 4 .el .IP "\s-1PB\s0 PlayerBlack ``Black''" 4 .IX Item "PB PlayerBlack Black" .IP "\s-1BR\s0 BlackRank (joined to \s-1PB\s0)" 4 .IX Item "BR BlackRank (joined to PB)" .ie n .IP "\s-1KM\s0 KoMi ""Komi:""" 4 .el .IP "\s-1KM\s0 KoMi ``Komi:''" 4 .IX Item "KM KoMi Komi:" .ie n .IP "\s-1RU\s0 RUles ""Rules:""" 4 .el .IP "\s-1RU\s0 RUles ``Rules:''" 4 .IX Item "RU RUles Rules:" .ie n .IP "\s-1TM\s0 TiMe ""Time:""" 4 .el .IP "\s-1TM\s0 TiMe ``Time:''" 4 .IX Item "TM TiMe Time:" .ie n .IP "\s-1OT\s0 OverTime (byo-yomi) ""Byo-yomi:""" 4 .el .IP "\s-1OT\s0 OverTime (byo-yomi) ``Byo-yomi:''" 4 .IX Item "OT OverTime (byo-yomi) Byo-yomi:" .ie n .IP "\s-1RE\s0 REsult ""Result:""" 4 .el .IP "\s-1RE\s0 REsult ``Result:''" 4 .IX Item "RE REsult Result:" .ie n .IP "\s-1AN\s0 ANnotator ""Annotated by:""" 4 .el .IP "\s-1AN\s0 ANnotator ``Annotated by:''" 4 .IX Item "AN ANnotator Annotated by:" .ie n .IP "\s-1SO\s0 Source ""Source:""" 4 .el .IP "\s-1SO\s0 Source ``Source:''" 4 .IX Item "SO Source Source:" .ie n .IP "\s-1US\s0 USer ""Entered by:""" 4 .el .IP "\s-1US\s0 USer ``Entered by:''" 4 .IX Item "US USer Entered by:" .IP "\s-1CP\s0 CoPyright" 4 .IX Item "CP CoPyright" .IP "\s-1GC\s0 GameComment" 4 .IX Item "GC GameComment" .RE .RS 4 .PD .Sp For each property that is found, a line is added to the \f(CW@title_lines\fR return array. If the property has a string in double-quotes in the list above, that string (plus one space) is prefixed to the property text. In addition, if \e&emph_sub is defined, the prefix is passed to &$emph_sub to make those portions appear emphasized in the title lines. Example: .Sp .Vb 1 \& my @title = $diagram\->gameProps_to_title(sub { "{\e\ebf $_[0]}" }); .Ve .Sp wraps portions of the title line in TeX's bold-face (bf) style. .RE .ie n .IP "$diagram\->\fBcapture\fR ('coords')" 4 .el .IP "\f(CW$diagram\fR\->\fBcapture\fR ('coords')" 4 .IX Item "$diagram->capture ('coords')" Captures the stone at the intersection. .Sp Note that \fBcapture\fR has no visible affect on the diagram. Rather, it marks the stone so that it is removed when creating the \fBnext\fR \&\fBDiagram\fR. .Sp \&\fBcapture\fR is not considered an action because it cannot cause a conflict or change the visible status of the board. .ie n .IP "$diagram\->\fBremove\fR ('coords')" 4 .el .IP "\f(CW$diagram\fR\->\fBremove\fR ('coords')" 4 .IX Item "$diagram->remove ('coords')" Removes the stone at the intersection. .Sp Unlike \fBcapture\fR, \fBremove\fR changes the visible status of the \&\fBDiagram\fR: the stone is deleted, along with all marks and letters (only the 'hoshi', if any, is retained). .Sp \&\fBremove\fR 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 (\s-1AE\s0) \s-1SGF\s0 property. .ie n .IP "my $stone = $diagram\->\fBgame_stone\fR(coords | $intersection);" 4 .el .IP "my \f(CW$stone\fR = \f(CW$diagram\fR\->\fBgame_stone\fR(coords | \f(CW$intersection\fR);" 4 .IX Item "my $stone = $diagram->game_stone(coords | $intersection);" Returns 'black' or 'white' if there is a stone currently on the coords or intersection (a reference to an intersection, such as is returned by \&\f(CW$diagram\fR\->\fBget\fR) , otherwise returns undef. .Sp Note that the return value is determined by the game perspective, not the diagram perspective. If a stone is \fBput\fR and later \fBcapture\fRd, \&\fBgame_stone\fR returns undef even though the diagram should still show the original stone. If a white stone is \fBput\fR and later \fBcapture\fRd, and then a black stone is \fBput\fR, \fBgame_stone\fR returns 'black', and \fBget\fR indicates that a white stone should be displayed on the diagram. .Sp Note also that since \fBput\fR is provisional until \fBnode\fR is called. If you use \fBgame_stone\fR to check for liberties and captures, it must be done \&\fIafter\fR the call to \fBnode\fR that realizes the \fBput\fR. .ie n .IP "$diagram\->\fBget\fR ('coords')" 4 .el .IP "\f(CW$diagram\fR\->\fBget\fR ('coords')" 4 .IX Item "$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. .Sp Only keys that have been applied are returned \- an empty hash means an empty intersection. .Sp The hash keys can be any of: .RS 4 .IP "'hoshi'" 4 .IX Item "'hoshi'" This intersection is a hoshi point. Note that since hoshi points are determined at \fBnew\fR time, the value of this hash entry is always 0. This key is returned even if a stone has been placed on the intersection. .IP "'white'" 4 .IX Item "'white'" The color of a stone at this intersection. .IP "'black'" 4 .IX Item "'black'" The color of a stone at this intersection. .IP "'number'" 4 .IX Item "'number'" The hash value is the number on the stone. The node for \&\fBnumber\fR is found in the 'black' or 'white' hash value. .IP "'capture'" 4 .IX Item "'capture'" The stone on this intersection has been \fBcapture\fRd, the intersection is currently empty from the perspective of the game. .IP "'mark'" 4 .IX Item "'mark'" The intersection or stone is marked. The value indicates the type of mark, usually the \s-1SGF\s0 property: .RS 4 .IP "\s-1CR\s0 circle" 4 .IX Item "CR circle" .PD 0 .IP "\s-1MA\s0 an X mark" 4 .IX Item "MA an X mark" .IP "\s-1SQ\s0 square" 4 .IX Item "SQ square" .IP "\s-1TR\s0 triangle" 4 .IX Item "TR triangle" .RE .RS 4 .RE .IP "'label'" 4 .IX Item "'label'" .PD The intersection has been labeled. The value indicates the text of the label. .IP "'overstones'" 4 .IX Item "'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 \&\fBDiagram\fR. .Sp The hash value is a reference to an array of color/number pairs. The colors and numbers were passed to the \fBput\fR method which decided to convert the stone into an overstone. .Sp This is typically seen as notes to the side of the diagram saying something like \*(L"black 33 was played at the marked white stone\*(R". In this example. the information returned by \fBget\fR describes 'the marked white stone', while 'black' will be the first item in the \&'overstones' array, and '33' will be the second: .Sp .Vb 3 \& $diagram\->get($coords) == {white => node_number, \& overstones => [\*(Aqblack\*(Aq, 33], \& ...} .Ve .IP "'\s-1TB\s0' or '\s-1TW\s0'" 4 .IX Item "'TB' or 'TW'" Intersection has been marked as black or white territory with a \s-1TB\s0 or \s-1TW\s0 property. .IP "'view'" 4 .IX Item "'view'" Set when the intersection is marked with a \s-1VW\s0 view property. Relates to the \s-1VW\s0 game \fBproperty\fR: .Sp .Vb 4 \& if ((not $diagram\->property(0)\->VW) or # no game\-level VieW property \& $intersection\->{view}) { # this intersection is viewable \& # display this intersection \& } .Ve .RE .RS 4 .Sp The hash reference returned by \fBget\fR points to the data in the \&\fBDiagram\fR object \- don't change it unless you know what you are doing. .RE .ie n .IP "my $coord_string = $diagram\->\fBxcoord\fR($x)" 4 .el .IP "my \f(CW$coord_string\fR = \f(CW$diagram\fR\->\fBxcoord\fR($x)" 4 .IX Item "my $coord_string = $diagram->xcoord($x)" .PD 0 .ie n .IP "my $coord_string = $diagram\->\fBycoord\fR($y)" 4 .el .IP "my \f(CW$coord_string\fR = \f(CW$diagram\fR\->\fBycoord\fR($y)" 4 .IX Item "my $coord_string = $diagram->ycoord($y)" .PD Returns a string to display for a given \f(CW$x\fR or \f(CW$y\fR coordinate. The string returned depends not only on the \f(CW$x\fR or \f(CW$y\fR value, but also on the \&\fBcoords_style\fR and \fBboardSizeX/Y\fR configuration options, .ie n .IP "my $first_number = $diagram\->\fBfirst_number\fR" 4 .el .IP "my \f(CW$first_number\fR = \f(CW$diagram\fR\->\fBfirst_number\fR" 4 .IX Item "my $first_number = $diagram->first_number" Returns the lowest number \fBput\fR on the \fBDiagram\fR, or 0 if no numbered stones have been \fBput\fR. .ie n .IP "my $last_number = $diagram\->\fBlast_number\fR" 4 .el .IP "my \f(CW$last_number\fR = \f(CW$diagram\fR\->\fBlast_number\fR" 4 .IX Item "my $last_number = $diagram->last_number" Returns the highest number \fBput\fR on the \fBDiagram\fR, or 0 if no numbered stones have been \fBput\fR. .ie n .IP "my $parentDiagram = $diagram\->\fBparent\fR (? $parent ?)" 4 .el .IP "my \f(CW$parentDiagram\fR = \f(CW$diagram\fR\->\fBparent\fR (? \f(CW$parent\fR ?)" 4 .IX Item "my $parentDiagram = $diagram->parent (? $parent ?)" If \f(CW$parent\fR is defined, sets the \fBparent\fR for this diagram. .Sp Always returns the current value of \fBparent\fR (possibly undef). .ie n .IP "my $move_number = $diagram\->\fBvar_on_move\fR (? $new_number ?)" 4 .el .IP "my \f(CW$move_number\fR = \f(CW$diagram\fR\->\fBvar_on_move\fR (? \f(CW$new_number\fR ?)" 4 .IX Item "my $move_number = $diagram->var_on_move (? $new_number ?)" If \f(CW$new_number\fR is defined, sets the \fBvar_on_move\fR for this diagram. This is intended to be used in conjunction with the information to title diagrams such as .Sp .Vb 4 \& my $title = "Variation 2 on move " . \& $diagram\->var_on_move . \& " in " . \& $diagram\->parent\->name; .Ve .Sp Always returns the current value of \fBvar_on_move\fR (possibly undef). .ie n .IP "my $overListRef = $diagram\->\fBgetoverlist\fR" 4 .el .IP "my \f(CW$overListRef\fR = \f(CW$diagram\fR\->\fBgetoverlist\fR" 4 .IX Item "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 \fBget\fR method. .Sp The list is sorted by the order the intersections first had an overstone \fBput\fR on. If there are no intersections with overstones, returns a reference to an empty list. .ie n .IP "my $user = $diagram\->\fBuser\fR ( ? $new_user ? )" 4 .el .IP "my \f(CW$user\fR = \f(CW$diagram\fR\->\fBuser\fR ( ? \f(CW$new_user\fR ? )" 4 .IX Item "my $user = $diagram->user ( ? $new_user ? )" If \f(CW$new_user\fR is defined, sets the \fBuser\fR value for the \fBDiagram\fR. Note that the \fBuser\fR is not used within \fBDiagram\fR, but can be used by external code for any purpose. Most useful is probably if \&\f(CW$new_user\fR is a reference to a hash of user-defined items of interest. .Sp Returns the current \fBuser\fR value (default is undef). .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "sgf2dg(1)" 4 .IX Item "sgf2dg(1)" Script to convert \s-1SGF\s0 format files to Go diagrams .SH "BUGS" .IX Header "BUGS" With the current architecture, conflicts within a node are not detected. I think this would probably be malformed \s-1SGF.\s0 This deficiency could be fixed by adding a 'shadow' diagram to which provisional actions are applied.