= ICU Tournament

For reading or writing files of chess tournament data. Original project name on github was _chess_icu_.

== Install

For Ruby 1.9.2, 1.9.3, 2.0.0, 2.2.1 (version 1.1.2 was the last compatible with Ruby 1.8.7).

  gem install icu_tournament

For name canonicalisation, the _icu_name_ gem is required and
for handling SwissPerfect files the _dbf_ and _rubyzip_ gems are needed.

== Usage

There are two main uses for this gem:

* You have chess tournament data that needs to be written to a file in one of the supported formats.
  For example, your data is in a spreadsheet but you need it in Krause format so you can upload it to the FIDE rating server.

* You have a file in a supported format and you need to extract the information it contains.
  For example, you have a Krause formatted file and want to extract the data and insert it into a database.

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

Here's how the 1972 Fischer-Spassky match could be formatted to Krause. First a tournament object is created
and the players (just two in this case) are added with unique ID numbers. To keep the example short, not all
the information that a Krause file might contain is included here (see ICU::Tournament::Krause for more details).

  t = ICU::Tournament.new('World Championship', '1972-07-11')
  t.add_player(ICU::Player.new('Robert J.', 'Fischer', 1))
  t.add_player(ICU::Player.new('Boris V.', 'Spassky', 2))

Then the results for each round are added using the unique ID numbers to refer to the players.

  t.add_result(ICU::Result.new(1, 1, 'L', :opponent => 2, :colour => 'B'))

Read this as: in round 1, player 1 lost against opponent 2 with the black pieces.

  t.add_result(ICU::Result.new(2, 1, 'L', :opponent => 2, :colour => 'W', :rateable => false))

In round 2 player 1 lost by default against player 2. Similarly for all the other rounds:

  t.add_result(ICU::Result.new(3, 1, 'W', :opponent => 2, :colour => 'B'))
  # ...
  t.add_result(ICU::Result.new(21, 1, 'W', :opponent => 2, :colour => 'B'))

Then finally, to create the file:

  open('match.txt', 'w') { |f| f.puts @t.serialize('Krause') }

== Reading Files

Suppose you have a tournament file in Krause format. Parse it into a tournament object like this:

  data = open('tournament.txt') { |f| f.read }
  parser = ICU::Tournament::Krause.new
  tournament = parser.parse(data)

On success, the _parse_ method returns an object of type ICU::Tournament. A tournament (ICU::Tournament)
has two or more players (ICU::Player), and each player has one or more results (ICU::Result). See the
rdoc for more details. You can traverse these objects and do what you want with them, such as storing the
information in a database.

On error, the _parse_ method returns _nil_ and an error message can be retrieved from the parser (parser.error).

== Author

Mark Orr, rating officer for the Irish Chess Union (ICU[http://icu.ie]).

== Current Maintainer

David Murray, rating officer for the Irish Chess Union. Contact ratings@icu.ie.