NAME

Chess::PGN::Filter - Perl extension for converting PGN files to other formats.

SYNOPSIS

#!/usr/bin/perl
# 
use strict;
use warnings;
use Chess::PGN::Filter;

if ($ARGV[0]) {
    filter(source => $ARGV[0],filtertype => 'XML');
}

OR

#!/usr/bin/perl
# 
use strict;
use warnings;
use Chess::PGN::Filter;

if ($ARGV[0]) {
    my %substitutions = (
        hsmyers => 'Myers, Hugh S (ID)'
    );

    filter(
        source => $ARGV[0],
        filtertype => 'TEXT',
        substitute => \%substitutions,
        nags => 'yes',
    );
}

DESCRIPTION

This is a typical text in one side, different text out the otherside filter module. There are as of this writing, the following supported choices:

1XML -- Converts from .pgn to .xml using the included pgn.dtd as the validation document. This is for the most part a one to one transliteration of the PGN standard into XMLese. It does have the additional virtue of allowing positions to be encoded within the XML output. These are generated by an embedded NAG of {0} and automatically (user controlled) at the end of each game. As a kind of adjunct to the position diagrams, pgn.dtd optionally allows each move to include it's FEN string. This allows scripted animation for web pages generated this information.

1TEXT -- Although the PGN standard is widely available, many program that generate .pgn do so in an ill-formed way. This mode is an attempt to 'normalize' away the various flaws found in the 'wild'! This includes things like game text all on a single line without a preceding blank line. Or castling indicated with zeros rather than the letter 'O'. There is at least one application that carefully indents the first move! The list of oddities is probably as long as the list of applications.

Owing to a dearth of imagination, there is but one routine in the module:

filter(parameter_hash)

There are however, a small host of known keys for parameter_hash and they are as follows:

• keys common to all filtertypes

  • filtertype -- essentially which filter to use. Values implemented are:

    1XML -- converts from .pgn text in, to .xml file out. Validated by supplied pgn.dtd.

    1TEXT -- converts from .pgn text in, to .pgn out with reformatting of ill-formed text and other modifications possible. Global correction of tag values, error checking for game text termination etc. Blank lines and paragraph wrapping emplemented to match PGN standard.

  • source -- name of file to convert, with output sent to STDOUT.

• keys for filtertype TEXT

  • substitute -- simple text substitution mechanism applied globally (file scope) to all tag text.

    This is actually a hash reference where the hash reffered to has the form of (text_to_change => text_to_change_to). For instance:

    my %substitutions = (
        hsmyers => 'Myers, Hugh S (ID)'
    );

    as used in the SYNOPSIS example would expand my user name into a full version for any tag the former might occur in.

  • comments -- switch to include/exclude comments (defaults to 'no'.)

  • ravs -- switch to include/exclude recursive annotated variations (defaults to 'no'.)

  • nags -- switch to include/exclude numberic annotation glyphs (defaults to 'no'.)

  • ECO -- switch to include/exclude ECO tag (defaults to 'yes'.)

  • NIC -- switch to include/exclude NIC tag (defaults to 'no'.)

  • Opening -- switch to include/exclude Opening tag (defaults to 'yes'.)

• keys for filtertype XML. These control the appearence of embedded positions reached during the game as well as the final position of the game.

  • fen -- switch to include/exclude fen information for each move (defaults to 'no'.)

  • position -- switch to control position diagrams in a game (defaults to 'yes'.)

    Possible values are:

    • 'nag' -- insert diagram for each {0} in game text.

    • 'end' -- insert diagram at end of game.

    • 'no' -- no diagrams from either source.

    • 'yes' -- create diagrams based on both embedded nags as well as at end of game.

  • font -- name of font to specify for embedded diagrams (default is 'Chess Kingdom'.)

    Following list shows font name, font designer. They are available from http://www.enpassant.dk/chess/fonteng.htm

    1Chess Cases -- Matthieu Leschemelle

    1Chess Adventurer -- Armando H. Marroquin

    1Chess Alfonso-X -- Armando H. Marroquin

    1Chess Alpha -- Eric Bentzen

    1Chess Berlin -- Eric Bentzen

    1Chess Condal -- Armando H. Marroquin

    1Chess Harlequin -- Armando H. Marroquin

    1Chess Kingdom -- Armando H. Marroquin

    1Chess Leipzig -- Armando H. Marroquin

    1Chess Line -- Armando H. Marroquin

    1Chess Lucena -- Armando H. Marroquin

    1Chess Magnetic -- Armando H. Marroquin

    1Chess Mark -- Armando H. Marroquin

    1Chess Marroquin -- Armando H. Marroquin

    1Chess Maya -- Armando H. Marroquin

    1Chess Mediaeval -- Armando H. Marroquin

    1Chess Mérida -- Armando H. Marroquin

    1Chess Millennia -- Armando H. Marroquin

    1Chess Miscel -- Armando H. Marroquin

    1Chess Montreal -- Gary Katch

    1Chess Motif -- Armando H. Marroquin

    1Chess Plain -- Alan Hickey

    1Chess Regular -- Alistair Scott

    1Chess Usual -- Armando H. Marroquin

    1Chess Utrecht -- Hans Bodlaender

    1Tilburg -- Eric Schiller and Bill Cone

    1Traveller Standard v3 -- Alan Cowderoy

  • border, values can be either 'single' or 'double' (default is 'single'.)

  • corner, values can be either 'square' or 'rounded' (default is 'square'.)

  • legend, values can be either 'yes' or 'no' (default is 'no'.)

  • size, value ranging from 1 to 6 that controls the size of the embedded diagram (default is 5.)

  Note -- not all fonts support all combinations of 'border', 'corner' and 'legend'. No warnings or errors will be generated by unsupported options, you get the best a font can do, no more!

EXPORT

filter - given a source file and specification, convert to supported output. See details in Description.

DEPENDENCIES

use Chess::PGN::Parse;

use Chess::PGN::EPD;

use Text::DelimMatch;

TODO

• Add other output types, PDF, DHTML, LaTeX.

• Handle recursive annotation variations...what you call RAVs!

KNOWN BUGS

None known; Unknown? Of course, though I try to be neat...

AUTHOR

Hugh S. Myers

Always: hsmyers@sdragons.com