icu_tournament 1.4.3 → 1.5.0

data/lib/icu_tournament/player.rb

@@ -181,11 +181,19 @@ module ICU
       end
     end
 
-    # Lookup a result by round number.
+    # Lookup a result by round number and return it (or nil if there is no such result).
     def find_result(round)
       @results.find { |r| r.round == round }
     end
 
+    # Lookup a result by round number, remove it and return it (or return nil if there is no such result).
+    def remove_result(round)
+      result = find_result(round)
+      return unless result
+      @results.delete(result)
+      result
+    end
+
     # Return the player's total points.
     def points
       @results.inject(0.0) { |t, r| t += r.points }

data/lib/icu_tournament/result.rb

@@ -66,6 +66,19 @@ module ICU
   #
   # The _points_ read-only accessor always returns a floating point number: either 0.0, 0.5 or 1.0.
   #
+  # Two results are <em>eql?</em> if all there attributes are the same, unless exceptions are specified.
+  #
+  #   r  = ICU::Result.new(1, 1, 'W', :opponent => 2)
+  #   r1 = ICU::Result.new(1, 1, 'W', :opponent => 2)
+  #   r2 = ICU::Result.new(1, 1, 'W', :opponent => 2, :rateable => false)
+  #   r3 = ICU::Result.new(1, 1, 'L', :opponent => 2, :rateable => false)
+  #
+  #   r.eql?(r1)                                   # => true
+  #   r.eql?(r2)                                   # => false
+  #   r.eql?(r3)                                   # => false
+  #   r.eql?(r2, :except => :rateable)             # => true
+  #   r.eql?(r3, :except => [:rateable, :score])   # => true
+  #
   class Result
     extend ICU::Accessor
     attr_positive :round
@@ -167,20 +180,22 @@ module ICU
       "R#{@round}P#{@player}O#{@opponent || '-'}#{@score}#{@colour || '-'}#{@rateable ? 'R' : 'U'}"
     end
 
-    # Loose equality. True if the round, player and opponent numbers, colour and score all match.
-    def ==(other)
+    # Equality. True if all attributes equal, exceptions allowed.
+    def eql?(other, opt={})
+      return true if equal?(other)
       return unless other.is_a? Result
-      [:round, :player, :opponent, :colour, :score].each do |m|
-        return false unless self.send(m) == other.send(m)
+      except = Hash.new
+      if opt[:except]
+        if opt[:except].is_a?(Array)
+          opt[:except].each { |x| except[x.to_sym] = true }
+        else
+          except[opt[:except].to_sym] = true
+        end
+      end
+      [:round, :player, :opponent, :colour, :score, :rateable].each do |m|
+        return false unless except[m] || self.send(m) == other.send(m)
       end
       true
     end
-
-    # Strict equality. True if the there's loose equality and also the rateablity is the same.
-    def eql?(other)
-      return true if equal?(other)
-      return false unless self == other
-      self.rateable == other.rateable
-    end
   end
 end

data/lib/icu_tournament/tournament.rb

@@ -55,6 +55,22 @@ module ICU
   #   t.add_result(ICU::Result.new(3, 20, 'L', :opponent => 10, :colour => 'W'))
   #   t.add_result(ICU::Result.new(3, 10, 'D', :opponent => 20, :colour => 'B'))  # would raise an exception
   #
+  # == Asymmetric Scores
+  #
+  # There is one exception to the rule that two corresponding results must be consistent:
+  # if both results are unrateable then the two scores need not sum to 1. The commonest case
+  # this caters for is probably that of a double default. To create such asymmetric results
+  # you must add the result from both players' perspectives. For example:
+  #
+  #   t.add_result(ICU::Result.new(3, 20, 'L', :opponent => 10, :rateable => false))
+  #   t.add_result(ICU::Result.new(3, 10, 'L', :opponent => 20, :rateable => false))
+  #
+  # After the first _add_result_ the two results are, as usual, consistent (in particular, the loss for player 20
+  # is balanced by a win for player 10). However, the second _add_result_, which asserts player 10 lost, does not cause
+  # an exception. It would have done if the results had been rateable but, because they are not, the scores are
+  # allowed to add up to something other than 1.0 (in this case, zero) and the effect of the second call to _add_result_
+  # is merely to adjust the score of player 10 from a win to a loss (while maintaining the loss for player 20).
+  #
   # See ICU::Player and ICU::Result for more details about players and results.
   #
   # == Validation
