icu_tournament 1.2.8 → 1.3.1

data/README.rdoc

@@ -2,7 +2,6 @@
 
 For reading or writing files of chess tournament data. Original project name on github was _chess_icu_.
 
-
 == Install
 
 For ruby 1.9.2 (version 1.1.2 was the last compatible with ruby 1.8.7).
@@ -27,6 +26,7 @@ The currently supported formats are:
 * ICU::Tournament::Krause - the format used by FIDE.
 * ICU::Tournament::ForeignCSV - used by Irish players to report their individual results in foreign tournaments.
 * ICU::Tournament::SwissPerfect - often used by Irish tournament controllers to report results.
+* ICU::Tournament::SPExport - the SwissPerfect text export format.
 
 == Writing Files
 

data/lib/icu_tournament.rb

@@ -5,6 +5,6 @@ require 'icu_name'
 icu_tournament_files = Array.new
 icu_tournament_files.concat %w{util federation}
 icu_tournament_files.concat %w{player result team tournament}
-icu_tournament_files.concat %w{fcsv krause sp}.map{ |f| "tournament_#{f}"}
+icu_tournament_files.concat %w{fcsv krause sp spx}.map{ |f| "tournament_#{f}"}
 
 icu_tournament_files.each { |file| require "icu_tournament/#{file}" }

data/lib/icu_tournament/federation.rb

@@ -81,6 +81,10 @@ module ICU
       matches[0]
     end
 
+    # Return an array of codes and names suitable for creating a federation menu in Rails.
+    #   ICU::Federation.menu(:order => 'code')     # order federations by code (instead of by name)
+    #   ICU::Federation.menu(:top => 'IRL')        # make this federation come first
+    #   ICU::Federation.menu(:none => 'None')      # add a dummy top entry with name "None" and blank code
     def self.menu(opts = {})
       compile
       top, menu = nil, []
@@ -91,6 +95,7 @@ module ICU
       menu
     end
     
+    # Return an array of sorted federation codes.
     def self.codes
       compile
       @@objects.map(&:code).sort
@@ -101,6 +106,7 @@ module ICU
       @name = name
     end
 
+    # :enddoc:
     private
 
     def self.compile

data/lib/icu_tournament/player.rb

@@ -12,9 +12,10 @@ module ICU
   #
   # In addition, players have a number of optional attributes which can be specified
   # via setters or in constructor hash options: _id_ (local or national ID), _fide_
-  # (FIDE ID), _fed_ (federation), _title_, _rating_, _rank_ and _dob_ (date of birth).
+  # (FIDE ID), _fed_ (federation), _title_, _rating_ (local rating), _fide_rating,
+  # _rank_ and _dob_ (date of birth).
   #
-  #   peter = ICU::Player.new('Peter', 'Svidler', 21, :fed => 'rus', :title => 'g', :rating = 2700)
+  #   peter = ICU::Player.new('Peter', 'Svidler', 21, :fed => 'rus', :title => 'g', :fide_rating = 2700)
   #   peter.dob = '17th June, 1976'
   #   peter.rank = 1
   #
@@ -80,11 +81,10 @@ module ICU
   #   fox1.fed                         # => 'IRL'
   #   fox1.gender                      # => 'M'
   #
-  #
   class Player
     extend ICU::Accessor
     attr_integer :num
-    attr_positive_or_nil :id, :fide, :rating, :rank
+    attr_positive_or_nil :id, :fide, :rating, :fide_rating, :rank
     attr_date_or_nil :dob
 
     attr_reader :results, :first_name, :last_name, :fed, :title, :gender
@@ -94,7 +94,7 @@ module ICU
       self.first_name = first_name
       self.last_name  = last_name
       self.num        = num
-      [:id, :fide, :fed, :title, :rating, :rank, :dob, :gender].each do |atr|
+      [:id, :fide, :fed, :title, :rating, :fide_rating, :rank, :dob, :gender].each do |atr|
         self.send("#{atr}=", opt[atr]) unless opt[atr].nil?
       end
       @results = []
@@ -192,7 +192,7 @@ module ICU
     def eql?(other)
       return true if equal?(other)
       return false unless self == other
-      [:id, :fide, :rating, :title, :gender].each do |m|
+      [:id, :fide, :rating, :fide_rating, :title, :gender].each do |m|
         return false if self.send(m) && other.send(m) && self.send(m) != other.send(m)
       end
       true
@@ -201,7 +201,7 @@ module ICU
     # Merge in some of the details of another player.
     def merge(other)
       raise "cannot merge two players that are not equal" unless self == other
-      [:id, :fide, :rating, :title, :fed, :gender].each do |m|
+      [:id, :fide, :rating, :fide_rating, :title, :fed, :gender].each do |m|
         self.send("#{m}=", other.send(m)) unless self.send(m)
       end
     end

