Games-Go-SGF-Grove/Grove.pm

=head1 NAME

Games::Go::SGF::Grove - SGF the Perl way

=head1 SYNOPSIS

 use Games::Go::SGF::Grove;

 $game = load_sgf $path;
 save_sgf $path, $game;

 $game = decode_sgf $sgf_data;
 $sgf_data = encode_sgf $game;

=head1 DESCRIPTION

This module loads and saves Go SGF files. Unlike other modules, it doesn't
build a very fancy data structure with lot's of java-like accessors
but instead returns a simple Perl data structure you can inspect with
Data::Dumper and modify easily. The structure follows the SGF file format
very closely.

The SGF format is documented here: L<http://www.red-bean.com/sgf/>.

All the functions below use a common data format and throw exceptions on
any errors.

=over 4

=cut

package Games::Go::SGF::Grove;

use strict;
no warnings;

use Carp;

use base Exporter::;

our $VERSION = 0.1;
our @EXPORT = qw(load_sgf save_sgf encode_sgf decode_sgf);

=item $game = load_sgf $path

Tries to read the file given by C<$path> and parses it as an SGF file,
returning the parsed data structure.

=item save_sgf $path, $game

Saves the SGF data to the specified file.

=item $game = decode_sgf $sgf_data

Tries to parse the given string into a Pelr data structure and returns it.

=item $sgf_data = encode_sgf $game

Takes a Perl data structure and serialises it into an SGF file. Anything
stored in the structure that isn't understood by this module will be
silently ignored.

=cut

sub decode_sgf($) {
   my ($sgf_data) = @_;

   Games::Go::SGF::Grove::Parser::->new->decode_sgf ($sgf_data)
}

sub encode_sgf($) {
   my ($game) = @_;

   Games::Go::SGF::Grove::Parser::->new->encode_sgf ($game)
}

sub load_sgf($) {
   my ($path) = @_;

   open my $fh, "<:perlio", $path
      or Carp::croak "$path: $!";

   local $/;
   decode_sgf <$fh>
}

sub save_sgf($$) {
   my ($path, $game) = @_;

   open my $fh, ">:perlio", $path
      or Carp::croak "$path: $!";

   print $fh encode_sgf $game;
}

=back

=head2 The Game Data structure

The SGF game is represented by a linked Perl data structure consisting of
unblessed hashes and arrays.

SGF files are a forest of trees, called a collection (i.e. you can have
multiple games stored in a file). The C<load_sgf> and C<decode_sgf>
functions returns this collection as a reference to an array containing
the individual game trees (usually there is only one, though).

Each individual tree is again an array of nodes representing the main line
of play.