@@ -67,11 +83,11 @@ module ICU
   # Validations checks that:
   #
   # * there are at least two players
-  # * every player has a least one result
-  # * the result round numbers are consistent (no more than one game per player per round)
+  # * result round numbers are consistent (no more than one game per player per round)
+  # * corresponding results are consistent (although they may have asymmetric scores if unrateable, as previously desribed)
   # * the tournament dates (start, finish, round dates), if there are any, are consistent
-  # * the player ranks are consistent with their scores
-  # * there are no players with duplicate ICU IDs or duplicate FIDE IDs
+  # * player ranks are consistent with their scores
+  # * there are no players with duplicate \ICU IDs or duplicate \FIDE IDs
   #
   # Side effects of calling <em>validate!</em> or _invalid_ include:
   #
@@ -87,7 +103,7 @@ module ICU
   #
   #   t.validate!(:type => 'ForeignCSV')
   #
-  # which, amongst other tests, checks that there is at least one player with an ICU number and
+  # which, amongst other tests, checks that there is at least one player with an \ICU number and
   # that all such players have a least one game against a FIDE rated opponent. This is an example
   # of a specialized check that is only appropriate for a particular serializer. If it raises an
   # exception then the tournament cannot be serialized that way.
@@ -278,6 +294,7 @@ module ICU
       raise "invalid result" unless result.class == ICU::Result
       raise "result round number (#{result.round}) inconsistent with number of tournament rounds" if @rounds && result.round > @rounds
       raise "player number (#{result.player}) does not exist" unless @player[result.player]
+      return if add_asymmetric_result?(result)
       @player[result.player].add_result(result)
       if result.opponent
         raise "opponent number (#{result.opponent}) does not exist" unless @player[result.opponent]
@@ -418,14 +435,15 @@ module ICU
           raise "duplicate FIDE IDs, players #{p.num} and #{fide_ids[p.fide_id]}" if fide_ids[p.fide_id]
           fide_ids[p.fide_id] = num
         end
-        raise "player #{num} has no results" if p.results.size == 0
+        return if p.results.size == 0
         p.results.each do |r|
           next unless r.opponent
           opponent = @player[r.opponent]
           raise "opponent #{r.opponent} of player #{num} is not in the tournament" unless opponent
           o = opponent.find_result(r.round)
           raise "opponent #{r.opponent} of player #{num} has no result in round #{r.round}" unless o
-          raise "opponent's result (#{o.inspect}) is not reverse of player's (#{r.inspect})" unless o.reverse.eql?(r)
+          score = r.rateable || o.rateable ? [] : [:score]
+          raise "opponent's result (#{o.inspect}) is not reverse of player's (#{r.inspect})" unless o.reverse.eql?(r, :except => score)
         end
       end
     end
@@ -587,5 +605,29 @@ module ICU
         else player.name
       end
     end
+
+    # Detect when an asymmetric result is about to be added, make the appropriate adjustment and return true.
+    # The conditions for an asymric result are: the player's result already exists, the opponent's result
+    # already exists, both results are unrateable and the reverse of one result is equal to the other, apart
+    # from score. In this case all we do update score of the player's result, thus allowing two results whose
+    # total score does not add to 1.
+    def add_asymmetric_result?(result)
+      return false if result.rateable
+
+      plr = @player[result.player]
+      opp = @player[result.opponent]
+      return false unless plr && opp
+
+      plr_result = plr.find_result(result.round)
+      opp_result = opp.find_result(result.round)
+      return false unless plr_result && opp_result
+      return false if plr_result.rateable || opp_result.rateable
+      
+      reversed = plr_result.reverse
+      return false unless reversed && reversed.eql?(opp_result, :except => :score)
+
+      plr_result.score = result.score
+      true
+    end
   end
 end

data/lib/icu_tournament/version.rb

@@ -2,6 +2,6 @@
 
 module ICU
   class Tournament
-    VERSION = "1.4.3"
+    VERSION = "1.5.0"
   end
 end

data/spec/player_spec.rb

@@ -247,6 +247,22 @@ module ICU
       end
     end
 
