sanichi-chess_icu 0.1.0 → 0.2.0

data/README.rdoc

@@ -1,11 +1,51 @@
-== ChessIcu
+= ChessIcu
 
 For parsing files of chess tournament data into ruby classes.
 
+
 == Install
 
   sudo gem install sanichi-chess_icu --source http://gems.github.com
-
+  
+  
 == Usage
 
-TODO
+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 taylored for the type of data
+in the file is first created (see below), and then it's parse or parse! method is called with the file's contents as argument.
+
+  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
+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:
+
+  tournament = parser.parse!(data)
+
+The file formats supported in the current version are:
+
+* Foreign CSV
+
+
+=== Foreign CSV
+
+This is a format specific to the ICU[http://icu.ie] ({specification}[http://www.icu.ie/articles/display.php?id=172])
+and is used by 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.
+
+
+== Author
+
+  Mark Orr, rating officer for the Irish Chess Union (ICU[http://icu.ie]).

data/Rakefile

@@ -26,7 +26,13 @@ Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.spec_opts = ['--colour --format nested --loadby mtime --reverse']
 end
 
-Rake::RDocTask.new do |doc|
+Spec::Rake::SpecTask.new(:fcsv) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/tournament_fcsv_spec.rb']
+  spec.spec_opts = ['--colour --format nested']
+end
+
+Rake::RDocTask.new(:doc) do |doc|
   if File.exist?('VERSION.yml')
     config = YAML.load(File.read('VERSION.yml'))
     version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
@@ -34,8 +40,8 @@ Rake::RDocTask.new do |doc|
     version = ""
   end
 
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title = "ChessIcu #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  doc.rdoc_dir = 'doc'
+  doc.title = "ChessIcu #{version}"
+  doc.rdoc_files.include('README*')
+  doc.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION.yml

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

data/lib/tournament_fcsv.rb

@@ -3,18 +3,23 @@ require 'fastercsv'
 module ICU
   class Tournament
     class ForeignCSV
-      attr_reader :tournament
-    
-      # Constructor.
-      def initialize(csv)
-        @state, @line, @round, @sum = 0, 0, nil, nil
-        parse(csv)
-      end
-      
-      private
+      attr_reader :error
       
+      # Parse CSV data returning a Tournament on success or a nil on failure (and a message retrievable via the error method).
       def parse(csv)
+        begin
+          parse!(csv)
+        rescue => ex
+          @error = ex.message
+          nil
+        end
+      end
+      
+      # Parse CSV data returning a Tournament on success or raising an exception on error.
+      def parse!(csv)
+        @state, @line, @round, @sum, @error = 0, 0, nil, nil, nil
         @tournament = Tournament.new('Dummy', '2000-01-01')
+        
         FasterCSV.parse(csv, :row_sep => :auto) do |r|
           @line += 1                            # increment line number
           next if r.size == 0                   # skip empty lines
@@ -51,7 +56,11 @@ module ICU
           raise "line #{@line}: premature termination - expected #{exp}"
         end
         raise "line #{@line}: no players found in file" if @tournament.players.size == 0
+        
+        @tournament
       end
+
+      private
       
       def event
         abort "the 'Event' keyword", 0 unless @r[0].match(/^(Event|Tournament)$/i)

data/spec/tournament_fcsv_spec.rb

@@ -31,8 +31,8 @@ Player,3364,Ui Laighleis,Gearoidin
 4,1,B,Powell,Linda,1850,,WLS
 Total,2
 CSV
-          @f = ForeignCSV.new(@csv)
-          @t = @f.tournament
+          @f = ForeignCSV.new
+          @t = @f.parse!(@csv)
         end
         
         it "should have a name" do
@@ -81,8 +81,8 @@ Player,1350,Orr,Mark
 2,1,B,Fischer,Bobby,2700,GM,USA
 Total,1.5
 CSV
-          @f = ForeignCSV.new(@csv)
-          @t = @f.tournament
+          @f = ForeignCSV.new
+          @t = @f.parse!(@csv)
         end
 
         it "should have the usual basic details" do
@@ -123,8 +123,8 @@ Player,1350,Orr,Mark
 2,=,W,Ui Laighleis,Gearoidin,1800,,IRL
 Total,1.0
 CSV
-          @f = ForeignCSV.new(@csv)
-          @t = @f.tournament
+          @f = ForeignCSV.new
+          @t = @f.parse!(@csv)
         end
 
         it "should have the usual basic details" do
@@ -162,8 +162,8 @@ Player ,3364 , ui Laighleis, gearoidin
 Total,1.0
 
 CSV
-          @f = ForeignCSV.new(@csv)
-          @t = @f.tournament
+          @f = ForeignCSV.new
+          @t = @f.parse!(@csv)
         end
 
         it "should have the correct basic details" do
@@ -184,9 +184,40 @@ CSV
         end
       end
       
+      context "#parse" do
+        before(:each) do
+          @f = ForeignCSV.new
+        end
+
+        it "should behave just like #parse! on success" do
+          csv = <<CSV
+Event,"Bratto Open, 2001"
+Start,7th March 2001
+Rounds,2
+Website,http://www.federscacchi.it/
+
+Player,3364,Ui Laighleis,Gearoidin
+1,=,W,Kasparov,Gary,2800,GM,RUS
+2,=,B,Orr,Mark,2100,IM,IRL
+Total,1.0
+CSV
+          @f.parse(csv).should be_an_instance_of(ICU::Tournament)
+          @f.error.should be_nil
+        end
+        
+        it "should not throw an exception but return nil on error" do
+          @f.parse(' ').should be_nil
+          @f.error.should match(/event/)
+        end
+      end
+
       context "invalid files" do
+        before(:each) do
+          @f = ForeignCSV.new
+        end
+        
         it "a blank file is invalid" do
-          lambda { ForeignCSV.new(' ') }.should raise_error(/event/i)
+          lambda { @f.parse!(' ') }.should raise_error(/event/i)
         end
         
         it "the event should come first" do
@@ -196,7 +227,7 @@ Event,"Bratto Open, 2001"
 Rounds,2
 Website,http://www.federscacchi.it/
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 1.*event/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 1.*event/i)
         end
         
         it "the start should come second" do
@@ -206,7 +237,7 @@ Rounds,2
 Start,7th March 2001
 Website,http://www.federscacchi.it/
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 2.*start/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 2.*start/i)
         end
         
         it "the number of rounds should come third" do
@@ -216,7 +247,7 @@ Start,7th March 2001
 Website,http://www.federscacchi.it/
 Rounds,2
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 3.*rounds/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 3.*rounds/i)
         end
         
         it "there should be a web site" do