data/lib/icu_tournament/tournament.rb

@@ -95,7 +95,7 @@ module ICU
   #   t.validate(:rerank => true)
   #
   # Ranking is inconsistent if some but not all players have a rank or if all players
-  # have a rank but some are ranked higher than others on lower scores.
+  # but at least one pair of players exist where one has a higher score but a lower rank.
   #
   # To rank the players requires a tie break method to be specified to order players on the same score.
   # The default is alphabetical (by last name then first name). Other methods can be specified by supplying
@@ -112,7 +112,7 @@ module ICU
   # * _modified_median_: same as Harkness except only lowest (or highest) score(s) are discarded for players with more (or less) than 50%
   # * _Neustadtl_ (or _Sonneborn-Berger_): sum of scores of players defeated plus half sum of scores of players drawn against
   # * _progressive_ (or _cumulative_): sum of running score for each round
-  # * _ratings_: sum of opponents ratings
+  # * _ratings_: sum of opponents ratings (FIDE ratings are used in preference to local ratings if available)
   # * _blacks_: number of blacks
   # * _wins_: number of wins
   # * _name_: alphabetical by name (if _tie_breaks_ is set to an empty array, as it is initially, then this will be used as the back-up tie breaker)
@@ -382,7 +382,7 @@ module ICU
     # Convenience method to parse a file.
     def self.parse_file!(file, format, opts={})
       type = format.to_s
-      raise "Invalid format" unless type.match(/^(SwissPerfect|Krause|ForeignCSV)$/);
+      raise "Invalid format" unless type.match(/^(SwissPerfect|SPExport|Krause|ForeignCSV)$/);
       parser = "ICU::Tournament::#{format}".constantize.new
       if type == 'ForeignCSV'
         # Doesn't take options.
@@ -398,15 +398,16 @@ module ICU
     # or if the tournament is unsuitable for serialisation in that format.
     def serialize(format, arg={})
       serializer = case format.to_s.downcase
-        when 'krause'       then ICU::Tournament::Krause.new
-        when 'foreigncsv'   then ICU::Tournament::ForeignCSV.new
-        when 'swissperfect' then ICU::Tournament::SwissPerfect.new
-        when ''             then raise "no format supplied"
+        when 'krause'     then ICU::Tournament::Krause.new
+        when 'foreigncsv' then ICU::Tournament::ForeignCSV.new
+        when 'spexport'   then ICU::Tournament::SPExport.new
+        when ''           then raise "no format supplied"
         else raise "unsupported serialisation format: '#{format}'"
       end
       serializer.serialize(self, arg)
     end
 
+    # :enddoc:
     private
 
     # Check players.
@@ -500,8 +501,8 @@ module ICU
     def check_type(type)
       if type.respond_to?(:validate!)
         type.validate!(self)
-      elsif type.to_s.match(/^(ForeignCSV|Krause|SwissPerfect)$/)
-        parser = "ICU::Tournament::#{type.to_s}".constantize.new.validate!(self)
+      elsif type.to_s.match(/^(ForeignCSV|Krause|SwissPerfect|SPExport)$/)
+        "ICU::Tournament::#{type.to_s}".constantize.new.validate!(self)
       else
         raise "invalid type supplied for validation check"
       end
@@ -563,7 +564,7 @@ module ICU
         when 'neustadtl'   then player.results.inject(0.0) { |t,r| t + (r.opponent ? hash['opp-score'][r.opponent] * r.points : 0.0) }
         when 'opp-score'   then player.results.inject(0.0) { |t,r| t + (r.opponent ? r.points : 0.5) } + (rounds - player.results.size) * 0.5
         when 'progressive' then (1..rounds).inject(0.0)    { |t,n| r = player.find_result(n); s = r ? r.points : 0.0; t + s * (rounds + 1 - n) }
-        when 'ratings'     then player.results.inject(0)   { |t,r| t + (r.opponent && @player[r.opponent].rating ? @player[r.opponent].rating : 0) }
+        when 'ratings'     then player.results.inject(0)   { |t,r| t + (r.opponent && (@player[r.opponent].fide_rating || @player[r.opponent].rating) ? (@player[r.opponent].fide_rating || @player[r.opponent].rating) : 0) }
         when 'harkness', 'modified'
           scores = player.results.map{ |r| r.opponent ? hash['opp-score'][r.opponent] : 0.0 }.sort
           1.upto(rounds - player.results.size) { scores << 0.0 }

data/lib/icu_tournament/tournament_fcsv.rb

@@ -97,19 +97,20 @@ module ICU
     #   ICU::Tournament::ForeignCSV.new.serialize(tournament)
     #
     # You can also build the tournament object from scratch using your own data and then serialize it.