+    context "removing a result" do
+      before(:all) do
+        @p = Player.new('Mark', 'Orr', 1)
+        @p.add_result(Result.new(1, 1, 'W', :opponent => 37, :score => 'W', :colour => 'W'))
+        @p.add_result(Result.new(2, 1, 'W', :opponent => 13, :score => 'W', :colour => 'B'))
+        @p.add_result(Result.new(3, 1, 'W', :opponent => 7,  :score => 'D', :colour => 'W'))
+      end
+
+      it "should find and remove a result by round number" do
+        result = @p.remove_result(1)
+        result.inspect.should == "R1P1O37WWR"
+        @p.results.size.should == 2
+        @p.results.map(&:round).join("|").should == "2|3"
+      end
+    end
+
     context "merge" do
       before(:each) do
         @p1 = Player.new('Mark', 'Orr', 1, :id => 1350)

data/spec/result_spec.rb

@@ -8,7 +8,7 @@ module ICU
         lambda { Result.new(3, 5, 'W', :opponent => 11, :colour => 'W') }.should_not raise_error
       end
     end
-    
+
     context "round number" do
       it "should be a positive integer" do
         lambda { Result.new(-2, 2, 0) }.should raise_error(/invalid positive integer/)
@@ -17,7 +17,7 @@ module ICU
         Result.new(' 3 ', 2, 0).round.should == 3
       end
     end
-    
+
     context "player number" do
       it "should be an integer" do
         lambda { Result.new(1, '  ', 0) }.should raise_error(/invalid integer/)
@@ -27,7 +27,7 @@ module ICU
         Result.new(1, " 9 ", 0).player.should == 9
       end
     end
-    
+
     context "score" do
       [1, 1.0, 'W', 'w', '+'].each do |score|
         it "should be 'W' for #{score}, #{score.class}" do
@@ -55,7 +55,7 @@ module ICU
         Result.new(1, 2, 'D').points.should == 0.5
       end
     end
-    
+
     context "colour" do
       it "should be 'W' or 'B' or nil (unknown)" do
         Result.new(4, 1, 0).colour.should be_nil
@@ -66,7 +66,7 @@ module ICU
         lambda { Result.new(4, 1, 0, :colour => 'red') }.should raise_error(/invalid colour/)
       end
     end
-    
+
     context "opponent number" do
       it "should be nil (the default) or an integer" do
         Result.new(4, 1, 0).opponent.should be_nil
@@ -78,27 +78,27 @@ module ICU
         Result.new(4, 1, 0, :opponent => ' 10 ').opponent.should == 10
         lambda { Result.new(4, 1, 0, :opponent => 'X') }.should raise_error(/invalid opponent number/)
       end
-      
+
       it "should be different to player number" do
         lambda { Result.new(4, 1, 0, :opponent => 1) }.should raise_error(/opponent .* player .* different/)
       end
     end
-    
+
     context "rateable flag" do
       it "should default to false if there is no opponent" do
         Result.new(4, 1, 0).rateable.should be_false
       end
-      
+
       it "should default to true if there is an opponent" do
         Result.new(4, 1, 0, :opponent => 10).rateable.should be_true
       end
-      
+
       it "should change if an opponent is added" do
         r = Result.new(4, 1, 0)
         r.opponent = 5;
         r.rateable.should be_true
       end
-      
+
       it "should be settable to false from the constructor" do
         Result.new(4, 1, 0, :opponent => 10, :rateable => false).rateable.should be_false
       end
@@ -108,43 +108,43 @@ module ICU
         r.rateable= false
         r.rateable.should be_false
       end
-      
+
       it "should not be settable to true if there is no opponent" do
         r = Result.new(4, 1, 0)
         r.rateable= true
         r.rateable.should be_false
       end
     end
-    
+
     context "reversed result" do
       it "should be nil if there is no opponent" do
         Result.new(4, 1, 0).reverse.should be_nil
       end
-      
+
       it "should have player and opponent swapped" do
         r = Result.new(4, 1, 0, :opponent => 2).reverse
         r.player.should == 2
         r.opponent.should == 1
       end
-      
+
       it "should have reversed result" do
         Result.new(4, 1, 0, :opponent => 2).reverse.score.should == 'W'
         Result.new(4, 1, 1, :opponent => 2).reverse.score.should == 'L'
         Result.new(4, 1, '=', :opponent => 2).reverse.score.should == 'D'
       end
