sanichi-chess_icu 0.2.1 → 0.2.4

data/README.rdoc

@@ -13,38 +13,30 @@ For parsing files of chess tournament data into ruby classes.
 A tournament (ICU::Tournament) has two or more players (ICU::Player), and each player has one or more results (ICU::Result).
 
 Tournament objects are created by parsing files of various formats. An instance of a class that can handle the format
-(see below for the available classes) is first created, and then it's parse or parse! method is called with the file's
-contents as argument.
+(see below for the available classes) is first created, and then it's <em>parse</em> or <em>parse!</em> method is called
+with the file's contents as the only argument.
 
+  require 'chess_icu'
   data = open('tournament.csv') { |f| f.read }
   tournament = parser.parse(data)
 
-On success, the parse method returns an object of type ICU::Tournament. On error, it returns nil and an error message
+On success, the parse method returns an object of type ICU::Tournament. On error, it returns _nil_ and an error message
 can be retrieved from the parser instance:
 
   parser.error  # => error message or nil on success
   
-Alternatively, if an exception is preferred on error, the parse! method can be used:
+Alternatively, if an exception is preferred on error, the <em>parse!</em> method can be used:
 
   tournament = parser.parse!(data)
 
 The file formats supported in the current version are:
 
-* Foreign CSV
+* Foreign CSV (ICU::Tournament::ForeignCSV) - for players to report their individual results in foreign tournaments
 
 
-=== Foreign CSV
-
-This is a format used by the ICU[http://icu.ie] ({specification}[http://www.icu.ie/articles/display.php?id=172])
-for players to submit their individual results in foreign tournaments for domestic rating.
-It's parsed by instances of ICU::Tournament::ForeignCSV.
-
-  parser = ICU::Tournament::ForeignCSV.new
-  
-
 == TODO
   
-Future versions of this software will be able to parse more common formats such as SwissPerfect and FIDE's Krause format.
+Future versions of this software will be able to parse other types of files such as SwissPerfect and FIDE's Krause format.
 
 
 == Author

data/VERSION.yml

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

data/lib/result.rb

@@ -2,6 +2,8 @@ module ICU
   class Result
     attr_reader :round, :player, :score, :colour, :opponent, :rateable
     
+    # Constructor. Round number, player number and score must be supplied.
+    # Optional hash attribute are _opponent_, _colour_ and _rateable_.
     def initialize(round, player, score, opt={})
       self.round  = round
       self.player = player
@@ -25,7 +27,7 @@ module ICU
       raise "invalid player number (#{player})" if @player == 0 && !player.to_s.match(/\d/)
     end
     
-    # Score for the game, even if a default. One of 'W', 'L' or 'D' (after some cleaning up).
+    # Score for the game, even if a default. One of 'W', 'L' or 'D'. Reasonable inputs like 1, 0, =, ½, etc will be converted.
     def score=(score)
       @score = case score.to_s.strip
         when /^(1\.0|1|\+|W|w)$/ then 'W'
@@ -35,7 +37,7 @@ module ICU
       end
     end
     
-    # The score as a number.
+    # Return the score as a floating point number.
     def points
       case @score
         when 'W' then 1.0
@@ -44,7 +46,7 @@ module ICU
       end
     end
     
-    # Colour. Either 'W' or 'B' after some cleaning up.
+    # Colour. Either 'W' (white) or 'B' (black).
     def colour=(colour)
       @colour = case colour.to_s
         when ''   then nil
@@ -54,7 +56,7 @@ module ICU
       end
     end
     
-    # Opponent player number. Either absent (nil) or any integer except the player number.
+    # Opponent player number. Either absent (_nil_) or any integer except the player number.
     def opponent=(opponent)
       @opponent = case opponent
         when nil     then nil
@@ -67,7 +69,7 @@ module ICU
       self.rateable = true if @opponent
     end
     
-    # Rateable flag. If false, game is not rateable. Can only be true if there is an opponent.
+    # Rateable flag. If false, result is not rateable. Can only be true if there is an opponent.
     def rateable=(rateable)
       if opponent.nil?
         @rateable = false
@@ -91,7 +93,7 @@ module ICU
       r
     end
     
-    # Loose equality.
+    # Loose equality. True if the round, player and opponent numbers, colour and score all match.
     def ==(other)
       return unless other.is_a? Result
       [:round, :player, :opponent, :colour, :score].each do |m|

data/lib/tournament.rb

@@ -1,8 +1,44 @@
 module ICU
+
+=begin rdoc
+
+== Generic Tournament
+
+Normally a tournament object is created by parsing a data file (e.g. with ICU::Tournament::ForeignCSV).
+However, it is also possible to build a tournament by first creating a bare tournament instance and then
+firstly adding all the players and then adding all the results.
+
+  require 'rubygems'
+  require 'chess_icu'
+
+  t = ICU::Tournament.new('Bangor Masters', '2009-11-09')
+
+  t.add_player(ICU::Player.new('Bobby', 'Fischer', 10))
+  t.add_player(ICU::Player.new('Garry', 'Kasparov', 20))
+  t.add_player(ICU::Player.new('Mark', 'Orr', 30))
+
+  t.add_result(ICU::Result.new(1, 10, 'D', :opponent => 30, :colour => 'W'))
+  t.add_result(ICU::Result.new(2, 20, 'W', :opponent => 30, :colour => 'B'))
+  t.add_result(ICU::Result.new(3, 20, 'L', :opponent => 10, :colour => 'W'))
+
+  [10, 20, 30].each { |n| puts "#{t.player(n).points} #{t.player(n).name}" }
+
+Would result in the following output.
+
+  1.5 Bobby Fischer
+  1.0 Gary Kasparov
+  0.5 Mark Orr
+
+Note that the players should be added first because the _add_result_ method will
+raise an exception if the players it references through their numbers (10, 20
+and 30 in this example) have not already been added to the tournament.
+
+=end
+
   class Tournament
     attr_reader :name, :start, :rounds, :site
     
-    # Constructor.
+    # Constructor. Name and start date must be supplied. Other attributes are optional.
     def initialize(name, start, opt={})
       self.name  = name
       self.start = start
@@ -10,20 +46,20 @@ module ICU
       @player = {}
     end
     
-    # Tournament name.
+    # Set the tournament name.
     def name=(name)
       raise "invalid tournament name (#{name})" unless name.to_s.match(/[a-z]/i)
       @name = name.to_s.strip
     end
     
-    # Start data in yyyy-mm-dd format.
+    # Set a start date in yyyy-mm-dd format.
     def start=(start)
       start = start.to_s.strip
       @start = Util.parsedate(start)
       raise "invalid start date (#{start})" unless @start
     end
     
-    # Number of rounds. Is either unknown (nil) or a positive integer.
+    # Set the number of rounds. Is either unknown (_nil_) or a positive integer.
     def rounds=(rounds)
       @rounds = case rounds
         when nil     then nil
@@ -34,7 +70,7 @@ module ICU
       raise "invalid number of rounds (#{rounds})" unless @rounds.nil? || @rounds > 0
     end
     
-    # Web site. Either unknown or a reasonably valid looking URL.
+    # Set the tournament web site. Should be either unknown (_nil_) or a reasonably valid looking URL.
     def site=(site)
       @site = site.to_s.strip
       @site = nil if @site == ''
@@ -42,7 +78,7 @@ module ICU
       raise "invalid site (#{site})" unless @site.nil? || @site.match(/^https?:\/\/[-\w]+(\.[-\w]+)+(\/[^\s]*)?$/i)
     end
     
-    # Add players.
+    # Add a new player to the tournament. Must have a unique player number.
     def add_player(player)
       raise "invalid player" unless player.class == ICU::Player
       raise "player number (#{player.num}) should be unique" if @player[player.num]
@@ -54,17 +90,22 @@ module ICU
       @player[num]
     end
     
-    # Return an array of all the players.
+    # Return an array of all players in order of their player numbers.
     def players
-      @player.values
+      @player.values.sort_by{ |p| p.num }
     end
     
-    # Lookup a player in the tournament.
+    # Lookup a player in the tournament by player number, returning _nil_ if the player number does not exist.
     def find_player(player)
       players.find { |p| p == player }
     end
     
-    # Add results.
+    # Add a result to a tournament. An exception is raised if the players referenced in the result (by number)
+    # do not exist in the tournament. The result, which remember is from the perspective of one of the players,
+    # is added to that player's results. Additionally, the reverse of the result is automatically added to the player's
+    # opponent, unless the opponent does not exist (e.g. byes, walkovers). By default, if the result is rateable
+    # then the opponent's result will also be rateable. To make the opponent's result unrateable, set the optional
+    # second parameter to false.
     def add_result(result, reverse_rateable=true)
       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

data/lib/tournament_fcsv.rb

@@ -2,10 +2,85 @@ require 'fastercsv'
 
 module ICU
   class Tournament
+    
+=begin rdoc
+
+== Foreign CSV
+
+This is a format ({specification}[http://www.icu.ie/articles/display.php?id=172]) used by the ICU[http://icu.ie]
+for players to submit their individual results in foreign tournaments for domestic rating.
+
+Suppose, for example, that the following data is the file <em>tournament.csv</em>:
+
+  Event,"Isle of Man Masters, 2007"
+  Start,2007-09-22
+  Rounds,9
+  Website,http://www.bcmchess.co.uk/monarch2007/
+
+  Player,456,Fox,Anthony
+  1,0,B,Taylor,Peter P.,2209,,ENG
+  2,=,W,Nadav,Egozi,2205,,ISR
+  3,=,B,Cafolla,Peter,2048,,IRL
+  4,1,W,Spanton,Tim R.,1982,,ENG
+  5,1,B,Grant,Alan,2223,,SCO
+  6,0,-
+  7,=,W,Walton,Alan J.,2223,,ENG
+  8,0,B,Bannink,Bernard,2271,FM,NED
+  9,=,W,Phillips,Roy,2271,,MAU
+  Total,4
+
+This file can be parsed as follows.
+
+  data = open('tournament.csv') { |f| f.read }
+  parser = ICU::Tournament::ForeignCSV.new
+  tournament = parser.parse(data)
+
+If the file is correctly specified, the return value from the <em>parse</em> method is an instance of
+ICU::Tournament (rather than <em>nil</em>, which indicates an error). In this example the file is valid, so:
+  
+  tournament.name                                    # => "Isle of Man Masters, 2007"
+  tournament.start                                   # => "2007-09-22"
+  tournament.rounds                                  # => 9
+  tournament.website                                 # => "http://www.bcmchess.co.uk/monarch2007/"
+
+The main player (the player whose results are being reported for rating) played 9 rounds
+but only 8 other players (he had a bye in round 6), so the total number of players is 9.
+
+  tournament.players.size                            # => 9
+  
+Each player has a unique number for the tournament. The main player always occurs first in this type of file, so his number is 1.
+
+  player = tournament.player(1)
+  player.name                                        # => "Fox, Anthony"
+
+This player has 4 points from 9 rounds but only 8 of his results are are rateable (because of the bye).
+
+  player.points                                      # => 4.0
+  player.results.size                                # => 9
+  player.results.find_all{ |r| r.rateable }.size     # => 8
+
+The other players all have numbers greater than 1.
+
+  opponents = tournamnet.players.reject { |o| o.num == 1 }
+
+There are 8 opponents of the main player, each with exactly one game.
+
+  opponents.size                                     # => 8
+  opponents.find_all{ |o| o.results.size == 1}.size  # => 8
+
+However, none of the opponents' results are rateable. For example:
+
+  opponent = tournament.players(2)
+  opponent.name                                      # => "Taylor, Peter P."
+  opponent.results[0].rateable                       # => false
+  
+=end
+
     class ForeignCSV
       attr_reader :error
       
-      # Parse CSV data returning a Tournament on success or a nil on failure (and a message retrievable via the error method).
+      # Parse CSV data returning a Tournament on success or a nil on failure.
+      # In the case of failure, an error message can be retrived via the <em>error</em> method.
       def parse(csv)
         begin
           parse!(csv)

data/spec/tournament_fcsv_spec.rb

@@ -62,6 +62,60 @@ CSV
           check_player(4, 'Linda',     'Powell',       1, 0, 0.0, :rating => 1850, :fed => 'WLS')
         end
       end
+      
+      context "the rdoc example tournament" do
+        before(:all) do
+          @csv = <<CSV
+Event,"Isle of Man Masters, 2007"
+Start,2007-09-22
+Rounds,9
+Website,http://www.bcmchess.co.uk/monarch2007/
+
+Player,456,Fox,Anthony
+1,0,B,Taylor,Peter P.,2209,,ENG
+2,=,W,Nadav,Egozi,2205,,ISR
+3,=,B,Cafolla,Peter,2048,,IRL
+4,1,W,Spanton,Tim R.,1982,,ENG
+5,1,B,Grant,Alan,2223,,SCO
+6,0,-
+7,=,W,Walton,Alan J.,2223,,ENG
+8,0,B,Bannink,Bernard,2271,FM,NED
+9,=,W,Phillips,Roy,2271,,MAU
+Total,4
+CSV
+          @f = ForeignCSV.new
+          @t = @f.parse!(@csv)
+          @p = @t.player(1)
+          @o = @t.players.reject { |o| o.num == 1 }
+          @r = @t.player(2)
+        end
+        
+        it "should have correct basic details" do
+          @t.name.should == 'Isle of Man Masters, 2007'
+          @t.start.should == '2007-09-22'
+          @t.rounds.should == 9
+          @t.site.should == 'http://www.bcmchess.co.uk/monarch2007/'
+        end
+        
+        it "should have the right number of players in the right order" do
+          @t.players.size.should == 9
+          @t.players.inject(''){ |a,o| a << o.num.to_s }.should == '123456789'
+        end
+        
+        it "should have the right details for the main player" do
+          @p.name.should == "Fox, Anthony"
+          @p.results.size == 9
+          @p.results.find_all{ |r| r.rateable }.size.should == 8
+          @p.points.should == 4.0
+        end
+        
+        it "should have the right details for the opponents" do
+          @o.size.should == 8
+          @o.find_all{ |o| o.results.size == 1}.size.should == 8
+          @r.name.should == "Taylor, Peter P."
+          @r.results[0].rateable.should be_false
+        end
+      end
     
       context "a tournament with more than one player" do
         before(:all) do

data/spec/tournament_spec.rb

@@ -7,7 +7,7 @@ module ICU
         lambda do
           t = Tournament.new('Bangor Bash', '2009-11-09')
           t.add_player(Player.new('Bobby', 'Fischer', 1))
-          t.add_player(Player.new('Garry', 'Gary Kasparov', 2))
+          t.add_player(Player.new('Garry', 'Kasparov', 2))
           t.add_player(Player.new('Mark', 'Orr', 3))
           t.add_result(Result.new(1, 1, '=', :opponent => 2, :colour => 'W'))
           t.add_result(Result.new(2, 2, 'L', :opponent => 3, :colour => 'W'))

metadata

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