-    # For example, here are the commands to reproduce the example above.
+    # For example, here are the commands to reproduce the example above. Note that in this format
+    # opponents' ratings are FIDE while players' IDs are ICU.
     #
     #   t = ICU::Tournament.new("Isle of Man Masters, 2007", '2007-09-22', :rounds => 9)
     #   t.site = 'http://www.bcmchess.co.uk/monarch2007/'
-    #   t.add_player(ICU::Player.new('Anthony',  'Fox',      1, :rating => 2100, :fed => 'IRL', :id => 456))
-    #   t.add_player(ICU::Player.new('Peter P.', 'Taylor',   2, :rating => 2209, :fed => 'ENG'))
-    #   t.add_player(ICU::Player.new('Egozi',    'Nadav',    3, :rating => 2205, :fed => 'ISR'))
-    #   t.add_player(ICU::Player.new('Peter',    'Cafolla',  4, :rating => 2048, :fed => 'IRL'))
-    #   t.add_player(ICU::Player.new('Tim R.',   'Spanton',  5, :rating => 1982, :fed => 'ENG'))
-    #   t.add_player(ICU::Player.new('Alan',     'Grant',    6, :rating => 2223, :fed => 'SCO'))
-    #   t.add_player(ICU::Player.new('Alan J.',  'Walton',   7, :rating => 2223, :fed => 'ENG'))
-    #   t.add_player(ICU::Player.new('Bernard',  'Bannink',  8, :rating => 2271, :fed => 'NED', :title => 'FM'))
-    #   t.add_player(ICU::Player.new('Roy',      'Phillips', 9, :rating => 2271, :fed => 'MAU'))
+    #   t.add_player(ICU::Player.new('Anthony',  'Fox',      1, :fide_rating => 2100, :fed => 'IRL', :id => 456))
+    #   t.add_player(ICU::Player.new('Peter P.', 'Taylor',   2, :fide_rating => 2209, :fed => 'ENG'))
+    #   t.add_player(ICU::Player.new('Egozi',    'Nadav',    3, :fide_rating => 2205, :fed => 'ISR'))
+    #   t.add_player(ICU::Player.new('Peter',    'Cafolla',  4, :fide_rating => 2048, :fed => 'IRL'))
+    #   t.add_player(ICU::Player.new('Tim R.',   'Spanton',  5, :fide_rating => 1982, :fed => 'ENG'))
+    #   t.add_player(ICU::Player.new('Alan',     'Grant',    6, :fide_rating => 2223, :fed => 'SCO'))
+    #   t.add_player(ICU::Player.new('Alan J.',  'Walton',   7, :fide_rating => 2223, :fed => 'ENG'))
+    #   t.add_player(ICU::Player.new('Bernard',  'Bannink',  8, :fide_rating => 2271, :fed => 'NED', :title => 'FM'))
+    #   t.add_player(ICU::Player.new('Roy',      'Phillips', 9, :fide_rating => 2271, :fed => 'MAU'))
     #   t.add_result(ICU::Result.new(1, 1, 'L', :opponent => 2, :colour => 'B'))
     #   t.add_result(ICU::Result.new(2, 1, 'D', :opponent => 3, :colour => 'W'))
     #   t.add_result(ICU::Result.new(3, 1, 'D', :opponent => 4, :colour => 'B'))
@@ -221,7 +222,7 @@ module ICU
                 o = t.player(r.opponent)
                 data << o.last_name
                 data << o.first_name
-                data << o.rating
+                data << o.fide_rating
                 data << o.title
                 data << o.fed
               else
@@ -250,6 +251,7 @@ module ICU
         end
       end
 
+      # :enddoc:
       private
 
       def event
@@ -308,7 +310,7 @@ module ICU
           @tournament.add_result(result)
         else
           result.colour = @r[2]
-          opponent = Player.new(@r[4], @r[3], @tournament.players.size + 1, :rating => @r[5], :title => @r[6], :fed => @r[7])
+          opponent = Player.new(@r[4], @r[3], @tournament.players.size + 1, :fide_rating => @r[5], :title => @r[6], :fed => @r[7])
           raise "opponent must have a federation" unless opponent.fed
           old_player = @tournament.find_player(opponent)
           if old_player

data/lib/icu_tournament/tournament_krause.rb

@@ -48,13 +48,15 @@ module ICU
     #   daffy.fide                        # => nil
     #   daffy.dob                         # => "1937-04-17"
     #
-    # By default, ID numbers in the input are interpreted as local IDs. If, instead, they should be interpreted as
-    # FIDE IDs, add the following option:
+    # By default, ID numbers and ratings in the input are interpreted as local IDs and ratings. If, instead, they should be interpreted as
+    # FIDE IDs and ratings, add the following option:
     #
     #   tournament = parser.parse_file('tournament.tab', :fide => true)
     #   daffy = tournament.player(2)
     #   daffy.id                          # => nil
     #   daffy.fide                        # => 7654321
