sanichi-chess_icu 0.2.6 → 0.2.7

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :minor: 2
-:patch: 6
+:patch: 7
 :major: 0

data/lib/player.rb

@@ -1,8 +1,84 @@
 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_ (either FIDE or national),
+_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,
+the date of birth conforms to a _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'
+
+Results (ICU::Result) should be added to players via the tournament (ICU::Tournament) object
+to which the player instance have been added. Their total score is available via the _points_ method.
+
+  peter.points                     # => 5.5
+
+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, none of _rating_, _dob_ and _id_ disagree then two players are equal according to _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 unequl)
+
+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_, _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')
+  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'
+
+=end
+
   class Player
     attr_accessor :first_name, :last_name, :num, :id, :fed, :title, :rating, :rank, :dob
     attr_reader :results
     
+    # 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
       self.last_name  = last_name
@@ -13,23 +89,26 @@ module ICU
       @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
     
-    # Player number. Any integer.
+    # Player number. Any integer is valid including zero and negative numbers, as long as it's unique in the tournament.
     def num=(num)
       @num = case num
         when Fixnum then num
@@ -49,7 +128,7 @@ module ICU
       raise "invalid ID (#{id})" unless @id.nil? || @id > 0
     end
     
-    # Federation. Is either unknown (nil) or contains at least three letters.
+    # Federation. Is either unknown (nil) or a string containing at least three letters.
     def fed=(fed)
       @fed = fed.to_s.strip
       @fed.upcase! if @fed.length == 3
@@ -57,7 +136,8 @@ module ICU
       raise "invalid federation (#{fed})" unless @fed.nil? || @fed.match(/[a-z]{3}/i)
     end
     
-    # Chess title. Is either unknown (nil) or one of a set of possibilities (after a little cleaning up).
+    # 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)
       @title = title.to_s.strip.upcase
       @title << 'M' if @title.match(/[A-LN-Z]$/)
@@ -65,7 +145,7 @@ module ICU
       raise "invalid chess title (#{title})" unless @title.nil? || @title.match(/^W?[GIFCN]M$/)
     end
     
-    # Elo rating. Is either unknown (nil) or a positive integer.
+    # Rating. Is either unknown (nil) or a positive integer.
     def rating=(rating)
       @rating = case rating
         when nil     then nil
@@ -76,7 +156,7 @@ module ICU
       raise "invalid rating (#{rating})" unless @rating.nil? || @rating > 0
     end
     
-    # Rank in the tournament. Is either unknown (nil) or a positive integer.
+    # Rank in the tournament. Is either unknown (nil) or a positive integer. Must be unique in the tournament.
     def rank=(rank)
       @rank = case rank
         when nil     then nil
@@ -112,7 +192,7 @@ module ICU
       @results.inject(0.0) { |t, r| t += r.points }
     end
     
-    # Loose equality test.
+    # Loose equality test. Passes if the names match and the federations are not different.
     def ==(other)
       return true if equal?(other)
       return false unless other.is_a? Player
@@ -122,7 +202,7 @@ module ICU
       true
     end
     
-    # Strict equality test.
+    # Strict equality test. Passes if the playes are loosly equal and also if their ID, rating and title are not different.
     def eql?(other)
       return true if equal?(other)
       return false unless self == other
@@ -133,10 +213,10 @@ module ICU
     end
     
     # Merge in some of the details of another player.
-    def subsume(other)
-      raise "cannot merge two players that are not strictly equal" unless eql?(other)
+    def merge(other)
+      raise "cannot merge two players that are not equal" unless self == other
       [:id, :rating, :title, :fed].each do |m|
-        self.send("#{m}=", other.send(m)) if other.send(m)
+        self.send("#{m}=", other.send(m)) unless self.send(m)
       end
     end
   end

data/lib/result.rb

@@ -19,16 +19,16 @@ a bye or walkover since there is no opponent. Without an opponent, it is unratea
 
   result.rateable     # => false
 
-We can fill in opponent details as follows:
+The player's colour and the number of their opponent can be set as follows:
 
-  result.opponent = 13
   result.colour = 'B'
+  result.opponent = 13
 
 Specifying an opponent always makes a result rateable.
 
   result.rateable     # => true
 
-This result now represents a win by player 10 with the black pieces over player number 13 in round 2.
+This example now represents a win by player 10 with the black pieces over player number 13 in round 2.
 Alternatively, all this can been specified in the constructor.
 
   result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B')
@@ -41,7 +41,7 @@ or include it in the constructor:
 
   result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B', :rateable => false)
 
-The result of the same game from the perspective of an opponent is:
+The result of the same game from the perspective of the opponent is:
 
   tluser = result.reverse
 

data/lib/tournament_fcsv.rb

@@ -175,7 +175,7 @@ However, none of the opponents' results are rateable. For example:
         if old_player
           raise "two players with the same name (#{@player.name}) have conflicting details" unless old_player.eql?(@player)
           raise "same player (#{@player.name}) has more than one set of results" if old_player.id
-          old_player.subsume(@player)
+          old_player.merge(@player)
           @player = old_player
         else
           @tournament.add_player(@player)
@@ -200,7 +200,7 @@ However, none of the opponents' results are rateable. For example:
             raise "two players with the same name (#{opponent.name}) have conflicting details" unless old_player.eql?(opponent)
             result.opponent = old_player.num
             if old_player.id
-              old_player.subsume(opponent)
+              old_player.merge(opponent)
               old_result = @player.find_result(@round)
               raise "missing result for player (#{@player.name}) in round #{@round}" unless old_result
               raise "mismatched results for player (#{old_player.name}) in round #{@round}" unless result == old_result

data/spec/player_spec.rb

@@ -191,7 +191,7 @@ module ICU
       end
     end
     
-    context "subsumption" do
+    context "merge" do
       before(:each) do
         @p1 = Player.new('Mark', 'Orr', 1, :id => 1350)
         @p2 = Player.new('Mark', 'Orr', 2, :rating => 2100, :title => 'IM', :fed => 'IRL')
@@ -199,7 +199,7 @@ module ICU
       end
       
       it "takes on the ID, rating, title and fed of the other player but not the player number" do
-        @p1.subsume(@p2)
+        @p1.merge(@p2)
         @p1.num.should == 1
         @p1.id.should == 1350
         @p1.rating.should == 2100
@@ -210,11 +210,11 @@ module ICU
       it "should have a kind of symmetry" do
         p1 = @p1.dup
         p2 = @p2.dup
-        p1.subsume(p2).eql?(@p2.subsume(@p1))
+        p1.merge(p2).eql?(@p2.merge(@p1))
       end
       
       it "cannot be done with unequal objects" do
-        lambda { @p1.subsume(@p3) }.should raise_error(/cannot merge.*not strictly equal/)
+        lambda { @p1.merge(@p3) }.should raise_error(/cannot merge.*not equal/)
       end
     end
     

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sanichi-chess_icu
 version: !ruby/object:Gem::Version 
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors: 
 - Mark Orr
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-18 00:00:00 -07:00
+date: 2009-04-19 00:00:00 -07:00
 default_executable: 
 dependencies: []