Each node is simply a hash reference. Each SGF property is stored with the
(uppercase) property name as the key, and a property-dependent value for
the contents (e.g., a black move is stored as C<< B => [3, 5] >>.

If there are any variations/branches/alternate lines of play, then these
are stored in the array reference in the C<variations> key (those again
are game trees, so array references themselves).

This module reserves all uppercase key names for SGF properties, the key
C<variations> and all keys starting with an underscore (C<_xxx>) as it's
own. Users of this module may store additional attributes that don't
conflict with these names in any node.

Unknown properties will be stored as scalars with the (binary) property
contents. Text nodes will always be decoded into Unicode text and encoded
into whatever the CA property of the root node says (default: C<UTF-8>).

When saving, all uppercase keys will be saved, lowercase keys will be
ignored.

For the actual encoding of other types, best decode some example game that
contains them and use Data::Dumper. Here is such an example:

  [ # list of game-trees, only one here
    [ # the main node sequence
      { # the root node, contains some variations
        DI => '7k',
        AP => undef,
        CO => '5',
        DP => '40',
        GE => 'tesuji',
        AW => [
                  [ 2, 16 ], [ 3, 15 ], [ 15, 9 ], [ 14, 13 ], ...
              ],
        C  => 'White just played a ladder block at h12.',
        variations => [ # list of variations, only one
                        [ # sequence of variation moves
                          { B => [  7,  5 ] }, # a black move
                          { W => [ 12, 12 ] }, # a white move
                          ... and so on
                        ]
                      ],
      }
    ]
  }

=cut

package Games::Go::SGF::Grove::Parser;

no warnings;
use strict 'vars';

use Encode ();
use Carp qw(croak);

my $ws = qr{[\x00-\x20]*}s;
my $property; # property => propertyinfo

sub new {
   my $class = shift;
   bless { @_ }, $class;
}

sub error {
   my ($self, $error) = @_;

   my $pos = pos $self->{sgf};

   my $tail = substr $self->{sgf}, $pos, 32;
   $tail =~ s/[\x00-\x1f]+/ /g;

   croak "$error (at octet $pos, '$tail')";
}

sub decode_sgf {
   my ($self, $sgf) = @_;

   # correct lines
   if ($sgf =~ /[^\015\012]\015/) {
      $sgf =~ s/\015\012?/\n/g;
   } else {
      $sgf =~ s/\012\015?/\n/g;
   }

   $self->{sgf} = $sgf;

   $self->{FF} = 1;
   $self->{CA} = 'WINDOWS-1252'; # too many files are
   $self->{GM} = 1;

   my @trees;

   eval {
      while ($self->{sgf} =~ /\G$ws(?=\()/sgoc) {
         push @trees, $self->decode_GameTree;
      }
   };

   croak $@ if $@;

   \@trees
}

sub decode_GameTree {
   my ($self) = @_;

   $self->{sgf} =~ /\G$ws\(/sgoc
      or $self->error ("GameTree does not start with '('");

   my $nodes = $self->decode_Sequence;

   while ($self->{sgf} =~ /\G$ws(?=\()/sgoc) {
      push @{$nodes->[-1]{variations}}, $self->decode_GameTree;
   }
   $self->{sgf} =~ /\G$ws\)/sgoc
      or $self->error ("GameTree does not end with ')'");

   $nodes
}

sub postprocess {
   my $self = shift;

   for (@_) {
      if ("ARRAY" eq ref) {
         $self->postprocess (@$_);
      } elsif ("HASH" eq ref) {
         if (my $value = $_->{_text}) {
            $value =~ s/\\\n/ /g;
            $value =~ s/\\(.)/$1/g;
            $_ = eval { Encode::decode $self->{CA}, $value } || $value
         } else {
            $self->postprocess (values %$_);
         }
      }
   }
}

sub decode_Sequence {
   my ($self) = @_;

   my (@nodes, $node, $name, $value, $prop, @val);

   while ($self->{sgf} =~ /\G$ws;/goc) {
      push @nodes, $node = {};
      # Node
      while ($self->{sgf} =~ /\G$ws([A-Z]+)/goc) {
         # Property
         $name = $1;
         $prop = $property->{$name};

         while ($self->{sgf} =~ /\G$ws\[((?:[^\\\]]*|\\.)*)\]/sgoc) {
            # PropValue
            $value = $1;
            if ($prop) {
               @val = $prop->{in}->($self, $value, $prop);

               if ($prop->{is_list}) {
                  push @{$node->{$name}}, @val
               } else {
                  $node->{$name} = $val[0];

                  $self->{CA} = $val[0] if $name eq "CA";
               }
            } else {
               #warn "unknown property '$name', will be saved unchanged.";#d#
               push @{$node->{$name}}, $value;
            }
         }
      }

      # postprocess nodes, currently only to decode text and simpletext
      $self->postprocess ($node);
   }

   \@nodes
}

sub encode_sgf($) {
   my ($self, $game) = @_;

   $self->{sgf} = "";

   $self->{FF} = 4;
   $self->{CA} = 'UTF-8';
   $self->{GM} = 1;
   $self->{AP} = ["Games::Go::SGF::Grove", $VERSION];

   $self->encode_GameTree ($_, 1) for @$game;

   $self->{sgf}
}

sub encode_GameTree {
   my ($self, $sequence, $is_root) = @_;

   if ($is_root) {
      my $root = $sequence->[0];

      $root->{CA} ||= $self->{CA};
      $root->{FF} ||= $self->{FF};
      $root->{GM} ||= $self->{GM};
      $root->{AP} ||= $self->{AP};

      $self->{CA} = $root->{CA};
   }

   $self->{sgf} .= "(";
   $self->encode_Sequence ($sequence);
   $self->{sgf} .= ")";
}

sub encode_Sequence {
   my ($self, $sequence) = @_;

   my ($value, $prop);

   for my $node (@$sequence) {
      $self->{sgf} .= ";";

      for my $name (sort keys %$node) {
         next unless $name eq uc $name;

         $value = $node->{$name};

         $self->{sgf} .= "$name\[";

         if ($prop = $property->{$name}) {
            if ($prop->{is_list}) {
               $self->{sgf} .= join "][", map $prop->{out}->($self, $_), @$value;
            } else {
               $self->{sgf} .= $prop->{out}->($self, $value);
            }
         } else {
            $self->{sgf} .=
               ref $value
                  ? join "][", @$value
                  : $value;
         }

         $self->{sgf} .= "]";
      }

      $self->encode_GameTree ($_) for @{ $node->{variations} };
   }
}

#############################################################################

=head2 Property Type Structure

A property type is a hash like this:

   {
     name => "SQ",
     group => {
                name => "Markup properties",
                restrictions => "CR, MA, SL, SQ and TR points must be unique, ...",
              },
     related => "TR, CR, LB, SL, AR, MA, LN",
     function => "Marks the given points with a square.\nPoints must be unique.",
     propertytype => "-",
     propvalue => "list of point"
     is_list => 1,
   }

=cut


{
   my ($group, $name, $value, $prop);

   my (%char2coord, %coord2char);

   {
      my @coord = ("a" .. "z", "A" .. "Z");

      for (0.. $#coord) {
         $char2coord{ $coord[$_] } = $_;
         $coord2char{ $_ } = $coord[$_];
      }
   }

   sub _parsetype($);
   sub _parsetype {
      for (shift) {
         if (s/e?list of //) {
            $prop->{is_list} = 1;
            return _parsetype $_;

         } elsif (s/composed (\S+)\s+(?:':'\s+)?(\S+)//) {
            $prop->{composed} = 1;
            my ($i, $o) = ($1, $2);
            my ($i1, $o1, $i2, $o2) = (_parsetype $i, _parsetype $o);
            return (
                  sub {
                     if ($_[1] =~ /^((?:[^\\:]+|\\.)*)(?::(.*))?$/s) {
                        # or $_[0]->error ("'Compose' ($i:$o) expected, got '$_[1]'");
                        my ($l, $r) = ($1, $2);

                        [
                           $i1->($_[0], $l),
                           defined $r ? $i2->($_[0], $r) : undef,
                        ]
                     }
                  },
                  sub {
                     $o1->($_[0], $_[1][0])
                     . ":"
                     . $o2->($_[0], $_[1][1])
                  },
               );

         } elsif (s/double//) {
            return (
                  sub {
                     $_[1] =~ /^[12]$/
                        or $_[0]->error ("'Double' (1|2) expected, got '$_[1]'");
                     $_[1]
                  },
                  sub {
                     $_[1]
                  },
               );
         } elsif (s/color//) {
            return (
                  sub {
                     # too many broken programs write this wrong
                     return "B" if $_[1] eq "1";
                     return "W" if $_[1] eq "2";

                     $_[1] =~ /^[BW]$/i
                        or $_[0]->error ("'Color' (B|W) expected, got '$_[1]'");
                     lc $_[1]
                  },
                  sub {
                     uc $_[1]
                  },
               );
         } elsif (s/none//) {
            return (
                  sub {
                     $_[1] =~ /^$/i
                        or $_[0]->error ("'None' expected, got '$_[1]'");
                     undef
                  },
                  sub {
                     "",
                  },
               );
         } elsif (s/point// || s/move// || s/stone//) {
            return (
                  sub {
                     if ($_[2]->{is_list}) {
                        if ($_[1] =~ /^([^:]+):(.*)$/) {
                           my ($ul, $dr) = ($1, $2);
                           my ($x1, $y1) = map $char2coord{$_}, split //, $ul; 
                           my ($x2, $y2) = map $char2coord{$_}, split //, $dr; 
                           my @stones;
                           for (my $d = $x1; $d < $x2; $d++) {
                              for (my $i = $y1; $i < $y2; $i++) {
                                 push @stones, [$d, $i];
                              }
                           }
                           return @stones;
                        }
                     }
                     $_[1] =~ /^(.)(.)$/
                        ? [ $char2coord{$1}, $char2coord{$2} ]
                        : []
                  },
                  sub {
                     $coord2char{$_[1][0]} . $coord2char{$_[1][1]}
                  },
               );
         } elsif (s/real//) {
            return (
                  sub {
                     $_[1] =~ /^[+-]?[0-9]*\.?[0-9]*$/i
                        or $_[0]->error ("'Real' expected, got '$_[1]'");
                     $_[1]+0
                  },
                  sub {
                     $_[1]+0
                  },
               );
         } elsif (s/number//) {
            return (
                  sub {
                     $_[1] =~ /^[+-]?[0-9]*$/i
                        or $_[0]->error ("'Number' expected, got '$_[1]'");
                     $_[1]+0
                  },
                  sub {
                     int $_[1]
                  },
               );
         } elsif (s/text// || s/simpletext//i) {
            return (
                  sub {
                     { _text => $_[1] }
                  },
                  sub {
                     my $str = Encode::encode $_[0]{CA}, $_[1];
                     $str =~ s/([\:\]\\])/\\$1/g;
                     $str
                  },
               );
         } else {
            die "FATAL: garbled DATA section, unknown type '$_'";
         }
      }
   }

   while (<DATA>) {
      if (/^(\S+):\t(.*)/) {
         if ($name eq "Restrictions") {
            $group->{restrictions} = $value;
         } elsif ($name eq "Property") {
            $property->{$value} =
            $prop = {
               name  => $value,
               group => $group,
            };
         } elsif ($name ne "") {
            $prop->{lc $name} = $value;
            if ($name eq "Propvalue") {
               ($prop->{in}, $prop->{out}) = _parsetype $value;
            }
         }
         $name = $1;
         $value = $2;
      } elsif (/^\t\t(.*)/) {
         $value .= "\n$1";
      } elsif (/(\S.*)/) {
         $group = {
            name => $1,
         };
      } elsif (/^$/) {
         # nop
      } else {
         die "FATAL: DATA section garbled\n";
      }
   }
}

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 Robin Redeker <elmex@ta-sa.org>

=cut

# now node descriptions follow

__DATA__
Move properties

Property:       B
Propvalue:      move
Propertytype:   move
Function:       Execute a black move. This is one of the most used properties
                in actual collections. As long as
                the given move is syntactically correct it should be executed.
                It doesn't matter if the move itself is illegal
                (e.g. recapturing a ko in a Go game).
                Have a look at how to execute a Go-move.
                B and W properties must not be mixed within a node.
Related:        W, KO

Property:       KO
Propvalue:      none
Propertytype:   move
Function:       Execute a given move (B or W) even it's illegal. This is
                an optional property, SGF viewers themselves should execute
                ALL moves. It's purpose is to make it easier for other
                applications (e.g. computer-players) to deal with illegal
                moves. A KO property without a black or white move within
                the same node is illegal.
Related:        W, B

Property:       MN
Propvalue:      number
Propertytype:   move
Function:       Sets the move number to the given value, i.e. a move
                specified in this node has exactly this move-number. This
                can be useful for variations or printing.
Related:        B, W, FG, PM

Property:       W
Propvalue:      move
Propertytype:   move
Function:       Execute a white move. This is one of the most used properties
                in actual collections. As long as
                the given move is syntactically correct it should be executed.
                It doesn't matter if the move itself is illegal
                (e.g. recapturing a ko in a Go game).
                Have a look at how to execute a Go-move.
                B and W properties must not be mixed within a node.
Related:        B, KO

Setup properties
Restrictions:   AB, AW and AE must have unique points, i.e. it is illegal to place different colors on the same point within one node.
                AB, AW and AE values which don't change the board, e.g. placing a black stone with AB[] over a black stone that's already there, is bad style. Applications may want to delete these values and issue a warning.

Property:       AB
Propvalue:      list of stone
Propertytype:   setup
Function:       Add black stones to the board. This can be used to set up
                positions or problems. Adding is done by 'overwriting' the
                given point with black stones. It doesn't matter what
                was there before. Adding a stone doesn't make any prisoners
                nor any other captures (e.g. suicide). Thus it's possible
                to create illegal board positions.
                Points used in stone type must be unique.
Related:        AW, AE, PL

Property:       AE
Propvalue:      list of point
Propertytype:   setup
Function:       Clear the given points on the board. This can be used
                to set up positions or problems. Clearing is done by
                'overwriting' the given points, so that they contain no
                stones. It doesn't matter what was there before.
                Clearing doesn't count as taking prisoners.
                Points must be unique.
Related:        AB, AW, PL

Property:       AW
Propvalue:      list of stone
Propertytype:   setup
Function:       Add white stones to the board. This can be used to set up
                positions or problems. Adding is done by 'overwriting' the
                given points with white stones. It doesn't matter what
                was there before. Adding a stone doesn't make any prisoners
                nor any other captures (e.g. suicide). Thus it's possible
                to create illegal board positions.
                Points used in stone type must be unique.
Related:        AB, AE, PL

Property:       PL
Propvalue:      color
Propertytype:   setup
Function:       PL tells whose turn it is to play. This can be used when
                setting up positions or problems.
Related:        AE, AB, AW

Node annotation properties

Property:       C
Propvalue:      text
Propertytype:   -
Function:       Provides a comment text for the given node. The purpose of
                providing both a node name and a comment is to have a short
                identifier like "doesn't work" or "Dia. 15" that can be
                displayed directly with the properties of the node, even if
                the comment is turned off or shown in a separate window.
                See text-type for more info.
Related:        N, ST, V, UC, DM, HO

Property:       DM
Propvalue:      double
Propertytype:   -
Function:       The position is even. SGF viewers should display a
                message. This property may indicate main variations in
                opening libraries (joseki) too. Thus DM[2] indicates an
                even result for both players and that this is a main
                variation of this joseki/opening.
                This property must not be mixed with UC, GB or GW
                within a node.
Related:        UC, GW, GB

Property:       GB
Propvalue:      double
Propertytype:   -
Function:       Something good for black. SGF viewers should display a
                message. The property is not related to any specific place
                on the board, but marks the whole node instead.
                GB must not be mixed with GW, DM or UC within a node.
Related:        GW, C, UC, DM

Property:       GW
Propvalue:      double
Propertytype:   -
Function:       Something good for white. SGF viewers should display a
                message. The property is not related to any specific place
                on the board, but marks the whole node instead.
                GW must not be mixed with GB, DM or UC within a node.
Related:        GB, C, UC, DM

Property:       HO
Propvalue:      double
Propertytype:   -
Function:       Node is a 'hotspot', i.e. something interesting (e.g.
                node contains a game-deciding move).
                SGF viewers should display a message.
                The property is not related to any specific place
                on the board, but marks the whole node instead.
                Sophisticated applications could implement the navigation
                command next/previous hotspot.
Related:        GB, GW, C, UC, DM

Property:       N
Propvalue:      simpletext
Propertytype:   -
Function:       Provides a name for the node. For more info have a look at
                the C-property.
Related:        C, ST, V

Property:       UC
Propvalue:      double
Propertytype:   -
Function:       The position is unclear. SGF viewers should display a
                message. This property must not be mixed with DM, GB or GW
                within a node.
Related:        DM, GW, GB

Property:       V
Propvalue:      real
Propertytype:   -
Function:       Define a value for the node.  Positive values are good for
                black, negative values are good for white.
                The interpretation of particular values is game-specific.
                In Go, this is the estimated score.
Related:        C, N, RE

Move annotation properties
Restrictions:   Move annotation properties without a move (B[] or W[]) within the same node are senseless and therefore illegal. Applications should delete such properties and issue a warning.
                BM, TE, DO and IT are mutual exclusive, i.e. they must not be mixed within a single node.

Property:       BM
Propvalue:      double
Propertytype:   move
Function:       The played move is bad.
                Viewers should display a message.
Related:        TE, DO, IT

Property:       DO
Propvalue:      none
Propertytype:   move
Function:       The played move is doubtful.
                Viewers should display a message.
Related:        BM, TE, IT

Property:       IT
Propvalue:      none
Propertytype:   move
Function:       The played move is interesting.
                Viewers should display a message.
Related:        BM, DO, TE

Property:       TE
Propvalue:      double
Propertytype:   move
Function:       The played move is a tesuji (good move).
                Viewers should display a message.
Related:        BM, DO, IT

Markup properties
Restrictions:   CR, MA, SL, SQ and TR points must be unique, i.e. it's illegal to have two or more of these markups on the same point within a node.

Property:       AR
Propvalue:      list of composed point point
Propertytype:   -
Function:       Viewers should draw an arrow pointing FROM the first point
                TO the second point.
                It's illegal to specify the same arrow twice,
                e.g. (Go) AR[aa:bb][aa:bb]. Different arrows may have the same
                starting or ending point though.
                It's illegal to specify a one point arrow, e.g. AR[cc:cc]
                as it's impossible to tell into which direction the
                arrow points.
Related:        TR, CR, LB, SL, MA, SQ, LN

Property:       CR
Propvalue:      list of point
Propertytype:   -
Function:       Marks the given points with a circle.
                Points must be unique.
Related:        TR, MA, LB, SL, AR, SQ, LN

Property:       DD
Propvalue:      elist of point
Propertytype:   inherit
Function:       Dim (grey out) the given points.
                DD[] clears any setting, i.e. it undims everything.
Related:        VW

Property:       LB
Propvalue:      list of composed point simpletext
Propertytype:   -
Function:       Writes the given text on the board. The text should be
                centered around the given point. Note: there's no longer
                a restriction to the length of the text to be displayed.
                Have a look at the FF4 example file on possibilities
                to display long labels (pictures five and six).
                Points must be unique.
Related:        TR, CR, MA, SL, AR, SQ, LN

Property:       LN
Propvalue:      list of composed point point
Propertytype:   -
Function:       Applications should draw a simple line form one point
                to the other.
                It's illegal to specify the same line twice,
                e.g. (Go) LN[aa:bb][aa:bb]. Different lines may have the same
                starting or ending point though.
                It's illegal to specify a one point line, e.g. LN[cc:cc].
Related:        TR, CR, MA, SL, AR, SQ, LB


Property:       MA
Propvalue:      list of point
Propertytype:   -
Function:       Marks the given points with an 'X'.
                Points must be unique.
Related:        TR, CR, LB, SL, AR, SQ, LN

Property:       SL
Propvalue:      list of point
Propertytype:   -
Function:       Selected points. Type of markup unknown
                (though SGB inverts the colors of the given points).
                Points must be unique.
Related:        TR, CR, LB, MA, AR, LN

Property:       SQ
Propvalue:      list of point
Propertytype:   -
Function:       Marks the given points with a square.
                Points must be unique.
Related:        TR, CR, LB, SL, AR, MA, LN

Property:       TR
Propvalue:      list of point
Propertytype:   -
Function:       Marks the given points with a triangle.
                Points must be unique.
Related:        MA, CR, LB, SL, AR, LN

Root properties

Property:       AP
Propvalue:      composed simpletext simpletext
Propertytype:   root
Function:       Provides the name and version number of the application used
                to create this gametree.
                The name should be unique and must not be changed for
                different versions of the same program.
                The version number itself may be of any kind, but the format
                used must ensure that by using an ordinary string-compare,
                one is able to tell if the version is lower or higher
                than another version number.
                Here's the list of known applications and their names:

                Application                  System       Name
                ---------------------------  -----------  --------------------
                [CGoban:1.6.2]               Unix         CGoban
                [Hibiscus:2.1]               Windows 95   Hibiscus Go Editor
                [IGS:5.0]                                 Internet Go Server
                [Many Faces of Go:10.0]      Windows 95   The Many Faces of Go
                [MGT:?]                      DOS/Unix     MGT
                [NNGS:?]                     Unix         No Name Go Server
                [Primiview:3.0]              Amiga OS3.0  Primiview
                [SGB:?]                      Macintosh    Smart Game Board
                [SmartGo:1.0]                Windows      SmartGo

Related:        FF, GM, SZ, ST, CA

Property:       CA
Propvalue:      simpletext
Propertytype:   root
Function:       Provides the used charset for SimpleText and Text type.
                Default value is 'ISO-8859-1' aka 'Latin1'.
                Only charset names (or their aliases) as specified in RFC 1345
                (or updates thereof) are allowed.
                Basically this field uses the same names as MIME messages in
                their 'charset=' field (in Content-Type).
                RFC's can be obtained via FTP from DS.INTERNIC.NET,
                NIS.NSF.NET, WUARCHIVE.WUSTL.EDU, SRC.DOC.IC.AC.UK
                or FTP.IMAG.FR.
Related:        FF, C, text type

Property:       FF
Propvalue:      number (range: 1-4)
Propertytype:   root
Function:       Defines the used file format. For difference between those
                formats have a look at the history of SGF.
                Default value: 1
                Applications must be able to deal with different file formats
                within a collection.
Related:        GM, SZ, ST, AP, CA

Property:       GM
Propvalue:      number (range: 1-16)
Propertytype:   root
Function:       Defines the type of game, which is stored in the current
                gametree. The property should help applications
                to reject games, they cannot handle.
                Valid numbers are: Go = 1, Othello = 2, chess = 3,
                Gomoku+Renju = 4, Nine Men's Morris = 5, Backgammon = 6,
                Chinese chess = 7, Shogi = 8, Lines of Action = 9,
                Ataxx = 10, Hex = 11, Jungle = 12, Neutron = 13,
                Philosopher's Football = 14, Quadrature = 15, Trax = 16,
                Tantrix = 17, Amazons = 18, Octi = 19, Gess = 20.
                Default value: 1
                Different kind of games may appear within a collection.
Related:        FF, SZ, ST, AP, CA

Property:       ST
Propvalue:      number (range: 0-3)
Propertytype:   root
Function:       Defines how variations should be shown (this is needed to
                synchronize the comments with the variations). If ST is omitted
                viewers should offer the possibility to change the mode online.
                Basically most programs show variations in two ways:
                as markup on the board (if the variation contains a move)
                and/or as a list (in a separate window).
                The style number consists two options.
                1) show variations of successor node (children) (value: 0)
                   show variations of current node   (siblings) (value: 1)
                   affects markup & list
                2) do board markup         (value: 0)
                   no (auto-) board markup (value: 2)
                   affects markup only.
                   Using no board markup could be used in problem collections
                   or if variations are marked by subsequent properties.
                   Viewers should take care, that the automatic variation
                   board markup DOESN'T overwrite any markup of other
                   properties.
                The  final number is calculated by adding the values of each
                option. Example: 3 = no board markup/variations of current node
                                 1 = board markup/variations of current node
                Default value: 0