+    #   daffy.rating                      # => nil
+    #   daffy.fide_rating                 # => 2200
     #
     # If the ranking numbers are missing from the file or inconsistent (e.g. player A is ranked above player B
     # but has less points than player B) they are recalculated as a side effect of the parse.
@@ -82,11 +84,11 @@ module ICU
     #
     #   krause = tournament.serialize('Krause')
     #
-    # By default, local (ICU) IDs are used for the serialization, but both methods accept an option that
-    # causes FIDE IDs to be used instead:
+    # By default, local (ICU) IDs and ratings are used for the serialization, but both methods accept an option that
+    # causes FIDE IDs and ratings to be used instead:
     #
     #   krause = parser.serialize(tournament, :fide => true)
-    #   krause = parser.serialize(tournament, :fide => true)
+    #   krause = tournament.serialize('Krause', :fide => true)
     #
     # The following lists Krause data identification numbers, their description and, where available, their corresponding
     # attributes in an ICU::Tournament instance.
@@ -241,6 +243,7 @@ module ICU
         # None.
       end
 
+      # :enddoc:
       private
 
       def set_name
@@ -263,12 +266,12 @@ module ICU
         {
           :gender => @data[5, 1],
           :title  => @data[6, 3],
-          :rating => @data[44, 4],
           :fed    => @data[49, 3],
           :dob    => @data[65, 10],
           :rank   => @data[81, 4],
         }
         opt[arg[:fide] ? :fide : :id] = @data[53, 11]
+        opt[arg[:fide] ? :fide_rating : :rating] = @data[44, 4]
         player = Player.new(nam.first, nam.last, num, opt)
         @tournament.add_player(player)
 
@@ -337,7 +340,7 @@ module ICU
       krause << sprintf(' %1s', case @gender; when 'M' then 'm'; when 'F' then 'w'; else ''; end)
       krause << sprintf(' %2s', case @title; when nil then ''; when 'IM' then 'm'; when 'WIM' then 'wm'; else @title[0, @title.length-1].downcase; end)
       krause << sprintf(' %-33s', "#{@last_name},#{@first_name}")
-      krause << sprintf(' %4s', @rating)
+      krause << sprintf(' %4s', arg[:fide] ? @fide_rating : @rating)
       krause << sprintf(' %3s', @fed)
       krause << sprintf(' %11s', arg[:fide] ? @fide : @id)
       krause << sprintf(' %10s', @dob)

data/lib/icu_tournament/tournament_sp.rb

@@ -35,22 +35,17 @@ module ICU
     # If no start date is supplied it will default to 2000-01-01, and can be reset later.
     #
     #   tournament = parser.parse_file('champs.zip')
-    #   tournament.start                # => '2000-01-01'
+    #   tournament.start                 # => '2000-01-01'
     #   tournament.start = '2010-07-03'
     #
-    # SwissPerfect files have slots for both local and international IDs and these, if present
-    # and if intergers are copied to the _id_ and _fide_ attributes respectively.
-    #
-    # By default, the parser extracts the local rating from the SwissPerfect files and not the international one.
-    # If international ratings are required instead, set the _rating_ option to "intl". For example:
+    # SwissPerfect files have slots for both local and international IDs and ratings and these, if present
+    # (and if integers) are copied to the _id_, _fide_, _rating_ and _fide_rating_ attributes.
     #
     #   tournament = parser.parse_file('ncc', :start => '2010-05-08')
-    #   tournament.player(2).id         # =>  12379 (ICU ID)
-    #   tournament.player(2).fide       # =>  1205064 (FIDE ID)
-    #   tournament.player(2).rating     # =>  2556 (ICU rating)
-    #
-    #   tournament = parser.parse_file('ncc', :start => '2010-05-08', :rating => 'intl')
-    #   tournament.player(2).rating     # =>  2530 (FIDE rating)
+    #   tournament.player(2).id          # =>  12379 (ICU ID)
+    #   tournament.player(2).fide        # =>  1205064 (FIDE ID)
+    #   tournament.player(2).rating      # =>  2556 (ICU rating)
+    #   tournament.player(2).fide_rating # =>  2530 (FIDE rating)
     #
     # By default, the parse will fail completely if the ".trn" file contains any invalid federations (see ICU::Federation).
     # There are two alternative behaviours controlled by setting the _fed_ option:
@@ -62,55 +57,23 @@ module ICU
     #
     # Because the data is in three parts, some of which are in a legacy binary format, serialization to this format is
     # not supported. Instead, a method is provided to serialize any tournament type into the text export format of
