view release on metacpan or  search on metacpan

lib/Chess4p/Pgn/Reader.pm  view on Meta::CPAN

=head1 NAME

Chess4p::Pgn::Reader - PGN reader.

=head1 SYNOPSIS


 use Chess4p::Pgn::Reader qw(read_game);

 open my $fh, '<:encoding(UTF-8):bom', $filename or die $!;

 read_game($fh, $visitor);


=head1 DESCRIPTION

Read chess games from PGN (Portable Game Notation) files.
The files are assumed to abide by the PGN Standard.

=over 4

=item 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 $!;>

=back

=head2 CALLBACKS

The visitor needs to define a set of callback methods, which will be called at specific parsing
events.

=over 4

=item 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.

=item end_game($visitor)

This is called immediately before the reader returns.

=item 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.

=item 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.

=item visit_comment($visitor, $comment)

The visitor has collected a (possibly multi-line) text comment, which is now available in $comment .

=item begin_variation($visitor)

Signals the start of a variation.

=item end_variation($visitor)

Signals the end of a variation.

=item visit_nag($visitor, $nag)

The reader has read a NAG (an integer).

=item 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'.

=item 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

=over 2

=item 1

parse the SAN string as a move

=item 2

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.


=back

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.