icu_tournament 1.1.2 → 1.2.0

data/README.rdoc

@@ -5,15 +5,12 @@ For reading or writing files of chess tournament data. Original project name on
 
 == Install
 
-The gem is hosted on gemcutter only:
+For ruby 1.9.2 (version 1.1.2 was the last compatible with ruby 1.8.7).
 
-  sudo gem install icu_tournament
+  gem install icu_tournament
 
+For name canonicalisation, _icu_name_ is required.
 For handling SwissPerfect files the _dbf_, _inifile_ and _rubyzip_ gems are required.
-For Ruby prior to version 1.9 the _fastercsv_ gem is needed to handle CSV files.
-
-Tested with ruby 1.8.7, 1.9.2.
-
 
 == Usage
 
@@ -31,7 +28,6 @@ The currently supported formats are:
 * ICU::Tournament::ForeignCSV - used by Irish players to report their individual results in foreign tournaments.
 * ICU::Tournament::SwissPerfect - often used by Irish tournament controllers to report results.
 
-
 == Writing Files
 
 Here's how the 1972 Fischer-Spassky match could be formatted to Krause. First a tournament object is created
@@ -60,7 +56,6 @@ Then finally, to create the file:
 
   open('match.txt', 'w') { |f| f.puts @t.serialize('Krause') }
 
-
 == Reading Files
 
 Suppose you have a tournament file in Krause format. Parse it into a tournament object like this:

data/lib/icu_tournament.rb

@@ -1,7 +1,10 @@
 # :enddoc:
 
+require 'rubygems'
+require 'icu_name'
+
 icu_tournament_files = Array.new
-icu_tournament_files.concat %w{util name federation}
+icu_tournament_files.concat %w{util federation}
 icu_tournament_files.concat %w{player result team tournament}
 icu_tournament_files.concat %w{fcsv krause sp}.map{ |f| "tournament_#{f}"}
 

data/lib/icu_tournament/federation.rb

@@ -1,73 +1,67 @@
 module ICU