-    # erfect, an example of which is shown below.
-    #
-    #   No  Name                 Loc Id  Total   1     2     3
-    #
-    #   1   Griffiths, Ryan-Rhys 6897    3       4:W   2:W   3:W
-    #   2   Flynn, Jamie         5226    2       3:W   1:L   4:W
-    #   3   Hulleman, Leon       6409    1       2:L   4:W   1:L
-    #   4   Dunne, Thomas        10914   0       1:L   3:L   2:L
-    #
-    # This format is important in Irish chess, as it's the format used to submit results to the <em>MicroSoft Access</em>
-    # implementation of the ICU ratings database.
-    #
-    #   swiss_perfect = tournament.serialize('SwissPerfect')
-    #
-    # The order of players in the serialized output is always by player number and as a side effect of serialization,
-    # the player numbers will be adjusted to ensure they range from 1 to the total number of players (i.e. renumbered
-    # in order). If you would prefer rank-order instead, then you must first renumber the players by rank (the default
-    # renumbering method) before serializing. For example:
-    #
-    #   swiss_perfect = tournament.renumber.serialize('SwissPerfect')
-    #
-    # There should be no need to explicitly rank the tournament first, as that information is already present in
-    # SwissPerfect files (i.e. each player should already have a rank after the files have been parsed).
-    # Additionally, the tie break rules used for the tournament are available from the _tie_break_ method,
-    # for example:
-    #
-    #   tournament.tie_breaks           # => [:buchholz, :harkness]
-    #
-    # Should you wish to rank the tournament using a different set of tie-break rules, you can do something like the following:
-    #
-    #   tournament.tie_breaks = [:wins, :blacks]
-    #   swiss_perfect = tournament.rerank.renumber.serialize('SwissPerfect')
-    #
-    # See ICU::Tournament for more about tie-breaks.
+    # SwissPerfect (see ICU::Tournament::SPExport).
     #
     class SwissPerfect
       attr_reader :error
 
       TRN = {
-        :dob        => "BIRTH_DATE",
-        :fed        => "FEDER",
-        :first_name => "FIRSTNAME",
-        :gender     => "SEX",
-        :id         => "LOC_ID",
-        :fide       => "INTL_ID",
-        :last_name  => "SURNAME",
-        :num        => "ID",
-        :rank       => "ORDER",
-        :rating     => ["LOC_RTG", "INTL_RTG"],
+        :dob         => "BIRTH_DATE",
+        :fed         => "FEDER",
+        :first_name  => "FIRSTNAME",
+        :gender      => "SEX",
+        :id          => "LOC_ID",
+        :fide        => "INTL_ID",
+        :last_name   => "SURNAME",
+        :num         => "ID",
+        :rank        => "ORDER",
+        :rating      => "LOC_RTG",
+        :fide_rating => "INTL_RTG",
       } # not used: ABSENT BOARD CLUB FORB_PAIRS LATE_ENTRY LOC_RTG2 MEMO TEAM TECH_SCORE WITHDRAWAL (START_NO, BONUS used below)
 
       SCO = %w{ROUND WHITE BLACK W_SCORE B_SCORE W_TYPE B_TYPE}  # not used W_SUBSCO, B_SUBSCO
@@ -175,6 +138,7 @@ module ICU
         # None.
       end
 
+      # :enddoc:
       private
 
       def get_files(file, arg)
@@ -280,15 +244,15 @@ module ICU
         @start_no[r.attributes["ID"]] = r.attributes["START_NO"]
         TRN.inject(Hash.new) do |hash, pair|
           key = pair[1]
-          key = key[arg[pair[0]].to_s == 'intl' ? 1 : 0] if key.class == Array
           val = r.attributes[key]
           case pair[0]
-          when :fed    then val = val && val.match(/^[A-Z]{3}$/i) ? val.upcase : nil
-          when :gender then val = val.to_i > 0 ? %w(M F)[val.to_i-1] : nil
-          when :id     then val = val.to_i > 0 ? val : nil
-          when :fide   then val = val.to_i > 0 ? val : nil
-          when :rating then val = val.to_i > 0 ? val : nil
-          when :title  then val = val.to_i > 0 ? %w(GM WGM IM WIM FM WFM)[val.to_i-1] : nil
+          when :fed         then val = val && val.match(/^[A-Z]{3}$/i) ? val.upcase : nil
+          when :gender      then val = val.to_i > 0 ? %w(M F)[val.to_i-1] : nil
+          when :id          then val = val.to_i > 0 ? val : nil
+          when :fide        then val = val.to_i > 0 ? val : nil
+          when :rating      then val = val.to_i > 0 ? val : nil
+          when :fide_rating then val = val.to_i > 0 ? val : nil
+          when :title       then val = val.to_i > 0 ? %w(GM WGM IM WIM FM WFM)[val.to_i-1] : nil
           end
           if pair[0] == :fed && val && arg[:fed]
             val = nil if arg[:fed].to_s == 'ignore'

data/lib/icu_tournament/tournament_spx.rb

