NAME
Chess4p::Pgn::Reader - PGN reader.
SYNOPSIS
use Chess4p::Pgn::Reader qw(read_game);
open my $fh, '<:encoding(UTF-8):bom', $filename or die $!;
read_game($fh, $visitor);DESCRIPTION
Read chess games from PGN (Portable Game Notation) files. The files are assumed to abide by the PGN Standard.
- read_game($fh, $visitor)
-
Read a game from the PGN file. $fh is a file handle for the opened PGN file. The visitor will handle the tokens fed by the reader (see below).
Returns a pair ($result, $errors) where $result is whatever the visitor returns in $visitor->result(), and $errors is a reference to an array that contains any error messages.
At the end of input, $result will be undefined - which means that $visitor->result() should always return a defined value, so that end of input can be detected correctly.
See pgn-reader.t for an example.
It is the callers responsibility to open the file in the proper encoding. Usually, PGN files are ASCII or UTF-8 encoded.
For example:
open my $fh, '<:encoding(UTF-8)', $filename or die $!;>
CALLBACKS
The visitor needs to define a set of callback methods, which will be called at specific parsing events.
- begin_game($visitor)
-
This will be called when the reader has determined that another game is available to be read. Use this for cleaning up from any previous games read.
Return 0 to have the reader call the other callbacks as this game is read.
Return 1 to have the reader skip the game by not calling the other callbacks as this game is read.
- end_game($visitor)
-
This is called immediately before the reader returns.
- visit_header($visitor, $name, $value)
-
This is called when the reader has read a PGN tag with its value. The tag name and value are returned.
- end_headers($visitor)
-
Called when the reader has determined that there are no more headers to be read.
Return 0 to have the reader call the other callbacks as it reads the movetext section.
Return 1 to have the reader skip the movetext section of this game. This is useful in searching for specific header values like player names, etc.
- visit_comment($visitor, $comment)
-
The visitor has collected a (possibly multi-line) text comment, which is now available in $comment .
- begin_variation($visitor)
-
Signals the start of a variation.
- end_variation($visitor)
-
Signals the end of a variation.
- visit_nag($visitor, $nag)
-
The reader has read a NAG (an integer).
- visit_result($visitor, $token)
-
The reader has read a token that signifies the game's result. This is one of '*', '1-0', '0-1' or '1/2-1/2'.
- begin_parse_san($visitor, $board, $token)
-
The reader has seen a token that is supposed to be a SAN move string.
Return 1 to have the reader
parse the SAN string as a move
call $visitor->visit_move($board, $move) if the move was parsed as being valid ($move is reference to a Chess4p::Move object);
Or add any error message to the readers error stack if the SAN string was not valid.
Whether the SAN was a valid move or not, the reader will call
$visitor->visit_board($board)
afterwards.
Return 0 to have the reader skip the SAN parsing;
The call to
$visitor->visit_board($board)
will happen also in this case.
AUTHOR
Ejner Borgbjerg
LICENSE
Perl Artistic License, GPL