Related:        C, FF, GM, SZ, AP, CA

Property:       SZ
Propvalue:      number
Propertytype:   root
Function:       Defines the size of the board. If only a single value
                is given, the board is a square; with two numbers given,
                rectangular boards are possible.
                If a rectangular board is specified, the first number specifies
                the number of columns, the second provides the number of rows.
                Square boards must not be defined using the compose type
                value: e.g. SZ[19:19] is illegal.
                The valid range for SZ is any size greater or equal to 1x1.
                For Go games the maximum size is limited to 52x52.
                Default value: game specific
                               for Go: 19 (square board)
                               for Chess: 8 (square board)
                Different board sizes may appear within a collection.
                See move-/point-type for more info.
Related:        FF, GM, ST, AP, CA

Game info properties

Property:       AN
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the person, who made the annotations
                to the game.
Related:        US, SO, CP

Property:       BR
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the rank of the black player.
                For Go (GM[1]) the following format is recommended:
                "..k" or "..kyu" for kyu ranks and
                "..d" or "..dan" for dan ranks.
                Go servers may want to add '?' for an uncertain rating and
                '*' for an established rating.
Related:        PB, BT, WR

Property:       BT
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the black team, if game was part of a
                team-match (e.g. China-Japan Supermatch).
Related:        PB, PW, WT

