.\" 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::Dg2SL 3pm"
.TH Games::Go::Sgf2Dg::Dg2SL 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::Dg2SL \- Perl extension to convert Games::Go::Sgf2Dg::Diagrams to Sensei's Library format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Games::Go::Sgf2Dg::Dg2SL
.PP
.Vb 2
\& my $dg2sl = B<Games::Go::Sgf2Dg::Dg2SL\-E<gt>new> (options);
\& my $sl = $dg2sl\->convertDiagram($diagram);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Games::Go::Sgf2Dg::Dg2SL object converts a Games::Go::Sgf2Dg::Diagram object into
Sensei's Library diagrams (see http://senseis.xmp.net/).
.PP
Sensei's Library diagrams only support move numbers from 1\-10, so make sure
you call sgf2dg with arguments that specify a maximum of 10 moves per diagram
and starting each diagram with move number 1. Example:
.PP
.Vb 1
\&  sgf2dg \-converter SL \-m 10 \-n foo.sgf
.Ve
.PP
Sensei's Library also doesn't support labelled stones.
.PP
An initial setup diagram is printed if the initial board isn't empty and
doesn't have a handicap setup \- i.e., only black stones, all of which are on
hoshi points.
.PP
Diagrams' extents are limited to the stones actually played, plus a margin.
That is, if there are only stones in one corner, only that corner is printed,
not the whole diagram. This is useful for analyses of local positions, but
if the first ten moves of a real game are all in one corner \- however
unlikely that may be \-, it would produce undesirable results.
.SH "NEW"
.IX Header "NEW"
.ie n .IP "my $dg2sl = \fBGames::Go::Sgf2Dg::Dg2SL\->new\fR (?options?)" 4
.el .IP "my \f(CW$dg2sl\fR = \fBGames::Go::Sgf2Dg::Dg2SL\->new\fR (?options?)" 4
.IX Item "my $dg2sl = Games::Go::Sgf2Dg::Dg2SL->new (?options?)"
.PP
A \fBnew\fR Games::Go::Sgf2Dg::Dg2SL takes the following options:
.IP "\fBboardSize\fR => number" 8
.IX Item "boardSize => number"
Sets the size of the board.
.Sp
Default: 19
.IP "\fBcoords\fR => true | false" 8
.IX Item "coords => true | false"
Generates a coordinate grid.
.Sp
Default: false
.IP "\fBtopLine\fR     => number (Default: 1)" 8
.IX Item "topLine => number (Default: 1)"
.PD 0
.IP "\fBbottomLine\fR  => number (Default: 19)" 8
.IX Item "bottomLine => number (Default: 19)"
.IP "\fBleftLine\fR    => number (Default: 1)" 8
.IX Item "leftLine => number (Default: 1)"
.IP "\fBrightLine\fR   => number (Default: 19)" 8
.IX Item "rightLine => number (Default: 19)"
.PD
The edges of the board that should be displayed.  Any portion of the
board that extends beyond these numbers is not included in the
output.
.ie n .IP "\fBdiaCoords\fR => sub { # convert $x, $y to Games::Go::Sgf2Dg::Diagram coordinates }" 8
.el .IP "\fBdiaCoords\fR => sub { # convert \f(CW$x\fR, \f(CW$y\fR to Games::Go::Sgf2Dg::Diagram coordinates }" 8
.IX Item "diaCoords => sub { # convert $x, $y to Games::Go::Sgf2Dg::Diagram coordinates }"
This callback defines a subroutine to convert coordinates from \f(CW$x\fR,
\&\f(CW$y\fR to whatever coordinates are used in the Games::Go::Sgf2Dg::Diagram
object.  The default \fBdiaCoords\fR converts 1\-based \f(CW$x\fR, \f(CW$y\fR to the
same coordinates used in \s-1SGF\s0 format files.  You only need to define
this if you're using a different coordinate system in the Diagram.
.Sp
Default:
    sub { my ($x, \f(CW$y\fR) = \f(CW@_\fR;
          \f(CW$x\fR = chr($x \- 1 + ord('a')); # convert 1 to 'a', etc
          \f(CW$y\fR = chr($y \- 1 + ord('a'));
          return \*(L"$x$y\*(R"; },           # concatenate two letters
.Sp
See also the \fBdiaCoords\fR method below.
.ie n .IP "\fBfile\fR => 'filename' | $descriptor | \e$string | \e@array" 8
.el .IP "\fBfile\fR => 'filename' | \f(CW$descriptor\fR | \e$string | \e@array" 8
.IX Item "file => 'filename' | $descriptor | $string | @array"
If \fBfile\fR is defined, the Sensei's Library diagram is dumped into the target.
The target can be any of:
.RS 8
.IP "filename" 4
.IX Item "filename"
The filename will be opened using IO::File\->new. The filename should include
the '>' or '>>' operator as described in 'perldoc IO::File'. The Sensei's
Library diagram is written into the file.
.IP "descriptor" 4
.IX Item "descriptor"
A file descriptor as returned by IO::File\->new, or a \e*FILE descriptor. The
Sensei's Library diagram is written into the file.
.IP "reference to a string scalar" 4
.IX Item "reference to a string scalar"
The Sensei's Library diagram is concatenated to the end of the string.
.IP "reference to an array" 4
.IX Item "reference to an array"
The Sensei's Library diagram is split on \*(L"\en\*(R" and each line is pushed onto the
array.
.RE
.RS 8
.Sp
Default: undef
.RE
.ie n .IP "\fBprint\fR => sub { my ($dg2sl, @lines) = @_; ... }" 8
.el .IP "\fBprint\fR => sub { my ($dg2sl, \f(CW@lines\fR) = \f(CW@_\fR; ... }" 8
.IX Item "print => sub { my ($dg2sl, @lines) = @_; ... }"
A user defined subroutine to replace the default printing method.
This callback is called from the \fBprint\fR method (below) with the
reference to the \fBDg2SL\fR object and a list of lines that are
part of the Sensei's Library diagram lines.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$dg2sl\->\fBconfigure\fR (option => value, ?...?)" 4
.el .IP "\f(CW$dg2sl\fR\->\fBconfigure\fR (option => value, ?...?)" 4
.IX Item "$dg2sl->configure (option => value, ?...?)"
Change Dg2SL options from values passed at \fBnew\fR time.
.ie n .IP "my $coord = $dg2mp\->\fBdiaCoords\fR ($x, $y)" 4
.el .IP "my \f(CW$coord\fR = \f(CW$dg2mp\fR\->\fBdiaCoords\fR ($x, \f(CW$y\fR)" 4
.IX Item "my $coord = $dg2mp->diaCoords ($x, $y)"
Provides access to the \fBdiaCoords\fR option (see above).  Returns
coordinates in the converter's coordinate system for board coordinates ($x,
\&\f(CW$y\fR).  For example, to get a specific intersection structure:
.Sp
.Vb 1
\&    my $int = $diagram\->get($dg2mp\->diaCoords(3, 4));
.Ve
.ie n .IP "$dg2sl\->\fBprint\fR ($text ? , ... ?)" 4
.el .IP "\f(CW$dg2sl\fR\->\fBprint\fR ($text ? , ... ?)" 4
.IX Item "$dg2sl->print ($text ? , ... ?)"
\&\fBprint\fRs the input \f(CW$text\fR directly to \fBfile\fR as defined at \fBnew\fR
time.  Whether or not \fBfile\fR was defined, \fBprint\fR accumulates the
\&\f(CW$text\fR for later retrieval with \fBconverted\fR.
.ie n .IP "my $sl = $dg2sl\->\fBconverted\fR ($replacement)" 4
.el .IP "my \f(CW$sl\fR = \f(CW$dg2sl\fR\->\fBconverted\fR ($replacement)" 4
.IX Item "my $sl = $dg2sl->converted ($replacement)"
Returns the entire Sensei's Library diagram converted so far for the \fBDg2SL\fR
object. If \f(CW$replacement\fR is defined, the accumulated Sensei's Library is
replaced by \f(CW$replacement\fR.
.ie n .IP "$dg2sl\->\fBcomment\fR ($comment ? , ... ?)" 4
.el .IP "\f(CW$dg2sl\fR\->\fBcomment\fR ($comment ? , ... ?)" 4
.IX Item "$dg2sl->comment ($comment ? , ... ?)"
Inserts the comment character (which is nothing for Sensei's Library) in front
of each line of each comment and \fBprint\fRs it to \fBfile\fR.
.ie n .IP "my $dg2sl\->\fBconvertDiagram\fR ($diagram)" 4
.el .IP "my \f(CW$dg2sl\fR\->\fBconvertDiagram\fR ($diagram)" 4
.IX Item "my $dg2sl->convertDiagram ($diagram)"
Converts a \fIGames::Go::Sgf2Dg::Diagram\fR into Sensei's Library. If \fBfile\fR was defined
in the \fBnew\fR method, the Sensei's Library is dumped into the \fBfile\fR.  In any
case, the Sensei's Library is returned as a string scalar.
.ie n .IP "my $sl = $dg2sl\->\fBconvertText\fR ($text)" 4
.el .IP "my \f(CW$sl\fR = \f(CW$dg2sl\fR\->\fBconvertText\fR ($text)" 4
.IX Item "my $sl = $dg2sl->convertText ($text)"
Converts \f(CW$text\fR into Sensei's Library code \- gee, that's not very hard.  In
fact, this method simply returns whatever is passed to it.  This is
really just a place-holder for more complicated converters.
.Sp
Returns the converted text.
.ie n .IP "$title = $dg2sl\->\fBconvertGameProps\fR (\e%sgfHash)" 4
.el .IP "\f(CW$title\fR = \f(CW$dg2sl\fR\->\fBconvertGameProps\fR (\e%sgfHash)" 4
.IX Item "$title = $dg2sl->convertGameProps (%sgfHash)"
\&\fBconvertGameProps\fR takes a reference to a hash of properties as
extracted from an \s-1SGF\s0 file.  Each hash key is a property \s-1ID\s0 and the
hash value is a reference to an array of property values:
\&\f(CW$hash\fR\->{propertyId}\->[values].  The following \s-1SGF\s0 properties are
recognized:
.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" 4
.IX Item "RO ROund"
.IP "\s-1DT\s0 DaTe" 4
.IX Item "DT DaTe"
.IP "\s-1PW\s0 PlayerWhite" 4
.IX Item "PW PlayerWhite"
.IP "\s-1WR\s0 WhiteRank" 4
.IX Item "WR WhiteRank"
.IP "\s-1PB\s0 PlayerBlack" 4
.IX Item "PB PlayerBlack"
.IP "\s-1BR\s0 BlackRank" 4
.IX Item "BR BlackRank"
.IP "\s-1PC\s0 PlaCe" 4
.IX Item "PC PlaCe"
.IP "\s-1KM\s0 KoMi" 4
.IX Item "KM KoMi"
.IP "\s-1RU\s0 RUles" 4
.IX Item "RU RUles"
.IP "\s-1TM\s0 TiMe" 4
.IX Item "TM TiMe"
.IP "\s-1OT\s0 OverTime (byo-yomi)" 4
.IX Item "OT OverTime (byo-yomi)"
.IP "\s-1RE\s0 REsult" 4
.IX Item "RE REsult"
.IP "\s-1AN\s0 ANnotator" 4
.IX Item "AN ANnotator"
.IP "\s-1SO\s0 Source" 4
.IX Item "SO Source"
.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
Both long and short property names are recognized, and all
unrecognized properties are ignored with no warnings.  Note that
these properties are all intended as game-level notations.
.RE
.ie n .IP "$dg2sl\->\fBclose\fR" 4
.el .IP "\f(CW$dg2sl\fR\->\fBclose\fR" 4
.IX Item "$dg2sl->close"
\&\fBprint\fRs any final text to the diagram (currently none) and closes
the dg2sl object.  Also closes \fBfile\fR if appropriate.
.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"
Seems likely.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marcel Gruenauer, <marcel@cpan.org<gt>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by Marcel Gruenauer.
.PP
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.