-      
+
       it "should preserve rateability" do
         Result.new(4, 1, 0, :opponent => 2).reverse.rateable.should be_true
         Result.new(4, 1, 0, :opponent => 2, :rateable => false).reverse.rateable.should be_false
       end
     end
-    
+
     context "renumber the player numbers in a result" do
       before(:each) do
         @r1 = Result.new(1, 4, 0)
         @r2 = Result.new(2, 3, 1, :opponent => 4, :color => 'B')
       end
-      
+
       it "should renumber successfully if the map has the relevant player numbers" do
         map = { 4 => 1, 3 => 2 }
         @r1.renumber(map).player.should == 1
@@ -152,50 +152,53 @@ module ICU
         @r1.opponent.should be_nil
         @r2.opponent.should == 1
       end
-      
+
       it "should raise exception if a player number is not in the map" do
         lambda { @r1.renumber({ 5 => 1, 3 => 2 }) }.should raise_error(/player.*4.*not found/)
       end
     end
-    
-    context "loose equality" do
+
+    context "equality" do
       before(:each) do
+        @r  = Result.new(1, 1, 0, :opponent => 2, :colour => 'W')
         @r1 = Result.new(1, 1, 0, :opponent => 2, :colour => 'W')
-        @r2 = Result.new(1, 1, 0, :opponent => 2, :colour => 'W')
+        @r2 = Result.new(1, 1, 0, :opponent => 2, :colour => 'W', :rateable => false)
         @r3 = Result.new(2, 1, 0, :opponent => 2, :colour => 'W')
-        @r4 = Result.new(1, 3, 0, :opponent => 2, :colour => 'W')
-        @r5 = Result.new(1, 1, 1, :opponent => 2, :colour => 'W')
-        @r6 = Result.new(1, 1, 0, :opponent => 3, :colour => 'W')
-        @r7 = Result.new(1, 1, 0, :opponent => 2, :colour => 'B')
-      end
-      
-      it "should be equal if the round, player numbers, result and colour all match" do
-        (@r1 == @r1).should be_true
-        (@r1 == @r2).should be_true
-      end
-      
-      it "should not be equal if the round, player numbers, result or colour do not match" do
-        (@r1 == @r3).should be_false
-        (@r1 == @r4).should be_false
-        (@r1 == @r5).should be_false
-        (@r1 == @r6).should be_false
-        (@r1 == @r7).should be_false
+        @r4 = Result.new(1, 1, 0, :opponent => 2, :colour => 'B')
+        @r5 = Result.new(2, 1, 1, :opponent => 3, :colour => 'B')
+      end
+
+      it "should only be equal if everything is the same" do
+        @r.eql?(@r).should be_true
+        @r.eql?(@r1).should be_true
+        @r.eql?(@r2).should be_false
+        @r.eql?(@r3).should be_false
+        @r.eql?(@r4).should be_false
+        @r.eql?(@r5).should be_false
+      end
+
+      it "exceptions are allowed" do
+        @r.eql?(@r2, :except => :rateable).should be_true
+        @r.eql?(@r3, :except => "round").should be_true
+        @r.eql?(@r4, :except => :colour).should be_true
+        @r.eql?(@r5, :except => [:colour, :round, :score, "opponent"]).should be_true
       end
     end
-    
-    context "strict equality" do
+
+    context "equality documentation example" do
       before(:each) do
-        @r1 = Result.new(1, 1, 0, :opponent => 2, :colour => 'W')
-        @r2 = Result.new(1, 1, 0, :opponent => 2, :colour => 'W')
-        @r3 = Result.new(1, 1, 0, :opponent => 2, :colour => 'W', :rateable => false)
-        @r4 = Result.new(2, 1, 0, :opponent => 2, :colour => 'W')
+        @r  = ICU::Result.new(1, 1, 'W', :opponent => 2)
+        @r1 = ICU::Result.new(1, 1, 'W', :opponent => 2)
+        @r2 = ICU::Result.new(1, 1, 'W', :opponent => 2, :rateable => false)
+        @r3 = ICU::Result.new(1, 1, 'L', :opponent => 2, :rateable => false)
       end