Property:       CP
Propvalue:      simpletext
Propertytype:   game-info
Function:       Any copyright information (e.g. for the annotations) should
                be included here.
Related:        US, SO, AN

Property:       DT
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the date when the game was played.
                It is MANDATORY to use the ISO-standard format for DT.
                Note: ISO format implies usage of the Gregorian calendar.
                Syntax:
                "YYYY-MM-DD" year (4 digits), month (2 digits), day (2 digits)
                Do not use other separators such as "/", " ", "," or ".".
                Partial dates are allowed:
                "YYYY" - game was played in YYYY
                "YYYY-MM" - game was played in YYYY, month MM
                For games that last more than one day: separate other dates
                by a comma (no spaces!); following shortcuts may be used:
                "MM-DD" - if preceded by YYYY-MM-DD, YYYY-MM, MM-DD, MM or DD
                "MM" - if preceded by YYYY-MM or MM
                "DD" - if preceded by YYYY-MM-DD, MM-DD or DD
                Shortcuts acquire the last preceding YYYY and MM (if
                necessary).
                Note: interpretation is done from left to right.
                Examples:
                        1996-05,06 = played in May,June 1996
                        1996-05-06,07,08 = played on 6th,7th,8th May 1996
                        1996,1997 = played in 1996 and 1997
                        1996-12-27,28,1997-01-03,04 = played on 27th,28th
                        of December 1996 and on 3rd,4th January 1997
                Note: it's recommended to use shortcuts whenever possible,
                e.g. 1997-05-05,06 instead of 1997-05-05,1997-05-06
