NAME

Games::Go::SGF - Parse and dissect Standard Go Format files

SYNOPSIS

  use Games::Go::SGF;

  my $file = shift;
  my $sgf = new Games::Go::SGF($file);
  print $sgf->getsgf;
  print "Game played on ".$sgf->date."\n";
  print $sgf->white. " (W) vs. ".$sgf->black." (B)\n";
  print "Board size: ".$sgf->size.". Komi: ".$sgf->komi."\n";

DESCRIPTION

This is an SGF file parser. It can read, write and step through SGF files, follow variations, and so on. It's good enough for getting simple statistics about games of Go, and building up Games::Go::Board objects representing games stored as SGF.

$sgf->move returns either a normal Games::Go::SGF::Node or a Games::Go::SGF::Variation object. The variation object has the additional methods mainline() to get the main line of the game, variation($n) to get the first node in the n'th variation, and variations to retrieve an array of variations. $variation->move will, by default, follow the mainline.

The parser will report 'bad go sgf' with an explanation if:

• there are certain duplicated property identifiers (tags) within a file (eg SZ)

• there are certain duplicated tags within a node (eg B)

• there is a certain mixture of tags within a node eg ( (B or W) and (AB or AW or AE) )

The parser will also quietly re-organise tags within a node if it is badly formed. eg CR[aa]CR[ab] becomes CR[aa][ab]

Some property value validation checks are made, some of which are Go specific. For example B[ab] is OK, but B[ab:ac] will not parse.

General use

The value of any property can be obtained by using its sgf tag. For example, to get the value of 'RU';

    my $rules = $sgf->RU;

Similarly, the value of any property can be set by using its sgf tag. For example, to set the value of 'RU';

    $sgf->RU('AGA');

Setting the value of a tag will create it, if necessary.

In addition, the following aliases are available:

    $sgf->date;  # equivalent to $sgf->DT
    $sgf->time;  # equivalent to $sgf->DT
    $sgf->white; # equivalent to $sgf->PW
    $sgf->black; # equivalent to $sgf->PB
    $sgf->size;  # equivalent to $sgf->SZ
    $sgf->komi;  # equivalent to $sgf->KM

These values can be also be set;

    $sgf->komi(5.5); # sets komi to 5.5

Properties found in the root of the sgf file (all those listed above for example) are available to be read regardless of the current node, other properties are node specific ($sgf->B for example)

PARAMETERS

A new SGF object can be created with one the following optional flags;

'lite' - re-organise but don't validate 'full' - validate and re-organise (slower)

If no parameter is specified, 'lite' is assumed.

For example

  my $sgf = new Games::Go::SGF($sgfdata, 'full');

METHODS

move

Move the parser on to the next node.

    $sgf($move_no++);

tags

The tags method returns an array containing the properties that were found in the current node.

    print $sgf->tags;

colour (aka color)

The colour method returns 'B', 'W', or 'None', depending on whether the tag B, or W, or neither of them was found in the current node.

    print $sgf->colour;
    print $sgf->color; # another way to spell colour

delete

To delete a tag in the current node;

    $sgf->delete('CR'); # delete the 'CR' tag

getsgf

To return the file in sgf;

    print $sgf->getsgf;

TODO

Make variations easier to navigate. Make validation game specific. Output to xml?

AUTHOR (version 0.01)

Simon Cozens

MODIFICATIONS (version 0.02+)

Daniel Gilder deg@cpan.org

SEE ALSO

Games::Go::Board, http://www.red-bean.com/sgf/

cpanm Games::Go::SGF

perl -MCPAN -e shell
install Games::Go::SGF