NAME

AGATourn - Perl extensions to ease the pain of using AGA tournament data files.

SYNOPSIS

use Games::Go::AGATourn;

my $agaTourn = Games::Go::AGATourn->new (options);

DESCRIPTION

An AGATourn object represents a round or several rounds of an American Go Association tournament. There are methods for parsing several type of AGA file format:

tdlist

The entire list of AGA members including playing strength, club affiliation, and some other stuff.

register.tde

The starting point for a tournament. All players in a tournament must be entered in the register.tde file.

round results: 1.tde, 2.tde, etc.

Game results for each round of the tournament.

A note on IDs: in general, hashes in an AGATourn object are keyed by the AGA ID. An AGA ID consists of a three letter country specifier (like USA or TMP for temporary IDs) concatenated to an integer. Here we specify the three letter country specifier as the 'country' and the integer part as the 'agaNum'. The country concatenated with the agaNum is the ID. My ID for example is USA2122. IDs should be normalized (capitalize the country part and remove preceding 0s from the agaNum part) with the NormalizeID method (below).

Note also that some programs may accept limited integers in the agaNum part of the ID. Accelerat, for example, seems to accept only up to 32K (someone used a signed short somewhere?)

METHODS

my $agaTourn = Games::Go::AGATourn->new (options)

A new AGATourn by default reads the register_tde file to get the name, rank, and AGA numbers for all the players in the tournament. It then reads all available game results (Round files: 1.tde, 2.tde, etc.) and the game data is incorporated into the AGATourn object.

Options:

Round

Round file number to read. If Round is 0, no round files are read. If Round is 1 or greater, only the one round file will be read. If round is undef (or not specified), all existing round files are read. Round files should be named 1.tde, 2.tde, etc.

Default: undef

register_tde

Name of register.tde file. Use undef to prevent reading the register.tde file. Changing the name of this file is probably a bad idea.

Default 'register.tde' (in the current directory)

nameLength

Starting length of name field. While reading the register file (see ReadRegisterFile below), nameLength grows to reflect the longest name seen so far (see NameLength method below).

Default: 0

defaultCountry

Default three-letter country name.

The tdlist file does not include country information in the ID, so the ParseTdListLine method returns country => defaultCountry.

Default: 'USA'

$agaTourn->Clear

Clears AGATourn database.

my $hash = $agaTourn->ParseTdListLine ($line)