Related:        EV, RO, PC, RU, RE, TM

Property:       EV
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the event (e.g. tournament).
                Additional information (e.g. final, playoff, ..)
                shouldn't be included (see RO).
Related:        GC, RO, DT, PC, RU, RE, TM

Property:       GN
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides a name for the game. The name is used to
                easily find games within a collection.
                The name should therefore contain some helpful information
                for identifying the game. 'GameName' could also be used
                as the file-name, if a collection is split into
                single files.
Related:        GC, EV, DT, PC, RO, ID

Property:       GC
Propvalue:      text
Propertytype:   game-info
Function:       Provides some extra information about the following game.
                The intend of GC is to provide some background information
                and/or to summarize the game itself.
Related:        GN, ON, AN, CP

Property:       ON
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides some information about the opening played
                (e.g. san-ren-sei, Chinese fuseki, etc.).
Related:        GN, GC

Property:       OT
Propvalue:      simpletext
Propertytype:   game-info
Function:       Describes the method used for overtime (byo-yomi).
                Examples: "5 mins Japanese style, 1 move / min",
                          "25 moves / 10 min".
Related:        TM, BL, WL, OB, OW

Property:       PB
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the black player.
Related:        PW, BT, WT

Property:       PC
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the place where the games was played.
Related:        EV, DT, RO, RU, RE, TM