@@ -226,7 +257,7 @@ Start,7th March 2001
 Rounds,2
 
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 4.*site/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 4.*site/i)
         end
         
         it "should have at least one player" do
@@ -236,7 +267,7 @@ Start,7th March 2001
 Rounds,2
 Website,http://www.federscacchi.it/
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 4.*no players/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 4.*no players/i)
         end
         
         it "the player needs to have a valid ID number" do
@@ -248,7 +279,7 @@ Website,http://www.federscacchi.it/
 
 Player,0,Ui Laighleis,Gearoidin
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 6.*number/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 6.*number/i)
         end
         
         it "should have the right number of results for each player" do
@@ -262,7 +293,7 @@ Player,3364,Ui Laighleis,Gearoidin
 1,=,W,Kasparov,Gary,2800,GM,RUS
 Total,0.5
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 8.*round/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 8.*round/i)
         end
         
         it "should have correct totals" do
@@ -277,7 +308,7 @@ Player,3364,Ui Laighleis,Gearoidin
 2,=,B,Orr,Mark,2100,IM,IRL
 Total,1.5
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 9.*total/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 9.*total/i)
         end
         
         
@@ -298,7 +329,7 @@ Player,1350,Orr,Mark
 2,=,B,Kasparov,Gary,2850,GM,RUS
 Total,1.0
 CSV
-          lambda { ForeignCSV.new(csv) }.should raise_error(/line 13.*same name.*conflicting/i)
+          lambda { @f.parse!(csv) }.should raise_error(/line 13.*same name.*conflicting/i)
         end
       end
     end

metadata

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