Parses a single line from the TDLIST file (the latest TDLIST file should be downloaded from the AGA at http://usgo.org shortly before the tournament, and either the tab-delimited tdlista or the space-delimited versions are accepted). The return value is a reference to a hash of the following values: agaNum => the number part if the ID country => the country part of the ID (always the default country) name => complains if there is no a comma memType => membership type or '' if none agaRating => rating in decimal form, or '' if none agaRank => undef unless rating is a D/K style rank expire => date membership expires or '' if none club => club affiliation or '' if none state => state or '' if none

If the line is not parsable, prints a warning and returns undef.

my $result = $agaTourn->ReadRegisterFile ($fileName)

Reads a register.tde file and calls AddRegisterLine on each line of the file.

Returns 0 if $fileName couldn't be opened for reading, 1 otherwise.

$agaTourn->AddRegisterLine ($line)

Calls ParseRegisterLine on $line. Information extracted about players and directives is added to the $agaTourn object. Comments and blank lines are ignored.

my $hash = $agaTourn->ParseRegisterLine ($line)

Parses a single line from the register.tde file (name lines). Here are some examples lines from register.tde file:

# this line is a comment.  the following line is a directive:
## HANDICAPS MAX
# the following line is a name line:
USA02122 Augustin, Reid    5.0 CLUB=PALO    # 12/31/2004 CA

The return value is a reference to a hash of the following values: agaNum => just the number part of the ID country => just the country part of the ID (default ='USA') name => complains if name doesn't contain a comma agaRating => rating for the player agaRank => undef if line contains a rating and not a rank club => if there is a club association, '' if not flags => anything left over (excluding comment) comment => everything after the #, '' if none

If the line is a directive, the return hash reference contains only: directive => the directive name value => the directive value ('' if none)

If the line is a comment, leading and trailing whitespace is removed and the hash contains only: comment => comment contents (may be '')

If the line is empty, returns undef.

If the line is not parsable, prints a warning and returns undef.

my $result = $agaTourn->ReadRoundFile ($fileName)

Reads a round file and calls AddRoundLine on each line of the file. Complains if filename is not in the form 1.tde, 2.tde, etc.

Sets the current Round number to the digit part of fileName.

Returns 0 if fileName couldn't be opened for reading, 1 otherwise.

$agaTourn->AddRoundLine ($line)

Parses $line (by calling ParseRoundLine) and adds the information to the GamesList. Games without a result ('?') increment both players' NoResults list scores, and games with a result ('b' or 'w') increment the two players' Wins and Losses scores. If the game result is 'b' or 'w', the black player is added to the white player's Played list and vica-versa. Note that Played is not affected by games that are not complete.

Complains if either player, or both, are not registered via AddRegisterLine.

my $hash = $agaTourn->ParseRoundLine ($line)

Parses a single line from a results file (1.tde, 2.tde, etc). Here's an example line from a results file:

  TMP18  TMP10   b     0     7   # Lee, Ken -28.5 : Yang, John -28.5
# wID    bID   result handi komi   comment

The return value is a reference to a hash of the following values: wcountry => combine with wagaNum to get complete ID wagaNum => the number part of white's AGA number bcountry => combine with bagaNum to get complete ID bagaNum => the number part of black's AGA number result => winner: 'b', 'w' or '?' handi => handicap game was played with komi => komi game was played with comment => everything after the #

If $line is empty, returns undef.

If $line is a comment, returns only: comment => everything after the #

If the line is not parsable, prints a warning and returns undef.

my $tourney = $agaTourn->Tourney

Returns the name of the tournament from a ##TOURNEY directive added via AddRegisterLine, or 'Unknown Tournament' if no TOURNEY directive has been added.

my $directive = $agaTourn->Directive ($directive)

Returns a list (or a reference to the list in scalar context) of directives added via calls to AddRegisterLine. Directive names are always turned into upper case (but the case of the directive value, if any, is preserved).

Since some directives (like BAND) may occur several times, all directives are stored as a list in the order added (either from ReadRegisterFile or AddRegisterLine). Certain directives (HANDICAPS ROUNDS RULES TOURNEY) keep only the last directive added.

Some directives have no associated value.

Directive returns undef if $directive has not been added, or a list (possibly empty) if $directive has been added.

If called with no arguments (or $directive is undef), returns a reference to a hash of all the current directives.

my $rounds = $agaTourn->Rounds

Returns the total number of rounds the $agaTourn object knows about. If there has been a ##ROUNDS directive in a call to AddRegisterLine file, this will return that number. If not, it will return the number part of the last round_number.tde file read or undef.

my $round = $agaTourn->Round

Returns the number of the current round (based on the last round_number.tde file read).

my $name = $agaTourn->Name ($id)

Returns the the name for $id.

If $id is undef, returns a reference to the entire Name hash (keyed by ID).

my $name_length = $agaTourn->NameLength

Returns the length of the longest name.

my $rating = $agaTourn->Rating ($id, $newRating)

Sets (if $newRating is defined) or returns the rating for $id. If $id is not defined, returns a reference to the entire Rating hash (keyed by IDs).

$id can also be a rank ('4d', or '5k'), or a rating (4.2 or -5.3, but not between 1.0 and -1.0). This form is simply a converter - $newRating is not accepted.

If $id is defined but not registered (via AddRegisterLine), complains and returns undef.

my $rank = $agaTourn->Rank ($id)

Returns the rank for $id. This field is undef unless the AddRegisterLine contained a rank field of the form '4k' or '3d' as opposed to a rating of the form '-4.5' or '3.4'.

If $id is not defined, returns a reference to the entire Rank hash (keyed by IDs).

my $sigma = $agaTourn->Sigma ($id)

Returns the sigma for $id. Sigma is determined by the rating/rank in the AddRegisterLine. If the line contains a rank field of the form '4k' or '3d', sigma is 1.2 for 7k and stronger, and

(k - 0.3) / 6

for 8k and weaker. If the line contains a rating of the form '-4.5' or '3.4', sigma is 0.6 for -8.0 and stronger, and

(-rating - 4.4) / 6

for weaker than -8.0.

Complains and returns undef if $id is undefined or unregistered.

my $club = $agaTourn->Club ($id)

Returns the club for $id or '' if no club is known. Returns undef if $id is not registered (via AddRegisterLine).

If no $id parameter is passed, returns a reference to the entire Club hash (keyed by IDs).

my $flags = $agaTourn->Flags ($id)

Returns the flags for $id or '' if no flags are known. Flags are anything left over (excluding the comment) after the ID, name, rating, and club have been parsed by AddRegisterLine. It might include (for example) BYE or Drop. The case is preserved from the original line parsed.

Returns undef if $id is not registered (via AddRegisterLine). If no $id parameter is passed, returns a reference to the entire Flags hash (keyed by IDs).

$comment = $agaTourn->Comment ($id)

Returns the comment associated with $id line as added via AddRegisterLine.

If no $id argument is passed, returns a reference to the entire Comments hash (keyed by IDs).

my $error = $agaTourn->Error

If called with an argument, sets the error flag to the new value. Returns the current (or new) value of the error flag.

my $gamesList = $agaTourn->GamesList ($id, ...)

Returns a list (or a reference to the list in scalar context) of games played by player(s). If no player argument is passed, returns the list of all games.

Games are added via the ReadRoundFile or the AddRoundLine methods.

Entries in the returned list are comma separated strings. They can be parsed with:

my ($whiteID, $blackID, $result,
    $handicap, $komi, $round) = split(',', $agaTourn->GamesList[$index]);

my $wins = $agaTourn->Wins ($id)

Returns the number of winning games recorded for $id. Wins are recorded via the AddRoundLine method.

If no $id argument is passed, returns a reference to the entire Wins hash (keyed by IDs).

my $losses = $agaTourn->Losses ($id)

Returns the number of losing games recorded for $id. Losses are recorded via the AddRoundLine method.

If no $id argument is passed, returns a reference to the entire Losses hash (keyed by IDs).

my $no_results = $agaTourn->NoResults ($id)

Returns the number of no-result games recorded for $id. No-results are recorded via the AddRoundLine method.

If no $id argument is passed, returns a reference to the entire NoResults hash (keyed by IDs).

my @played = $agaTourn->Played ($id)

Returns a list (or a reference to the list in scalar context) of $id's opponents. The list is ordered as they were added by AddRoundLine method.

If no $id argument is passed, returns a reference to the entire Played hash (keyed by IDs).

my $rating = $agaTourn->RankToRating ($rank | $rating)

Returns a value guaranteed to be in a correct AGA Rating format. The format is a number with a tenths decimal, where the number represents the dan rank (if positive) or the kyu rank (if negative). A rating of 3.5 represents squarely in the middle of the 3 dan rank, and -1.9 represents a weak 1 kyu rank. The range from 1.0 to -1.0 is not used (see CollapseRating/ExpandRating below).

my $band_idx = $agaTourn->WhichBandIs ($rank | $rating)

Returns the band index for a rank or rating. Returns NOTARANK if rank/rating is not in any bands.

See also BandName below.

my $band_name = $agaTourn->BandName ($bandIndex)

Returns the name of a band specified by the bandIndex or undef of not known.

Scoring bands are specified via AddRegisterLine with ##BAND directives.

AGATourn complains if bands are specified with holes between them.

The bands are sorted (by strength) and indexed. BandName returns the original name (as specified in the ##BAND directive) from a band index.

my ($handicap, $komi) = $agaTourn->Handicap ($player1, $player2)

Returns the appropriate handicap and komi for two players. Players can be in any form acceptable to Rating.

If player1 is stronger than player two, the handicap is a positive number. If player1 is weaker than player2, (players need to be swapped), the returned handicap is a negative number. If the handicap would normally be 0 and the players need to be swapped, the returned handicap is -1.

A handicap of 1 is never returned. The returned handicap and komi are always integers (you may assume that komi needs a additional half-point if you like).

If either player1 or player2 is invalid, Handicap complains (during the call to Rating for the player) and returns (-1, -1).

Handicap uses the following table (same as the AGA handicap practice):

 rating     handi Ing   AGA
 diff             Komi  Komi
0.000-0.650   0     7     6    even, normal komi
0.651-1.250   0    -1*    0    no komi  (* black wins ties under Ing)
1.251-2.200   0    -7    -6    reverse komi
2.201-3.300   2    -2     0    two stones
3.301-4.400   3    -3     0    three stones ...

my $collapsed_rating = $agaTourn->CollapseRating ($aga_rating)

AGA ratings have a hole between 1.0 and -1.0. This method fills the hole by adding 1 to kyu ratings and subtracting 1 from dan ratings. If $aga_rating is between 1.0 and -1.0, complains and returns the original $rating.

my $AGA_rating = $agaTourn->ExpandRating ($collapsed_rating)

AGA ratings have a hole between 1.0 and -1.0. This method converts a continuous rating with no hole into a valid AGA rating by adding 1 to ratings greater than 0 and subtracting 1 from ratings less than 0.

my $normalized_id = $agaTourn->NormalizeID ($id)

Performs normalization of $id so the we can compare variations of $id without considering them as different. Normalization consists of turning the country part of $id to all upper-case and removing leading zeros from the number part.

All $ids used as hash keys should be normalized.

SEE ALSO

o tdfind(1) - prepare register.tde for an AGA Go tournament

o aradjust(1) - adjust pairings and enter results for a round

o tscore(1) - score a tournament

o send2AGA(1) - prepare tournament result for sending to AGA

AUTHOR

Reid Augustin, <reid@netchip.com>

COPYRIGHT AND LICENSE

Copyright (C) 1999, 2004, 2005 by Reid Augustin

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.