Property:       PW
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the white player.
Related:        PB, BT, WT

Property:       RE
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the result of the game. It is MANDATORY to use the
                following format:
                "0" (zero) or "Draw" for a draw (jigo),
                "B+" ["score"] for a black win and
                "W+" ["score"] for a white win
                Score is optional (some games don't have a score e.g. chess).
                If the score is given it has to be given as a real value,
                e.g. "B+0.5", "W+64", "B+12.5"
                Use "B+R" or "B+Resign" and "W+R" or "W+Resign" for a win by
                resignation. Applications must not write "Black resigns".
                Use "B+T" or "B+Time" and "W+T" or "W+Time" for a win on time,
                "B+F" or "B+Forfeit" and "W+F" or "W+Forfeit" for a win by
                forfeit,
                "Void" for no result or suspended play and
                "?" for an unknown result.

Related:        EV, DT, PC, RO, RU, TM

Property:       RO
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides round-number and type of round. It should be
                written in the following way: RO[xx (tt)], where xx is the
                number of the round and (tt) the type:
                final, playoff, league, ...
Related:        EV, DT, PC, RU, RE, TM

Property:       RU
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the used rules for this game.
                Because there are many different rules, SGF requires
                mandatory names only for a small set of well known rule sets.
                Note: it's beyond the scope of this specification to give an
                exact specification of these rule sets.
                Mandatory names for Go (GM[1]):
                        "AGA" (rules of the American Go Association)
                        "GOE" (the Ing rules of Goe)
                        "Japanese" (the Nihon-Kiin rule set)
                        "NZ" (New Zealand rules)

Related:        EV, DT, PC, RO, RE, TM

Property:       SO
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the source (e.g. book, journal, ...).
Related:        US, AN, CP

Property:       TM
Propvalue:      real
Propertytype:   game-info
Function:       Provides the time limits of the game.
                The time limit is given in seconds.
Related:        EV, DT, PC, RO, RU, RE

Property:       US
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the name of the user (or program), who entered
                the game.
Related:        SO, AN, CP

Property:       WR
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provides the rank of the white player. For recommended
                format see BR.
Related:        PW, WT, BR

Property:       WT
Propvalue:      simpletext
Propertytype:   game-info
Function:       Provide the name of the white team, if game was part of a
                team-match (e.g. China-Japan Supermatch).
Related:        PB, PW, BT

Timing properties

Property:       BL
Propvalue:      real
Propertytype:   move
Function:       Time left for black, after the move was made.
                Value is given in seconds.
Related:        TM, OT, WL, OB, OW

Property:       OB
Propvalue:      number
Propertytype:   move
Function:       Number of black moves left (after the move of this node was
                played) to play in this byo-yomi period.
Related:        TM, OT, BL, WL, OW

Property:       OW
Propvalue:      number
Propertytype:   move
Function:       Number of white moves left (after the move of this node was
                played) to play in this byo-yomi period.
Related:        TM, OT, BL, WL, OB

Property:       WL
Propvalue:      real
Propertytype:   move
Function:       Time left for white after the move was made.
                Value is given in seconds.
Related:        TM, OT, BL, OB, OW

Miscellaneous properties

Property:       FG
Propvalue:      composed number SimpleText
Propertytype:   -
Function:       The figure property is used to divide a game into
                different figures for printing: a new figure starts at the
                node containing a figure property.
                If the value is not empty then
                - Simpletext provides a name for the diagram
                - Number specifies some flags (for printing).
                  These flags are:
                        - coordinates on/off (value: 0/1)
                        - diagram name on/off (value: 0/2)
                        - list moves not shown in figure on/off (value: 0/4)
                          Some moves can't be shown in a diagram (e.g. ko
                          captures in Go) - these moves may be listed as text.
                        - remove captured stones on/off (value: 0/256)
                          'remove off' means: keep captured stones in the
                          diagram and don't overwrite stones played earlier -
                          this is the way diagrams are printed in books.
                          'remove on' means: capture and remove the stones from
                          the display - this is the usual viewer mode.
                          This flag is specific to Go (GM[1]).
                        - hoshi dots on/off (value: 0/512)
                          This flag is specific to Go (GM[1]).
                        - Ignore flags on/off (value: 32768)
                          If on, then all other flags should be ignored and
                          the application should use its own defaults.
                  The final number is calculated by summing up all flag values.
                  E.g. 515 = coordinates and diagram name off, remove captured
                  stones, list unshown moves, hoshi dots off;
                  257 = coordinates off, diagram name on, list unshown moves,
                  don't remove captured stones, hoshi dots on.
                  (this is how diagrams are printed in e.g. Go World)
                Note: FG combined with VW, MN and PM are mighty tools to print
                and compile diagrams.