-      
-      it "should only be equal if everything is the same" do
-        @r1.eql?(@r1).should be_true
-        @r1.eql?(@r2).should be_true
-        @r1.eql?(@r3).should be_false
-        @r1.eql?(@r4).should be_false
+
+      it "should be correct" do
+        @r.eql?(@r1).should be_true
+        @r.eql?(@r2).should be_false
+        @r.eql?(@r3).should be_false
+        @r.eql?(@r2, :except => :rateable).should be_true
+        @r.eql?(@r3, :except => [:rateable, :score]).should be_true
       end
     end
   end

data/spec/tournament_spec.rb

@@ -32,8 +32,9 @@ module ICU
 042 2009-11-09
 001   10      Fischer,Bobby                                                      1.5    1    30 w =              20 b 1
 001   20      Kasparov,Garry                                                     1.0    2              30 b 1    10 w 0
-001   30      Orr,Mark                                                           0.5    3    10 b =    20 w 0          
+001   30      Orr,Mark                                                           0.5    3    10 b =    20 w 0          #
 EOS
+        @s.sub!(/#/, '')
       end
 
       it "should serialize to Krause" do
@@ -324,7 +325,7 @@ EOS
       it "can be added one at a time" do
         @t.add_result(Result.new(1, 1, 'W', :opponent => 2))
         @t.add_result(Result.new(2, 2, 'D', :opponent => 3))
-        @t.add_result(Result.new(3, 3, 'L', :opponent => 1))
+        @t.add_result(Result.new(3, 3, 'L', :opponent => 1, :rateable => false))
         @mark.results.size.should == 2
         @mark.points.should == 2.0
         @gary.results.size.should == 2
@@ -333,10 +334,11 @@ EOS
         @boby.points.should == 0.5
       end
 
-      it "asymmetric results cannot be added" do
+      it "results with asymmetric scores cannot be added unless both results are unrateable" do
         @t.add_result(Result.new(1, 1, 'W', :opponent => 2))
         lambda { @t.add_result(Result.new(1, 2, 'D', :opponent => 1)) }.should raise_error(/result.*match/)
         lambda { @t.add_result(Result.new(1, 2, 'L', :opponent => 1, :rateable => false)) }.should raise_error(/result.*match/)
+        lambda { @t.add_result(Result.new(3, 3, 'L', :opponent => 1, :rateable => false)) }.should_not raise_error
       end
 
       it "should have a defined player" do
@@ -350,6 +352,13 @@ EOS
       it "should be consistent with the tournament's number of rounds" do
         lambda { @t.add_result(Result.new(4, 1, 'W', :opponent => 2)) }.should raise_error(/round/)
       end
+
+      it "documentation example should ne correct" do
+        @t.add_result(ICU::Result.new(3, 2, 'L', :opponent => 1, :rateable => false))
+        @t.add_result(ICU::Result.new(3, 1, 'L', :opponent => 2, :rateable => false))
+        @t.player(1).results.first.points.should == 0.0
+        @t.player(2).results.first.points.should == 0.0
+      end
     end
 
     context "finding players" do
@@ -495,6 +504,26 @@ EOS
         @t.player(2).id = 1350
         @t.invalid.should match(/duplicate.*ICU/)
       end
+
+      it "should allow players to have no results" do
+        (1..3).each { |r| @t.player(1).remove_result(r) }
+        @t.invalid.should be_false
+      end
+
+      it "should not allow asymmetric scores for rateable results" do
+        @t.player(1).find_result(1).score = 'L'
+        @t.invalid.should match(/result.*reverse/)
+      end
+
+      it "should allow asymmetric scores for unrateable results" do
+        @t.player(1).find_result(1).score = 'L'
+        (1..2).each do |p|
+          r = @t.player(p).find_result(1)
+          r.rateable = false
+          r.score = 'L'
+        end
+        @t.invalid.should be_false
+      end
     end
 
     context "renumbering" do

metadata

@@ -2,7 +2,7 @@
 name: icu_tournament
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 1.4.3
+  version: 1.5.0
 platform: ruby
 authors: 
 - Mark Orr
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-29 00:00:00 Z
+date: 2011-07-01 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: dbf
@@ -172,7 +172,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 1676868114987793590
+      hash: 3338096865289385673
       segments: 
       - 0
       version: "0"
@@ -181,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 1676868114987793590
+      hash: 3338096865289385673
       segments: 
       - 0
       version: "0"