ICU Tournament

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


For Ruby 1.9.2, 1.9.3, 2.0.0 (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.


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 ='World Championship', '1972-07-11')
t.add_player('Robert J.', 'Fischer', 1))
t.add_player('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(, 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(, 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(, 1, 'W', :opponent => 2, :colour => 'B'))
# ...
t.add_result(, 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| }
parser =
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).


Mark Orr, rating officer for the Irish Chess Union (ICU).