sanichi-chess_icu 0.2.4 → 0.2.5

data/.gitignore

@@ -1,4 +1,4 @@
 coverage
-doc
+rdoc
 pkg
 tmp

data/Rakefile

@@ -6,13 +6,14 @@ require 'spec/rake/spectask'
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
-    gem.name = "chess_icu"
-    gem.summary = "For parsing files of chess tournament data into ruby classes."
-    gem.homepage = "http://github.com/sanichi/chess_icu"
-    gem.authors = ["Mark Orr"]
-    gem.email = "mark.j.l.orr@googlemail.com"
-    gem.files = FileList['[A-Z]*', '{lib,spec}/**/*', '.gitignore']
-    gem.has_rdoc = true
+    gem.name         = "chess_icu"
+    gem.summary      = "For parsing files of chess tournament data into ruby classes."
+    gem.homepage     = "http://github.com/sanichi/chess_icu"
+    gem.authors      = ["Mark Orr"]
+    gem.email        = "mark.j.l.orr@googlemail.com"
+    gem.files        = FileList['[A-Z]*', '{lib,spec}/**/*', '.gitignore']
+    gem.has_rdoc     = true
+    gem.rdoc_options = "--charset=UTF-8"
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
@@ -32,7 +33,7 @@ Spec::Rake::SpecTask.new(:fcsv) do |spec|
   spec.spec_opts = ['--colour --format nested']
 end
 
-Rake::RDocTask.new(:doc) do |doc|
+Rake::RDocTask.new(:rdoc) do |rdoc|
   if File.exist?('VERSION.yml')
     config = YAML.load(File.read('VERSION.yml'))
     version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
@@ -40,8 +41,8 @@ Rake::RDocTask.new(:doc) do |doc|
     version = ""
   end
 
-  doc.rdoc_dir = 'doc'
-  doc.title = "ChessIcu #{version}"
-  doc.rdoc_files.include('README*')
-  doc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ChessIcu #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION.yml

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

data/lib/chess_icu.rb

@@ -1,3 +1,4 @@
+# :enddoc:
 dir = File.dirname(__FILE__)
 %w{util name player result tournament}.each { |file| require "#{dir}/#{file}" }
 %w{fcsv}.each                               { |file| require "#{dir}/tournament_#{file}" }

data/lib/name.rb

@@ -1,4 +1,58 @@
 module ICU
+
+=begin rdoc
+
+== Names
+
+This class exists for two main reasons:
+
+* to normalise to a common format the different ways names are typed in practice
+* to be able to match two names even if they are not exactly the same
+
+To create a name object, supply both the first and second names separately to the constructor.
+
+  robert = ICU::Name.new(' robert  j ', ' FISHER ')
+
+Capitalisation, white space and punctuation will all be automatically corrected:
+
+  robert.name                                    # => 'Robert J. Fischer'
+  robert.rname                                   # => 'Fischer, Robert J.'  (reversed name)
+
+To avoid ambiguity when either the first or second names consist of multiple words, it is better to
+supply the two separately, if known. However, the full name can be supplied alone to the constructor
+and a guess will be made as to the first and last names.
+
+  bobby = ICU::Name.new(' bobby fischer ')
+  
+  bobby.first                                    # => 'Bobby'
+  bobby.last                                     # => 'Fischer'
+
+Names will match even if one is missing middle initials or if a nickname is used for one of the first names.
+
+  bobby.match(robert)                            # =>  true
+
+Note that the class is aware of only common nicknames (e.g. _Bobby_ and _Robert_, _Bill_ and _William_, etc), not all possibilities.
+
+Supplying the _match_ method with strings is equivalent to instantiating a Name instance with the same
+strings and then matching it. So, for example the following are equivalent:
+
+  robert.match('R. J.', 'Fischer')               # => true
+  robert.match(ICU::Name('R. J.', 'Fischer'))    # => true
+
+In those examples, the inital _R_ matches the first letter of _Robert_. However, nickname matches will not
+always work with initials. In the next example, the initial _R_ does not match the first letter _B_ of the
+nickname _Bobby_.
+
+  bobby.match('R. J.', 'Fischer')                # => false
+
+Some of the ways last names are canonicalised are illustrated below:
+
+  ICU::Name.new('John', 'O Reilly').last         # => "O'Reilly"
+  ICU::Name.new('dave', 'mcmanus').last          # => "McManus"
+  ICU::Name.new('pete', 'MACMANUS').last         # => "MacManus"
+  
+=end
+
   class Name
     attr_reader :first, :last
     
@@ -206,6 +260,7 @@ Patrick Pat Paddy
 Peter Pete
 Philippe Philip Phillippe Phillip
 Rick Ricky
+Robert Bob Bobby
 Samual Sam Samuel
 Stefanie Stef
 Stephen Steven Steve

data/lib/result.rb

@@ -1,5 +1,82 @@
 module ICU
