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, 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.


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).

Current Maintainer

David Murray, rating officer for the Irish Chess Union. Contact [email protected]