-
-=begin rdoc
-
-== Federations
-
-This class can be used to map a string into an object representing a chess federation.
-In FIDE, chess federations are generally either referred to by their full names such as
-_Ireland_ or _Russia_ or by three letter codes such as _IRL_ or _RUS_. The three letter
-codes are mostly the same as those found in the international standard known as
-{ISO 3166-1 alpha-3}[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3], but with
-some differences (e.g. for England, Scotland and Wales).
-
-You cannot directly create instances of this class using _new_. Instead, you supply
-a string to the class method _find_ and, if the string supplied uniguely identifies a
-federation, an instance is returned which responds to _name_ and _code_.
-
-  fed = ICU::Federation.find('IRL')
-  fed.name                                           # => "Ireland"
-  fed.code                                           # => "IRL"
-
-If the string is not sufficient to identify a federation, the _find_ method returns _nil_.
-
-  fed = ICU::Federation.find('ZYX')                  # => nil
-
-If the string is three letters long and matches (case insenstively) one of the unique
-federation codes, then the instance corresponding to that federation is returned.
-
-  ICU::Federation.find('rUs').code                   # => "RUS"
-
-If the string is more than three letters long and if it is a substring (case insensitive)
-of exactly one federation name, then that federation is returned.
-
-  ICU::Federation.find('ongoli').name                # => "Mongolia"
-
-In all other cases, nil is returned. In the following example, the string matches more than one federation.
-
-  ICU::Federation.find('land')                       # => nil
-
-The method is not fooled by irrelevant white space.
-
-  ICU::Federation.find('  united   states   ').code  # => 'USA'
-
-The class method _menu_ will return an array of two-element arrays each of which contain a name
-and a code.
-
-  ICU::Federation.menu                               # => [['Afghanistan', 'AFG'], ['Albania', 'ALB], ...]
-
-Such an array could be used, for example, as the basis of a selection menu in a web application.
-Various options are available to alter the array returned. Use the _:order_ option to order by code
-instead of the default (by country name).
-
-  ICU::Federation.menu(:order => 'code')             # => [..., ['Ireland', 'IRL'], ['Iraq', 'IRQ], ...]
-
-To put one country at the top (followed by the rest, in order) supply the country's code with the _:top_ option:
-  
-  ICU::Federation.menu(:top => 'IRL')                # => [['Ireland', 'IRL'], ['Afghanistan', 'AFG], ...]
-
-To supply an extra "None" item at the top, specify its label with the _:none_ option:
-  
-  ICU::Federation.menu(:none => 'None')              # => [['None', ''], ['Afghanistan', 'AFG], ...]
-
-The "None" option's code is the empty string and it come above the "top" option if both are specified.
-
-=end
-
+  #
+  # This class can be used to map a string into an object representing a chess federation.
+  # In FIDE, chess federations are generally either referred to by their full names such as
+  # _Ireland_ or _Russia_ or by three letter codes such as _IRL_ or _RUS_. The three letter
+  # codes are mostly the same as those found in the international standard known as
+  # {ISO 3166-1 alpha-3}[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3], but with
+  # some differences (e.g. for England, Scotland and Wales).
+  #
+  # You cannot directly create instances of this class using _new_. Instead, you supply
+  # a string to the class method _find_ and, if the string supplied uniguely identifies a
+  # federation, an instance is returned which responds to _name_ and _code_.
+  #
+  #   fed = ICU::Federation.find('IRL')
+  #   fed.name                                           # => "Ireland"
+  #   fed.code                                           # => "IRL"
+  #
+  # If the string is not sufficient to identify a federation, the _find_ method returns _nil_.
+  #
+  #   fed = ICU::Federation.find('ZYX')                  # => nil
+  #
+  # If the string is three letters long and matches (case insenstively) one of the unique
+  # federation codes, then the instance corresponding to that federation is returned.
+  #
+  #   ICU::Federation.find('rUs').code                   # => "RUS"
+  #
+  # If the string is more than three letters long and if it is a substring (case insensitive)
+  # of exactly one federation name, then that federation is returned.
+  #
+  #   ICU::Federation.find('ongoli').name                # => "Mongolia"
+  #
+  # In all other cases, nil is returned. In the following example, the string matches more than one federation.
+  #
+  #   ICU::Federation.find('land')                       # => nil
+  #
+  # The method is not fooled by irrelevant white space.
+  #
+  #   ICU::Federation.find('  united   states   ').code  # => 'USA'
+  #
+  # The class method _menu_ will return an array of two-element arrays each of which contain a name
+  # and a code.
+  #
+  #   ICU::Federation.menu                               # => [['Afghanistan', 'AFG'], ['Albania', 'ALB], ...]
+  #
+  # Such an array could be used, for example, as the basis of a selection menu in a web application.
+  # Various options are available to alter the array returned. Use the _:order_ option to order by code
+  # instead of the default (by country name).
+  #
+  #   ICU::Federation.menu(:order => 'code')             # => [..., ['Ireland', 'IRL'], ['Iraq', 'IRQ], ...]
+  #
+  # To put one country at the top (followed by the rest, in order) supply the country's code with the _:top_ option:
+  #
+  #   ICU::Federation.menu(:top => 'IRL')                # => [['Ireland', 'IRL'], ['Afghanistan', 'AFG], ...]
+  #
+  # To supply an extra "None" item at the top, specify its label with the _:none_ option:
+  #
+  #   ICU::Federation.menu(:none => 'None')              # => [['None', ''], ['Afghanistan', 'AFG], ...]
+  #
+  # The "None" option's code is the empty string and it come above the "top" option if both are specified.
+  #
   class Federation
     attr_reader :code, :name
     private_class_method :new
-    
+
     # Given a code, name or part of a name, return the corresponding federation instance.
     # If there is no match or more than one match, _nil_ is returned.
     def self.find(str=nil)
@@ -86,7 +80,7 @@ The "None" option's code is the empty string and it come above the "top" option
       return nil unless matches.length == 1
       matches[0]
     end
-    
+
     def self.menu(opts = {})
       compile unless @@objects;
       top, menu = nil, []
@@ -96,14 +90,14 @@ The "None" option's code is the empty string and it come above the "top" option
       menu.unshift([opts[:none], '']) if opts[:none]
       menu
     end
-    
+
     def initialize(code, name) # :nodoc: because new is private
       @code = code
       @name = name
     end