+
+=begin rdoc
+
+== Result
+
+A result is the outcome of a game from the perspective of one of the players.
+If the game was not a bye or a walkover and involved a second player, then
+that second player will also have a result for the same game, and the two
+results will be mirror images of each other.
+
+A result always involves a round number, a player number and a score, so these
+three attributes must be supplied in the constructor.
+
+  result = ICU::Result.new(2, 10, 'W')
+
+The above example represents player 10 winning in round 2. As it stands, it represends
+a bye or walkover since there is no opponent. Without an opponent it is unrateable.
+
+  result.rateable     # => false
+
+We can fill in opponent details as follows:
+
+  result.opponent = 13
+  result.colour = 'B'
+
+Specifying an opponent via a setter always makes a result rateable.
+
+  result.rateable     # => true
+
+This result now represents a win with the black pieces over player number 13 in round 2.
+Alternatively, all this could have been specified in the constructor.
+
+  result = ICU::Result.new(2, 10, 'W', :opponent => 13, :colour => 'B')
+
+To make a game unratable, even it involves an opponent, set the _rateable_ atribute explicity:
+
+  result.rateable = false
+
+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:
+
+  tluser = result.reverse
+
+which, with the above example, would be:
+
+  tluser.player       # => 13
+  tluser.opponent     # => 10
+  tluser.score        # => 'L'
+  tluser.colour       # => 'B'
+  tluser.round        # => 2
+
+The reversed result will copy the _rateable_ attribute of the original unless an
+explicit override is supplied.
+
+  result.rateable                 # => true
+  result.reverse.rateable         # => true (copied from original)
+  result.reverse(false).rateable  # => false (overriden)
+
+A result which has no opponent is not reversible (the _reverse_ method returns _nil_).
+
+The return value from the _score_ method is always one of _W_, _L_ or _D_. However,
+when setting the score, a certain amount of variation is permitted as long as it is
+clear what is meant. For eample, the following would all be converted to _D_:
+
+  result.score = ' D '
+  result.score = 'd'
+  result.score = '='
+  result.score = '0.5'
+
+The _points_ read-only accessor always returns a floating point number, either 0.0, 0.5 or 1.0.
+
+=end
+
   class Result
+
     attr_reader :round, :player, :score, :colour, :opponent, :rateable
     
     # Constructor. Round number, player number and score must be supplied.
@@ -76,7 +153,7 @@ module ICU
         return
       end
       @rateable = case rateable
-        when nil   then true   # default (when absent) is true
+        when nil   then true   # default is true
         when false then false  # this is the only way to turn it off
         else true
       end

data/lib/util.rb

@@ -1,6 +1,17 @@
 module ICU
   class Util
-    # Parse dates into yyyy-mm-dd format, preferring European format. Return nil on error.
+
+=begin rdoc
+
+Parse dates into yyyy-mm-dd format, preferring European over US convention. Return nil on error.
+
+  Util.parsedate('1955-11-09')       # => '1955-11-09'
+  Util.parsedate('02/03/2009')       # => '2009-03-02'
+  Util.parsedate('02/23/2009')       # => '2009-02-23'
+  Util.parsedate('16th June 1986')   # => '1986-06-16'
+
+=end
+
     def self.parsedate(date)
       date = date.to_s
       return nil unless date.match(/[1-9]/)

data/spec/name_spec.rb

@@ -33,6 +33,34 @@ module ICU
       end
     end
     
+    context "rdoc expample" do
+      before(:each) do
+        @robert = Name.new(' robert  j ', ' FISCHER ')
+        @bobby = Name.new(' bobby fischer ')
+      end
+      
+      it "should get Robert" do
+        @robert.name.should == 'Robert J. Fischer'
+      end
+      
+      it "should get Bobby" do
+        @bobby.last.should == 'Fischer'
+        @bobby.first.should == 'Bobby'
+      end
+      
+      it "should match Robert and Bobby" do
+        @robert.match(@bobby).should be_true
+        @robert.match('R. J.', 'Fischer').should be_true
+        @bobby.match('R. J.', 'Fischer').should be_false
+      end
+      
+      it "should canconicalise last names" do
+        Name.new('John', 'O Reilly').last.should == "O'Reilly"
+        Name.new('dave', 'mcmanus').last.should == "McManus"
+        Name.new('pete', 'MACMANUS').last.should == "MacManus"
+      end
+    end
+    
     context "names that are already canonical" do
       it "should not be altered" do
         Name.new('Mark J. L.', 'Orr').name.should == 'Mark J. L. Orr'
@@ -81,10 +109,18 @@ module ICU
     end
     
     context "construction from a single string" do
+      before(:each) do
+        @mark1 = Name.new('ORR, mark j l')
+        @mark2 = Name.new('MARK J L ORR')
+        @oreil = Name.new("O'Reilly, j-k")
+      end
+      
       it "should be possible in simple cases" do
-        Name.new('ORR, mark j l').name.should == 'Mark J. L. Orr'
-        Name.new('MARK J L ORR').name.should == 'Mark J. L. Orr'
-        Name.new("O'Reilly, j-k").name.should == "J.-K. O'Reilly"
+        @mark1.first.should == 'Mark J. L.'
+        @mark1.last.should == 'Orr'
+        @mark2.first.should == 'Mark J. L.'
+        @mark2.last.should == 'Orr'
+        @oreil.name.should == "J.-K. O'Reilly"
       end
     end
     

data/spec/util_spec.rb

@@ -20,6 +20,10 @@ module ICU
         Util.parsedate('02/03/2009').should == '2009-03-02'
       end
       
+      it "should handle US style when there's no alternative" do
+        Util.parsedate('02/23/2009').should == '2009-02-23'
+      end
+
       it "should handle single digits" do
         Util.parsedate('9/8/2006').should == '2006-08-09'
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sanichi-chess_icu
 version: !ruby/object:Gem::Version 
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors: 
 - Mark Orr