NAME

Games::Go::AGA::Parse::Register - models AGA register.tde file information

VERSION

version 0.042

SYNOPSIS

  use Games::Go::AGA::Parse::Register;
  my $parser = Games::Go::AGA::Parse::Register->new;

  $parser->parse_line('line from register.tde file'); # parse a line

DESCRIPTION

Games::Go::AGA::Parse::Register parses single lines from an AGA register.tde format file and returns a reference to a hash representing the contents of the line.

register.tde files contain the tournemant registration information for an American Go Association (AGA) go tournament. There are three types of line that can occur in a register file: directives, comments, and player information:

    ## directive
    # comment
    id last name, first name  rank  CLUB=club DROP # comment

Directives are global configuration for the tournament, and include such things as TOURNEY (the tournament name), RULES (e.g. Ing or AGA), etc.

Comments may contain any text which is ignored.

Player information lines contain the registration information.

METHODS

my $parser = Games::Go::AGA::Parse::Register->new;

Creates a new parser object.

my $parser = $parser->filename( ['new_name'])

Get/set a filename (used in error messages)

my $file_handle = $parser->filename( [$new_file_handle ])

Get/set a file handle (used in error messages)

my $hash_ref = $parser->parse_line('line');

line is a line of text from a register.tde format file.

The return value is the same as returned by $parser->as_hash

%as_hash = $parser->as_hash()

Retuns the parsed line as a hash. Missing fields will be empty strings ('').

There are three 'flavors' of hash depending on which of the three types of line is parsed:

Directives

A directives line is a 'key/value' pair and is returned as:

    (
        directive    => 'directive name'
        value        => 'directive value'
    )

Comments

A comment line is returned as:

    (
        comment      => 'the comment'
    )

Player

A player line is returned as:

    (
        id          => 'unique identifier'  # AGA ID or temporary ID
        last_name   => 'last name'          # may contain spaces
        first_name  => 'first name'         # may contain spaces
        rank        => 'rank or rating'     # either a rank or a rating
        flags       => [flag1, ...]         # ref to array of flags (DROP,
                                            #    DROPn, BYE, BAR=Foo, etc)
        club        => 'club'               # a CLUB=XYZ flag is turned into this
        comment     => 'comment field'      # player comment
    )

id is single token, unique per player (usually the AGA ID).

From after the ID to the first comma (',') is the player's last_name.

From after the comma to the rank is the first_name.

If no comma is found, the first_name field is not defined.

rank may be either a dan/kuy rank or an AGA numeric rating. If it is a rank, it is an integer followed by either D, or K (for dan or kyu). If it is a rating, it is a decimal number between 20 and -99 excluding the range from .9999 to -.9999. Positive numbers represent dan and negative represent kyu. The convention is that decimal numbers (ratings) represent a more reliable value than the D/K representation.

flags formed with an equals sign (e.g. Bar=Foo) are returned as a single array element, and the key is upper-cased ('Bar' is changed to 'BAR' in this example).

DROPn flags refer to specific rounds (n).

For historical reasons, DROPn may be found in the comment section. If so, they are removed from the comment and added to the flags.

Note that the 'Club=' flag is handled differently: it is removed from the flags list and the club name is instead loaded into the club field.

flags may be a reference to an empty array. comments may be an empty string.

In scalar context, returns a reference to the hash.

@as_array = $parser->as_array()

Retuns the parsed line as an array. Missing fields will be empty strings (''). The order is the same as listed above for as_hash.

In scalar context, returns a reference to the array.

$field_by_name = $parser-> < name >

Individual fields may be set or retrieved by name. E.g:

    $last_name = $parser->last_name
     . . .
    $parser->rank('4d');

OPTIONS

Options to the ->new method are:

filename => 'file name'

handle => $file_handle

These are not required to create a parser, but if supplied, error exceptions will include more useful information.

AUTHOR

Reid Augustin <reid@hellosix.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Reid Augustin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.