Related:        MN, PM, VW

Property:       PM
Propvalue:      number
Propertytype:   inherit
Function:       This property is used for printing.
                It specifies how move numbers should be printed.
                0 ... don't print move numbers
                1 ... print move numbers as they are
                2 ... print 'modulo 100' move numbers
                        This mode is usually used in books or magazines.
                        Note: Only the first move number is calculated
                        'modulo 100' and the obtained number is increased
                        for each move in the diagram.
                        E.g. A figure containing moves
                                 32-78  is printed as moves 32-78
                                102-177 is printed as moves  2-77
                                 67-117 is printed as moves 67-117
                                154-213 is printed as moves 54-113
                Default value: 1
Related:        MN, FG

Property:       VW
Propvalue:      elist of point
Propertytype:   inherit
Function:       View only part of the board. The points listed are
                        visible, all other points are invisible.
                        Note: usually the point list is given in compressed
                        format (see 'point' type)!
                        Points have to be unique.
                        Have a look at the picture to get an idea.
                        VW[] clears any setting, i.e. the whole board is
                        visible again.
Related:        DD, PM, FG

Go properties
Restrictions:   TW and TB points must be unique, i.e. it's illegal to list the same point in TB and TW within the same node.
Gametype:       1

Property:       HA
Propvalue:      number
Propertytype:   game-info
Function:       Defines the number of handicap stones (>=2).
                If there is a handicap, the position should be set up with
                AB within the same node.
                HA itself doesn't add any stones to the board, nor does
                it imply any particular way of placing the handicap stones.
Related:        KM, RE, RU

Property:       KM
Propvalue:      real
Propertytype:   game-info
Function:       Defines the komi.
Related:        HA, RE, RU

Property:       TB
Propvalue:      elist of point
Propertytype:   -
Function:       Specifies the black territory or area (depends on
                rule set used).
                Points must be unique.
Related:        TW

Property:       TW
Propvalue:      elist of point
Propertytype:   -
Function:       Specifies the white territory or area (depends on
                rule set used).
                Points must be unique.
Related:        TB

Octi properties
Gametype:       19

Property:       RU (rules)
Propvalue:      simpletext
Propertytype:   game-info
Function:       Valid values are one major variation ("full", "fast",
                or "kids") followed by a colon and a comma separated
                elist of variations ("edgeless", "superprong", etc.).
                
                The colon may be omitted if either side is empty.
                The default is 2-player full, no variations.
                The 4-player game is not currently available.

Property:       BO (black octisquares)
Propvalue:      list of point
Propertytype:   game-info
Function:       The position of Black's octi squares.  Black will be
                setup with one empty pod on each of these points.
                It is illegal to list the same point twice.
                Traditionally, Black sits at the south end of the board.
Related:        WO

Property:       WO (white octisquares)
Propvalue:      list of point
Propertytype:   game-info
Function:       The position of White's octi squares.  White will be
                setup with one empty pod on each of these points.
                It is illegal to list the same point twice.
                Traditionally, White sits at the north end of the board.
Related:        BO

Property:       NP (number of prongs)
Propvalue:      number
Propertytype:   game-info
Function:       This is the number of prongs each players has at the
                start of the game.
                The default will be derived from the rules.
Related:        NR

Property:       NR (number of reserve)
Propvalue:      number
Propertytype:   game-info
Function:       This is the number of pods in each players reserve at
                the start of the game.
                The default will be derived from the rules.
Related:        NP, NS

Property:       NS (number of superprongs)
Propvalue:      number
Propertytype:   game-info
Function:       This is the number of superprongs each players has at
                the start of the game.
                The default will be derived from the rules.
Related:        NR

Property:       AS (arrow stone)
Propvalue:      list of composed stone ':' point
Propertytype:   -
Function:       Most of the same restriction from AR apply.
                The same arrow must not occur twice; however, two arrows
                from different stones at the same point may have arrows
                to the same destination.        Single point arrows are also
                illegal.
Related:        AR

Property:       CS (circle stone)
Propvalue:      list of stone
Propertytype:   -
Function:       Marks the given stones, each with a circle.
Related:        CR

Property:       MS (mark stone)
Propvalue:      list of stone
Propertytype:   -
Function:       Marks the given stones, each with an ex.
Related:        MA

Property:       SS (square stone)
Propvalue:      list of stone
Propertytype:   -
Function:       Marks the given stones, each with a square.
Related:        SQ

Property:       TS (triangle stone)
Propvalue:      list of stone
Propertytype:   -
Function:       Marks the given stones, each with a triangle.
Related:        TR