-    
+
     private
-    
+
     def self.compile
       return if @@objects
       @@names = Hash.new
@@ -118,10 +112,10 @@ The "None" option's code is the empty string and it come above the "top" option
         end
       end
     end
-    
+
     # The data structures compiled.
     @@objects, @@codes, @@names = nil, nil, nil
-    
+
     # An array of data that gets compiled into other data structures.
     @@data =
     [

data/lib/icu_tournament/player.rb

@@ -1,100 +1,94 @@
 module ICU
-
-=begin rdoc
-
-== Player
-
-A player in a tournament must have a first name, a last name and a number
-which is unique in the tournament but otherwise arbitary.
-
-  bobby = ICU::Player.new('robert j', 'fischer', 17)
-
-Names are automatically cannonicalised (tidied up).
-
-  bobby.first_name                 # => 'Robert J.'
-  bobby.last_name                  # => 'Fischer'
-
-In addition, players have a number of optional attributes which can be specified
-via setters or in constructor hash options: _id_ (local or national ID), _fide_
-(FIDE ID), _fed_ (federation), _title_, _rating_, _rank_ and _dob_ (date of birth).
-
-  peter = ICU::Player.new('Peter', 'Svidler', 21, :fed => 'rus', :title => 'g', :rating = 2700)
-  peter.dob = '17th June, 1976'
-  peter.rank = 1
-
-Some of these values will also be canonicalised to some extent. For example,
-date of birth will be turned into _yyyy-mm-dd_ format, the chess title will be two
-to three capital letters always ending in _M_ and the federation, if it's three
-letters long, will be upcased.
-
-  peter.dob                        # => 1976-07-17
-  peter.title                      # => 'GM'
-  peter.fed                        # => 'RUS'
-
-It is preferable to add results (ICU::Result) to a player via the tournament (ICU::Tournament) object's
-_add_result_ method rather than the method of the same name belonging to player instances. Doing so
-allows mirrored results to be added to both players with one call (e.g. one player won, so the
-other lost). A player's results can later be retieved via the _results_ accessor.
-
-Total scores is available via the _points_ method.
-
-  peter.points                     # => 5.5
-
-A player can have up to two ID numbers (both positive integers or nil): _id_ (local or national ID,
-such as ICU number) and _fide_ (FIDE ID).
-
-  peter.id = 16790                 # ICU
-  peter.fide = 4102142             # FIDE
-
-Players can be compared to see if they're roughly or exactly the same, which may be useful in detecting duplicates.
-If the names match and the federations don't disagree then two players are equal according to the _==_ operator.
-The player number is irrelevant.
-
-  john1 = ICU::Player.new('John', 'Smith', 12)
-  john2 = ICU::Player.new('John', 'Smith', 22, :fed = 'IRL')
-  john2 = ICU::Player.new('John', 'Smith', 32, :fed = 'ENG')
-
-  john1 == john2                   # => true (federations don't disagree because one is unset)
-  john2 == john3                   # => false (federations disagree)
-
-If, in addition, _rating_, _dob_, _gender_, _id_ and _fide_ do not disagree then two players are equal
-according to the stricter criteria of _eql?_.
-
-  mark1 = ICU::Player.new('Mark', 'Orr', 31, :fed = 'IRL', :rating => 2100)
-  mark2 = ICU::Player.new('Mark', 'Orr', 33, :fed = 'IRL', :rating => 2100, :title => 'IM')
-  mark3 = ICU::Player.new('Mark', 'Orr', 37, :fed = 'IRL', :rating => 2200, :title => 'IM')
-
-  mark1.eql?(mark2)                # => true (ratings agree and titles don't disagree)
-  mark2.eql?(mark3)                # => false (the ratings are not the same)
-
-The presence of two players in the same tournament that are equal according to _==_ but unequal
-according to _eql?__ is likely to indicate a data entry error.
-
-If two instances represent the same player and are equal according to _==_ then the _id_, _fide_, _rating_,
-_title_ and _fed_ attributes of the two can be merged. For example:
-
-  fox1 = ICU::Player.new('Tony', 'Fox', 12, :id => 456)
-  fox2 = ICU::Player.new('Tony', 'Fox', 21, :rating => 2100, :fed => 'IRL', :gender => 'M')
-  fox1.merge(fox2)
-
-Any attributes present in the second player but not in the first are copied to the first.
-All other attributes are unaffected.
-
-  fox1.rating                      # => 2100
-  fox1.fed                         # => 'IRL'
-  fox1.gender                      # => 'M'
-
-=end
-
+  #
+  # A player in a tournament must have a first name, a last name and a number
+  # which is unique in the tournament but otherwise arbitary.
+  #
+  #   bobby = ICU::Player.new('robert j', 'fischer', 17)
+  #
+  # Names are automatically cannonicalised (tidied up).
+  #
+  #   bobby.first_name                 # => 'Robert J.'
+  #   bobby.last_name                  # => 'Fischer'
+  #
+  # In addition, players have a number of optional attributes which can be specified
+  # via setters or in constructor hash options: _id_ (local or national ID), _fide_
+  # (FIDE ID), _fed_ (federation), _title_, _rating_, _rank_ and _dob_ (date of birth).
+  #
+  #   peter = ICU::Player.new('Peter', 'Svidler', 21, :fed => 'rus', :title => 'g', :rating = 2700)
+  #   peter.dob = '17th June, 1976'
+  #   peter.rank = 1
+  #
+  # Some of these values will also be canonicalised to some extent. For example,
+  # date of birth will be turned into _yyyy-mm-dd_ format, the chess title will be two
+  # to three capital letters always ending in _M_ and the federation, if it's three
+  # letters long, will be upcased.
+  #
+  #   peter.dob                        # => 1976-07-17
+  #   peter.title                      # => 'GM'
+  #   peter.fed                        # => 'RUS'
+  #
+  # It is preferable to add results (ICU::Result) to a player via the tournament (ICU::Tournament) object's
+  # _add_result_ method rather than the method of the same name belonging to player instances. Doing so
+  # allows mirrored results to be added to both players with one call (e.g. one player won, so the
+  # other lost). A player's results can later be retieved via the _results_ accessor.
+  #
+  # Total scores is available via the _points_ method.
+  #
+  #   peter.points                     # => 5.5
+  #
+  # A player can have up to two ID numbers (both positive integers or nil): _id_ (local or national ID,
+  # such as ICU number) and _fide_ (FIDE ID).
+  #
+  #   peter.id = 16790                 # ICU
+  #   peter.fide = 4102142             # FIDE
+  #
+  # Players can be compared to see if they're roughly or exactly the same, which may be useful in detecting duplicates.
+  # If the names match and the federations don't disagree then two players are equal according to the _==_ operator.
+  # The player number is irrelevant.
+  #
+  #   john1 = ICU::Player.new('John', 'Smith', 12)
+  #   john2 = ICU::Player.new('John', 'Smith', 22, :fed = 'IRL')
+  #   john2 = ICU::Player.new('John', 'Smith', 32, :fed = 'ENG')
+  #
+  #   john1 == john2                   # => true (federations don't disagree because one is unset)
+  #   john2 == john3                   # => false (federations disagree)
+  #
+  # If, in addition, _rating_, _dob_, _gender_, _id_ and _fide_ do not disagree then two players are equal
+  # according to the stricter criteria of _eql?_.
+  #
+  #   mark1 = ICU::Player.new('Mark', 'Orr', 31, :fed = 'IRL', :rating => 2100)
+  #   mark2 = ICU::Player.new('Mark', 'Orr', 33, :fed = 'IRL', :rating => 2100, :title => 'IM')
+  #   mark3 = ICU::Player.new('Mark', 'Orr', 37, :fed = 'IRL', :rating => 2200, :title => 'IM')
+  #
+  #   mark1.eql?(mark2)                # => true (ratings agree and titles don't disagree)
+  #   mark2.eql?(mark3)                # => false (the ratings are not the same)
+  #
+  # The presence of two players in the same tournament that are equal according to _==_ but unequal
+  # according to _eql?__ is likely to indicate a data entry error.
+  #
+  # If two instances represent the same player and are equal according to _==_ then the _id_, _fide_, _rating_,
+  # _title_ and _fed_ attributes of the two can be merged. For example:
+  #
+  #   fox1 = ICU::Player.new('Tony', 'Fox', 12, :id => 456)
+  #   fox2 = ICU::Player.new('Tony', 'Fox', 21, :rating => 2100, :fed => 'IRL', :gender => 'M')
+  #   fox1.merge(fox2)
+  #
+  # Any attributes present in the second player but not in the first are copied to the first.
+  # All other attributes are unaffected.
+  #
+  #   fox1.rating                      # => 2100
+  #   fox1.fed                         # => 'IRL'
+  #   fox1.gender                      # => 'M'
+  #
+  #
   class Player
-    
     extend ICU::Accessor
     attr_integer :num
     attr_positive_or_nil :id, :fide, :rating, :rank
     attr_date_or_nil :dob
-    
+
     attr_reader :results, :first_name, :last_name, :fed, :title, :gender
-    
+
     # Constructor. Must supply both names and a unique number for the tournament.
     def initialize(first_name, last_name, num, opt={})
       self.first_name = first_name
@@ -105,33 +99,33 @@ All other attributes are unaffected.
       end
       @results = []
     end
-    
+
     # Canonicalise and set the first name(s).
     def first_name=(first_name)
       name = Name.new(first_name, 'Last')
       raise "invalid first name" unless name.first.length > 0
       @first_name = name.first
     end
-    
+
     # Canonicalise and set the last name(s).
     def last_name=(last_name)
       name = Name.new('First', last_name)
       raise "invalid last name" unless name.last.length > 0 && name.first.length > 0
       @last_name = name.last
     end
-    
+
     # Return the full name, last name first.
     def name
       "#{last_name}, #{first_name}"
     end
-    
+
     # Federation. Is either unknown (nil) or a string containing at least three letters.
     def fed=(fed)
       obj = Federation.find(fed)
       @fed = obj ? obj.code : nil
       raise "invalid federation (#{fed})" if @fed.nil? && fed.to_s.strip.length > 0
     end
-    
+
     # Chess title. Is either unknown (nil) or one of: _GM_, _IM_, _FM_, _CM_, _NM_,
     # or any of these preceeded by the letter _W_.
     def title=(title)
@@ -142,7 +136,7 @@ All other attributes are unaffected.
       @title = nil if @title == ''
       raise "invalid chess title (#{title})" unless @title.nil? || @title.match(/^W?[GIFCN]M$/)
     end
-    
+
     # Gender. Is either unknown (nil) or one of _M_ or _F_.
     def gender=(gender)
       @gender = gender.to_s.strip[0,1].upcase
@@ -150,7 +144,7 @@ All other attributes are unaffected.
       @gender = 'F' if @gender == 'W'
       raise "invalid gender (#{gender})" unless @gender.nil? || @gender.match(/^[MF]$/)
     end
-    
+
     # Add a result. Don't use this method directly - use ICU::Tournament#add_result instead.
     def add_result(result)
       raise "invalid result" unless result.class == ICU::Result
@@ -165,17 +159,17 @@ All other attributes are unaffected.
         @results.insert(i, result)
       end
     end
-    
+
     # Lookup a result by round number.
     def find_result(round)
       @results.find { |r| r.round == round }
     end
-    
+
     # Return the player's total points.
     def points
       @results.inject(0.0) { |t, r| t += r.points }
     end
-    
+
     # Renumber the player according to the supplied hash. Return self.
     def renumber(map)
       raise "player number #{@num} not found in renumbering hash" unless map[@num]
@@ -183,7 +177,7 @@ All other attributes are unaffected.
       @results.each{ |r| r.renumber(map) }
       self
     end
-    
+
     # Loose equality test. Passes if the names match and the federations are not different.
     def ==(other)
       return true if equal?(other)
@@ -193,7 +187,7 @@ All other attributes are unaffected.
       return false if @fed && other.fed && @fed != other.fed
       true
     end
-    
+
     # Strict equality test. Passes if the playes are loosly equal and also if their IDs, rating, gender and title are not different.
     def eql?(other)
       return true if equal?(other)
@@ -203,7 +197,7 @@ All other attributes are unaffected.
       end
       true
     end
-    
+
     # Merge in some of the details of another player.
     def merge(other)
       raise "cannot merge two players that are not equal" unless self == other