‘libtour’ tournament processing library

Each sporting tournament consists of a number of stages, examples of stages are Preliminary Stage, Quater Finals, Finals.

Each stage includes one or more group; for instance a Preliminary Stage may contain groups A, B, C, and D; Finals may contain a single group of two teams that compete for the winner's title.

Each group has two or more teams. Before the tournament starts, only groups of the first stage know their teams. By the completion of the first stage it is usually possible to programmatically determine teams that advance to the following stage, based on their results, and so on for all stages.

Given rules of the tournament (points allocated to a team in a game, as well as sorting criteria for table of standings), initial teams and game schedule it is possible to interpret its results inside a computer program.

libtour is a generic tournament processing library written in C++. Rules, teams and schedule of a tournament are defined in the Scheme programming language (Guile) and given to the library as input. What makes libtour generic is the fact that it only expects the structure of a tournament be as described in the "Concepts" section above, and does not know anything else about it. Therefore it is possible to make libtour interpret virtually any sporting tournament.

Scheme language seems a perfect choice for tournament definitions as it allows to easily intermix data and processing logic. Guile interpreter packaged as a library (libguile) makes it simple to mix C and Scheme function calls. Many thanks to the people who made Guile happen.

• simple protocol to communicate with the library through request/reply objects
• queries of data coming from the Scheme definitions (game, team and team result fields, date format etc)
• queries of interpreted data (table of standings, game schedule with results, teams etc)
• notion of the "local team ID" that allows definitions of future stages without knowing real teams
• ability to query the information for stages whose teams hasn't been determined yet
• support for different group formulas (round robin, game count, playoffs)
• support for excessive games (those in the schedule but not necessary to play, like in a playoff stage)
• support for carry-forward game results, and incidentally, predefined games results
• game schedule verification
• support for dynamic creation of (parts of) the game schedule
• support for sorting conflicts within a group (when the rules fail to determine exact team positioning) and providing manual resolution for such conflicts (updated in ver. 0.9.2)
• summary groups (one per stage) provided by the library
• support for creating custom groups on the fly using team and/or game filtering procedures defined in Scheme; information on the interface of available filters (since ver. 0.9.0)
• loading and interpreting more than one tournament at a time
• saving and restoring tournament state
• comprehensive (?) documentation

• currently only two-player (not multi-player) games are supported

Scheme definitions for the following tournaments are included in libtour distribution:

• FIFA World Cup 2002
• Ice Hockey World Championship 2003
• NHL 2002
• NHL 2003
• NHL 2004

It should be fairly easy to add more definitions.

libtour ships with a simple CLI application that allows you to fully interact with the library (see a sample session). I am also working on a Qt-based GUI program which is definitely more fun to use, see the qtour project at sourceforge.

• HTML
• PDF