Property:       RP (remove pod)
Propvalue:      list of stone
Propertytype:   setup
Function:       Removes a stone from the board.
                More selective than AddEmpty.
Related:        AE

Backgammon properties
Gametype:       6

Property:       CO
Propvalue:      simpletext
Propertytype:   setup
Function:       Set the position of the doubling cube.  The value
                should be `b' (black), `w' (white), `c' (centred), or `n'
                (none -- for cubeless or Crawford games).
Related:        CV

Property:       CV
Propvalue:      number
Propertytype:   setup
Function:       Set the value of the doubling cube.  This value
                defaults to 1 at the beginning of the game, but a CV property
                should be added when setting up a position where a double has
                been made, or at the beginning of a money game if automatic
                doubles occur.
Related:        CP

Property:       DI
Propvalue:      number
Propertytype:   setup
Function:       Set the dice without moving (this could be useful for
                creating problem positions, e.g. DI[31])
Related:        CO

Property:       MI
Propvalue:      list of composed simpletext ':' simpletext
Propertytype:   game-info
Function:       Specifies information about the match the game belongs to.
                This property should specify a list of tag/value pairs, where
                the allowable tags are case-insensitive, and include:

                  length - the match length (number of points); value should
                           be a number
                  game   - the number of this game within the match (the
                           first game is 1); value should be a number
                  bs     - the score for Black at the start of the game;
                           value should be a number
                  ws     - the score for White at the start of the game;
                           value should be a number

                Unknown tags should be ignored (a warning may be produced).
                The order of tags in the list is not significant.  An example
                MI property is:
                                  MI[length:7][game:3][ws:2][bs:1]
Related:        EV, GN, RE, RO

Property:       RE
Propvalue:      simpletext
Propertytype:   game-info
Function:       The general RE property has the following
                modification in backgammon games: in the case of a
                resignation, the value should also specify the number of
                points before the R(esign).  Here are three example RE
                properties:

                        RE[B+6R]      -- White resigns a backgammon on a 2
                                         cube (worth 6 points).
                        RE[W+2Resign] -- Black resigns a gammon on a 1 cube
                                         (worth 2 points).
                        RE[W+4]       -- Black drops a redouble to 8 (note
                                         this is considered a normal loss, not
                                         a resignation).
Related:        RE

Property:       RU
Propvalue:      simpletext
Propertytype:   game-info
Function:       Backgammon-specific values for the general RU property
                include the following:

                  [Crawford] -- the Crawford rule is being used in this match,
                    although this is not the Crawford game.
                  [Crawford:CrawfordGame] -- this IS the Crawford game.
                  [Jacoby] -- the Jacoby rule is in use for this game.
Related:        RU

Lines of Action properties
Gametype:       9

Property:       AS
Propvalue:      SimpleText
Propertytype:   -
Function:       Adding stones - the color of the player who is adding
                stones to the board. The valid strings are 'Black', 'White'
                or 'None'. The puropse of this property is to define a
                board position where the human is expected to continue placing
                stones on the board through some user interface.

Property:       IP
Propvalue:      SimpleText
Propertytype:   game-info
Function:       Designates the initial position in the game to be
                displayed by the viewer.
                The only value currently supported is 'End', which causes
                the viewer to initially display the final position of the game.
                The default is to display the position after setup but before
                any moves.

Property:       IY
Propvalue:      SimpleText
Propertytype:   game-info
Function:       Invert Y axis.  Values are 'true' or 'false'.
                If 'true', the board should be displayed with numbers
                increasing in value from bottom to top of the screen.
                Default: 'false'

Property:       SE
Propvalue:      point
Propertytype:   -
Function:       Mark the given point and up to 8 additional points,
                depending on where the provided point (stone) could legally
                move.

Property:       SU
Propvalue:      SimpleText
Propertytype:   game-info
Function:       Setup type - designates the intial placement of pieces,
                and also the implicitly the variation on the basic rules to be
                employed. The currently valid values include the following
                strings:
                'Standard', 'Scrambled-eggs', 'Parachute', 'Gemma' and 'Custom'
                (the initial board is empty, AB and AW properties
                will be used to establish the starting position).
                Default: 'Standard'
                For details on the setups and rule variations, consult the
                LOA home pages.

Hex properties
Gametype:       11

Property:       IS
Propvalue:      list of composed SimpleText ':' SimpleText
Propertytype:   root
Function:       This property allows applications to store and read
                an initial viewer setting. The property value is a list of
                "keyword followed by ':' followed by either 'on' or 'off'".
                Valid keywords are:
                  'tried' - identify future moves that have been tried?
                  'marked' - show good/bad move markings?
                  'lastmove' - identify the last cell played?
                  'headings' - display column/row headings (a b.., 1 2..)?
                  'lock' - lock the game against new moves (for analysis)?
                This property is allowed in the root node only.
                Example: IS[tried:on][lock:off][marked:off]

Property:       IP
Propvalue:      SimpleText
Propertytype:   game-info
Function:       Designates the initial position that the viewer
                should display. It will most frequently indicate the
                current position of play in the game. This is necessary 
                because future possible moves may have been explored,
                and the user must be able to distinguish real moves
                actually made from exploratory moves. More than one IP[]
                property in a game is illegal, and the behaviour undefined.
                The property value should be empty (""); it is specified
                as SimpleText for compatibility.

Amazons properties
Gametype:       18

Property:       AA
Propvalue:      list of point
Propertytype:   setup
Function:       Adding arrows to the board. This can be used to set up
                positions or problems.

End:    this marks the end

Revision:	1.10
Committed:	Mon Jul 21 18:52:13 2008 UTC (15 years, 11 months ago) by elmex
Branch:	MAIN
Changes since 1.9:	+1 -4 lines
Log Message:	schaden => ?