@@ -0,0 +1,397 @@
+module ICU
+  class Tournament
+    #
+    # The SWissPerfect export format used to be important in Irish chess as it was used to submit
+    # results to the ICU's first computerised ratings system, a <em>MicroSoft Access</em> database.
+    # As a text based format, it was easier to manipulate than the full binary formats of SwissPerfect.
+    # Here is an illustrative example of this format:
+    #
+    #   No Name           Feder Intl Id Loc Id Rtg  Loc  Title Total  1   2   3
+    #
+    #   1  Duck, Daffy    IRL           12345       2200 im    2     0:= 3:W 2:D
+    #   2  Mouse, Minerva       1234568        1900            1.5   3:D 0:= 1:D
+    #   3  Mouse, Mickey  USA   1234567                  gm    1     2:D 1:L 0:=
+    #
+    # The format does not record either the name nor the start date of the tournament.
+    # Player colours are also missing. When parsing data in this format it is necessary
+    # to specify name and start date explicitly:
+    #
+    #   parser = ICU::Tournament::SPExport.new
+    #   tournament = parser.parse_file('sample.txt', :name => 'Mickey Mouse Masters', :start => '2011-02-06')
+    #
+    #   tournament.name                   # => "Mickey Mouse Masters"
+    #   tournament.start                  # => "2011-02-06"
+    #   tournament.rounds                 # => 3
+    #   tournament.player(1).name         # => "Duck, Daffy"
+    #   tournament.player(2).points       # => 1.5
+    #   tournament.player(3).fed          # => "USA"
+    #
+    # See ICU::Tournament for further details about the object returned.
+    #
+    # The SwissPerfect application offers a number of choices when exporting a tournament cross table,
+    # one of which is the column separator. The ICU::Tournament::SPExport parser can only handle data
+    # with tab separators but is able to cope with any other configuration choices. For example, if
+    # some of the optional columns are missing or if the data is not formatted with space padding.
+    #
+    # To serialize an ICU::Tournament instance to the format, use the _serialize_ method of
+    # the appropriate parser:
+    #
+    #   parser = ICU::Tournament::Krause.new
+    #   spexport = parser.serialize(tournament)
+    #
+    # or use the _serialize_ method of the instance with the appropraie format name:
+    #
+    #   spexport = tournament.serialize('SPExport')
+    #
+    # In either case the method returns a string representation of the tourament in SwissPerfect export
+    # format with tab separators, space padding and (by default) the local player ID and total score
+    # optional columns:
+    #
+    #   No  Name                 Loc Id  Total    1     2     3
+    #
+    #   1   Griffiths, Ryan-Rhys 6897    3       4:W   2:W   3:W
+    #   2   Flynn, Jamie         5226    2       3:W   1:L   4:W
+    #   3   Hulleman, Leon       6409    1       2:L   4:W   1:L
+    #   4   Dunne, Thomas        10914   0       1:L   3:L   2:L
+    #
+    # To change which optional columns are output, use the _columns_ option with an array of the column attribute names.
+    # The optional attribute names, together with their column header names in SwissPerfect, are as follows:
+    #
+    # * _fed_: Feder
+    # * _fide_: Intl Id
+    # * _id_: Loc Id
+    # * _fide_: ting_ (Rtg
+    # * _rating_: Loc
+    # * _title_: Title
+    # * _points_: Total
+    #
+    # So, for example, to omitt the optional columns completely, supply an empty array of column names:
+    #
+    #   tournament.serialize('SPExport', :columns => [])
+    #
+    #   No  Name                  1     2     3
+    #                            
+    #   1   Griffiths, Ryan-Rhys 4:W   2:W   3:W
+    #   2   Flynn, Jamie         3:W   1:L   4:W
+    #   3   Hulleman, Leon       2:L   4:W   1:L
+    #   4   Dunne, Thomas        1:L   3:L   2:L
+    #
+    # Or supply whatever columns you want, for example:
+    #
+    #   tournament.serialize('SPExport', :columns => [:fide, :fide_rating])
+    #
+    # Note that the column order in the serialised string is the same as it is in the SwissPerfect application.
+    # The order of column names in the _columns_ hash has no effect.
+    #
+    # The default, when you leave out the _columns_ option is equivalent to:
+    #
+    #   tournament.serialize('SPExport', :columns => [:id, :points])
+    #
+    # The order of players in the serialized output is always by player number and as a side effect of serialization,
+    # the player numbers will be adjusted to ensure they range from 1 to the total number of players maintaining the
+    # original order. If you would prefer rank-order instead, then you must first renumber the players by rank (the
+    # default renumbering method) before serializing. For example:
+    #
+    #   spexport = tournament.renumber(:rank).serialize('SPExport')
+    #
+    # Or equivalently, since renumbering by rank is the default, just:
+    #
+    #   spexport = tournament.renumber.serialize('SPExport')
+    #
+    # You may wish set the tie-break rules before ranking:
+    #
+    #   tournament.tie_breaks = [:buchholz, ::neustadtl]
+    #   spexport = tournament.rerank.renumber.serialize('SwissPerfect')
+    #
+    # See ICU::Tournament for more about tie-breaks.
+    #
+    class SPExport
+      attr_reader :error
+
+      # Parse SwissPerfect export data returning a Tournament on success or raising an exception on error.
+      def parse!(spx, arg={})
+        @tournament = init_tournament(arg)
+        @lineno = 0
+        @header = nil
+        @results = Array.new
+        spx = ICU::Util.to_utf8(spx) unless arg[:is_utf8]
+
+        # Process each line.
+        spx.each_line do |line|
+          @lineno += 1
+          line.strip!          # remove leading and trailing white space
+          next if line == ''   # skip blank lines
+
+          if @header
+            process_player(line)
+          else
+            process_header(line)
+          end
+        end
+
+        # Now that all players are present, add the results to the tournament.
+        @results.each do |r|
+          lineno, player, data, result = r
+          begin
+            @tournament.add_result(result)
+          rescue => err
+            raise "line #{lineno}, player #{player}, result '#{data}': #{err.message}"
+          end
+        end
+
+        # Finally, exercise the tournament object's internal validation, reranking if neccessary.
+        @tournament.validate!(:rerank => true)
+
+        @tournament
+      end
+
+      # Parse SwissPerfect export text 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(spx, arg={})
+        begin
+          parse!(spx, arg)
+        rescue => ex
+          @error = ex.message
+          nil
+        end
+      end
+
+      # Same as <em>parse!</em> except the input is a file name rather than file contents.
+      def parse_file!(file, arg={})
+        spx = ICU::Util.read_utf8(file)
+        arg[:is_utf8] = true
+        parse!(spx, arg)
+      end
+
+      # Same as <em>parse</em> except the input is a file name rather than file contents.
+      def parse_file(file, arg={})
+        begin
+          parse_file!(file, arg)
+        rescue => ex
+          @error = ex.message
+          nil
+        end
+      end
+
+      # Serialise a tournament to SwissPerfect text export format.
+      def serialize(t, arg={})
+        t.validate!(:type => self)
+
+        # Ensure a nice set of player numbers and get the number of rounds.
+        t.renumber(:order)
+        rounds = t.last_round
+        
+        # Optional columns.
+        optional = arg[:columns] if arg.instance_of?(Hash) && arg[:columns].instance_of?(Array)
+        optional = [:id, :points] unless optional
+        
+        # Columns identifiers in SwissPerfect order.
+        columns = Array.new
+        columns.push(:num)
+        columns.push(:name)
+        [:fed, :fide, :id, :fide_rating, :rating, :title, :points].each { |x| columns.push(x) if optional.include?(x) }
+        
+        # SwissPerfect headers for each column (other than the rounds, which are treated separately).
+        header = Hash.new
+        columns.each do |col|
+          header[col] = case col
+          when :num         then "No"
+          when :name        then "Name"
+          when :fed         then "Feder"
+          when :fide        then "Intl Id"
+          when :id          then "Loc Id"
+          when :fide_rating then "Rtg"
+          when :rating      then "Loc"
+          when :title       then "Title"
+          when :points      then "Total"
+          end
+        end
+        
+        # Widths and formats for each column.
+        width = Hash.new
+        format = Hash.new
+        columns.each do |col|
+          width[col] = t.players.inject(header[col].length) { |l, p| p.send(col).to_s.length  > l ? p.send(col).to_s.length  : l }
+          format[col] = "%-#{width[col]}s"
+        end
+
+        # The header, followed by a blank line.
+        formats = columns.map{ |col| format[col] }
+        (1..rounds).each { |r| formats << "%#{width[:num]}d  " % r }
+        sp = formats.join("\t") % columns.map{ |col| header[col] }
+        sp << "\r\n\r\n"
+
+        # The round formats for players are slightly different to those for the header.
+        formats.pop(rounds)
+        (1..rounds).each{ |r| formats << "%#{2+width[:num]}s" }
+        
+        # Serialize the formats already.
+        formats = formats.join("\t") + "\r\n"
+
+        # Now add a line for each player.
+        t.players.each { |p| sp << p.to_sp_text(rounds, columns, formats) }
+
+        # And return the whole lot.
+        sp
+      end
+
+      # Additional tournament validation rules for this specific type.
+      def validate!(t)
+        # None.
+      end
+
+      # :enddoc:
+      private
+
+      def init_tournament(arg)
+        raise "tournament name missing"       unless arg[:name]
+        raise "tournament start date missing" unless arg[:start]
+        Tournament.new(arg[:name], arg[:start])
+      end
+
+      def process_header(line)
+        raise "header should always start with 'No'" unless line.match(/^No\s/)
+        items = line.split(/\t/).map(&:strip)
+        raise "header requires tab separators" unless items.size > 2
+        @header = Hash.new
+        @rounds = 1
+        items.each_with_index do |item, i|
+          key = case item
+          when 'No'      then :num
+          when 'Name'    then :name
+          when 'Total'   then :total
+          when 'Loc Id'  then :id
+          when 'Intl Id' then :fide
+          when 'Title'   then :title
+          when 'Feder'   then :fed
+          when 'Loc'     then :rating
+          when 'Rtg'     then :fide_rating
+          when /^[1-9]\d*$/
+            round   = item.to_i
+            @rounds = round if round > @rounds
+            round
+          else nil
+          end
+          @header[key] = i if key
+        end
+        raise "header is missing 'No'"    unless @header[:num]
+        raise "header is missing 'Name'"  unless @header[:name]
+        (1..@rounds).each { |r| raise "header is missing round #{r}" unless @header[r] }
+      end
+
+      def process_player(line)
+        items = line.split(/\t/).map(&:strip)
+        raise "line #{@lineno} has too few items" unless items.size > 2
+
+        # Player details.
+        num  = items[@header[:num]]
+        name = Name.new(items[@header[:name]])
+        opt  = Hash.new
+        [:fed, :title, :id, :fide, :rating, :fide_rating].each do |key|
+          if @header[key]
+            val = items[@header[key]]
+            opt[key] = val unless val.nil? || val == ''
+          end
+        end
+
+        # Create the player and add it to the tournament.
+        player = Player.new(name.first, name.last, num, opt)
+        @tournament.add_player(player)
+
+        # Save the results for later processing.
+        points = items[@header[:total]] if @header[:total]
+        points = nil if points == ''
+        points = points.to_f if points
+        total = 0.0;
+        (1..@rounds).each do |r|
+          total+= process_result(r, player.num, items[@header[r]])
+        end
+        total = points if points && fix_invisible_bonuses(player.num, points - total)
+        raise "declared points total (#{points}) does not agree with total from summed results (#{total})" if points && points != total
+      end
+
+      def process_result(round, player_num, data)
+        raise "illegal result (#{data})" unless data.match(/^(0|[1-9]\d*)?:([-+=LWD])?$/i)
+        opponent = $1.to_i
+        score = $2 || 'L'
+        options = Hash.new
+        options[:opponent] = opponent unless opponent == 0
+        options[:rateable] = false    unless score && score.match(/^(W|L|D)$/i)
+        result = Result.new(round, player_num, score, options)
+        @results << [@lineno, player_num, data, result]
+        result.points
+      end
+
+      def fix_invisible_bonuses(player_num, difference)
+        # We don't need to fix it if it's not broken.
+        return false if difference == 0.0
+        # We can't fix a summed total that is greater than the declared total.
+        return false if difference < 0.0
+        # Get the player's results objects from the temporary store.
+        results = @results.select{ |r| r[1] == player_num }.map{ |r| r.last }
+        # Get all losses and draws that don't have opponents (because their scores can be harmlessly altered).
+        losses = results.reject{ |r| r.opponent || r.score != 'L' }.sort{ |a,b| a.round <=> b.round }
+        draws  = results.reject{ |r| r.opponent || r.score != 'D' }.sort{ |a,b| a.round <=> b.round }
+        # Give up unless these results have enough capacity to accomodate the points difference.
+        return false unless difference <= 1.0 * losses.size + 0.5 * draws.size
+        # Start promoting losses to draws.
+        losses.each do |loss|
+          loss.score = 'D'
+          difference -= 0.5
+          break if difference == 0.0
+        end
+        # If that's not enough, start promoting draws to wins.
+        if difference > 0.0
+          draws.each do |draw|
+            draw.score = 'W'
+            difference -= 0.5
+            break if difference == 0.0
+          end
+        end
+        # And if that's not enough, start promoting losses to wins.
+        if difference > 0.0
+          losses.each do |loss|
+            loss.score = 'W'
+            difference -= 0.5
+            break if difference == 0.0
+          end
+        end
+        # Signal success.
+        return true
+      end
+    end
+  end
+
+  class Player
+    # Format a player's record as it would appear in an SP export file.
+    def to_sp_text(rounds, columns, formats)
+      values = columns.inject([]) do |vals,col|
+        val = send(col).to_s
+        val.sub!(/\.0/, '') if col == :points
+        vals << val
+      end
+      (1..rounds).each do |r|
+        result = find_result(r)
+        values << (result ? result.to_sp_text : " : ")
+      end
+      formats % values
+    end
+  end
+
+  class Result
+    # Format a player's result as it would appear in an SP export file.
+    def to_sp_text
+      sp = opponent ? opponent.to_s : '0'
+      sp << ':'
+      if rateable
+        sp << score
+      else
+        sp << case score
+        when 'W' then '+'
+        when 'L' then '-'
+        else '='
+        end
+      end
+    end
+  end
+end