NAME
Games::Go::AGA::DataObjects::Register - models AGA register.tde file information
VERSION
version 0.152
SYNOPSIS
use Games::Go::AGA::DataObjects::Register;
my $reg = Games::Go::AGA::DataObjects::Register->new();
$reg->insert_player_at_idx($idx, $player);
my $player_list = $reg->players; # get ref to list of playersDESCRIPTION
A Games::Go::AGA::DataObjects::Register represents the information in a register.tde file. register.tde contains tournemant registration information for an American Go Association (AGA) go tournament. The format is like this:
## directive
# comment
id last name, first name rank CLUB=club DROP # COMMENTThese three types of line are stored in this object in the corresponding attributes:
- comments ref to Array (full line comments, in order)
- players ref to Array of Games::Go::AGA::DataObjects::Player
- directives a Games::Go::AGA::DataObjects::Directives object
Directives are global configuration for the tournament, and include such things as TOURNEY (the tournament name), RULES (e.g. Ing or AGA), etc.
id is single token, unique per player (usually the AGA ID).
Following id to the first comma (',') is the player's last_name.
Following the comma to the rank is the first_name.
rank is either an integer followed by D, d, K, or k (for dan or kyu), or it is a decimal number less than 20 and greater than -100 but excluding the range from .9999 to -.9999 where positive numbers represent dan and negative represent kyu. The convention is that a decimal number (rating) represents a more reliable estimate than a D/K representation (rank). Note: the TDListN.txt file from the AGA includes ratings of 0.0 to indicate unknown rank. Converting these to (i.e.) 30k is reasonable.
CLUB=... is optional. A tournament pairing system may choose to avoid pairing players who belong to the same club.
DROP is optional and indicates the players who will not participate in any future rounds. An enhancement is to allow DROPn where 'n' indicates specific round numbers to drop.
COMMENT is optional and may contain any information.
METHODS
- comments
-
Returns a reference to a copy of the comments list. Since this is a copy, you cannot add or remove comments by altering this list.
- players
-
In array context, returns a copy of the players list. Since this is a copy, you cannot add or remove players by altering this list.
In scalar context, returns a reference to the player list.
- id_is_duplicate ($id, $player | undef )
-
$id is normalized and checked for validity. If valid, it is checked for duplicatation in the existing list of players. If $player is defined and in the list, matching $player's ID is not considered a duplication. To check against all existing players, pass explicit an 'undef' parameter:
$register->id_is_duplicate($id, undef); - insert_player_at_idx ($idx, $player)
-
$player is a Games::Go::AGA::DataObjects::Player to be added to the players array. $idx is the index of the player to insert before. If $idx is out of bounds (-1 for example), adds $player to the end of the list.
Throws an error if $player's id duplicates an existing ID.
- get_player_idx ($player) # index of player in list
- get_player ($player) # actual player object
-
These methods find and return a player index (in the players list), or the Games::Go::AGA::DataObjects::Player. $player can be any of:
- the ID of the player to retrieve
- the index of the player
- a Games::Go::AGA::DataObjects::Player object
Throws an exception if $player is not found or is out of bounds.
- delete_player ($player)
-
Removes and returns a Games::Go::AGA::DataObjects::Player. $player may be any of the items listed for get_player, and throws an exception in the same circumstances.
- @band_breaks = bands()
-
Bands are used to divide a tournament into groups for the purpose of allocating awards. For example, all Dan players might be in one band while the kyu players are divided into two bands: 10k and stronger, and 11K and below. Standings are then divided into these three groups.
Bands are defined with the BAND_BREAKS directive which is a sequence of ranks where the listed rank is always included in the group above that rank. For the example above with three bands:
## BAND_BREAKS 1D 10Kindicates the two band breaking points, and includes 9D to 1D players in the top group, 1K to 10K players in the middle group, and all others in the bottom group.
BAND_BREAKS may be entered in any order, but they will always be sorted in top down order (stronger breaks first). Ranks (2K, 3D) will be converted to Ratings (numerical) and integerizedd. A rank of 2D, for example, converts to a rating of 2.5. For bands, we want to include all 2Ds, from 2.0 to just below 3.0 in the same group. Converting to integers accomplishes this. Break points entered as Ratings (numeric) should also be integers (or like 2.0), but they will not be integerized, so you can split a in the middle of rank groups if you wish.
There is also a BANDS directive which declares how many bands to break the tournament into. If there is a BANDS directive but no BAND_BREAKS directive, then as soon as any band-related fetch occurs, this module attempts to find the best breaking points so as to place aproximately equal numbers of players in each band. This process creates a BAND_BREAKS directive.
For backwards compatibility, BAND (singular) directives are supported on entry, but will be converted to a BAND_BREAKS directive for read back.
The bands() method returns an array (or in scalar context, a reference to an array) whose elements are the band breaking points (as numerical ratings, not ranks). If there is no BAND_BREAKS directives, a single, all-inclusive band is assumed and this function returns an array consisting of -99 (99K).
The first element of the array is the rating above which a player falls into the top band (between 9D and the first element). A rating that is less than the first element and greater than the second element falls into the second strongest band, and so on.
- $band_idx = which_band_is($rank_or_rating);
-
Returns the index of the band that $rank_or_rating falls into. If there is no BAND_BREAKS directive, a single, all-inclusive band is assumed and this function returns 0 for all $rank_or_ratings.
$band_idx 0 is the strongest band with higher $band_idxs being lower in rank.
ATTRIBUTES
Accessor methods are defined for the following attributes:
- comments ref to Array (full line comments, in order)
- directives a Games::Go::AGA::DataObjects::Directives object
- change_callback reference to a function to call after a change
SEE ALSO
AUTHOR
Reid Augustin <reid@hellosix.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 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.