NAME

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

SYNOPSIS

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

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

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

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: http://www.red-bean.com/sgf/.

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

$game = load_sgf $path

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

save_sgf $path, $game

Saves the SGF data to the specified file.

$game = decode_sgf $sgf_data

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

$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.

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 load_sgf and 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 B => [3, 5].

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

This module reserves all uppercase key names for SGF properties, the key variations and all keys starting with an underscore (_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: 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
                        ]
                      ],
      }
    ]
  }

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,
   }

AUTHOR

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