Go to the first, previous, next, last section, table of contents.


libtour API

Header files named `t_*.hh' are intended to be used by a program that links libtour. These headers are normally installed in the `$prefix/include' directory. The following sections describe how to use the libtour API. The examples are using STL's string class.

Initializing libtour

First of all, boot guile (the flow control will resume in innner_main once Guile is initialized):

#include <t_tour.hh>
#include <t_exception.hh>
#include <config.h>

int
main( int argc, char** argv )
{
    scm_boot_guile(argc, argv, inner_main, 0);
    return 0;
}

static void
inner_main( void*, int argc, char** argv )
{
    ...

Now you have to set path(s) to your tournament definitions. Use either T_Tour::appendPath() to append a single directory:

    string mydir = ...
    T_Tour::appendPath( mydir );

or T_Tour::setPath() to use several directories:

    vector<string> mydirs;
    ...
    T_Tour::setPath( mydirs );

libtour installation contains a directory with several tournament definitions, its location can be retrieved with libour-config command line tool.

libtour user code should be enclosed in a try ... catch block since the libtour calls may throw T_Exception objects.

    try {
        T_Tour tour( tour_name ); //parse the tournament definition
        ...
    }
    catch ( T_Exception& e ) { cerr << e.why() << endl; }

It is possible to distinguish between errors caused by invalid tournament definitions (Scheme code) and invalid requests on one side, and internal libtour errors on the other. For details on the exception classes' hierarchy See section Main classes, and `t_exception.hh' header.

Inside the try ... catch block after the tour_name tournament definition is parsed in the T_Tour constructor, we can load previously saved results (see section Saving and restoring state), or get the latest ones and save them:

        string saved_results = getSavedResults();
        tour.loadResults( saved_results );
        ...

        string latest_results = tour.getResults();
        saveResults( latest_results );

where getSavedResults() and saveResults() read and write a result file. And you can, of course, query and modify the tournament state.

Interacting with the tournament

To make a query (either read-only or modifying) you have to prepare a T_QuerySpec object and pass it to the T_Tour instance:

#include <t_tour.hh>
#include <t_query.hh>

...
    T_Tour tour( tour_name );

    T_QuerySpec q;
    ... //fill in the query

    T_QueryResults res;
    tour.processQuery( q, res );
    ... //process result

    T_QuerySpec q2;
    ... //fill in the insertion request
    tour.processInsert( q2 );

T_Tour::processQuery() will fill in a T_QueryResults object passed to it with the results of the query. T_Tour::processInsert(), on the other hand, changes the state of a tournament and returns nothing. Both of these methods will throw a T_Exception if anything goes wrong.

The following sections explain how to make a query (see section Making a query object) and interpret the result (see section Processing query result).

Making a query object

To communicate with libtour the user code has to encaplulate its request into a T_QuerySpec object and pass it to either T_Tour::processQuery() or T_Tour::processInsert() method (see section Interacting with the tournament).

There are two parts in a T_QuerySpec object:

  1. target -- what to get
  2. options -- how to get it

Both target and options of a query should belong to the T_QuerySpec::Token enumeration:

class T_QuerySpec
{
    enum Token {
        UNDEFINED=-1,
        ID,              //id
        INFO,            //info
        NAME,            //name
        STAGE,           //stage
        GROUP,           //group
        DEL_GROUP,       //delete usr group
        TEAM,            //team
        TEAM1,           //first team
        TEAM2,           //second team
        GAME,            //game
        UN_GAME,         //undo game
        SCHEDULE,        //schedule
        STANDINGS,       //standings
        S_CONFLICT,      //sorting conflict
        S_CONFLICT_DET,  //sorting conflict details
        S_CONFLICT_SOL,  //solution of a sorting conflict
        POS_RANGE,       //position range
        G_RESULT,        //game result
        COMPLETE,        //complete stage
        UN_COMPLETE,     //uncomplete stage
        TEAM_FIELDS,     //team result fields
        STANDINGS_FIELDS,//team result fields
        GAME_FIELDS,     //game result fields
        SCHEDULE_FIELDS, //schedule fields
        DATE_FORMAT,     //date/time format
        HOME_POSITION,   //position of the home team
        EXCESSIVE_GAMES, //ids of excessive games
        BELONGS,         //game belongs to group
        WINNERS,         //winners
        TEAM_FILTER,     //team filter for making usr groups
        GAME_FILTER,     //game filter for making usr groups
        FILTER_ARGS      //team or game filter arguments
	MAX_POINTS       //max points in a game
    };
    ...
};

For instance, to query the standings table of the group A of the stage S1 one would do the following:

T_QuerySpec qs;
qs.setTarget( T_QuerySpec::STANDINGS );
qs.setOption( T_QuerySpec::STAGE, "S1" );
qs.setOption( T_QuerySpec::GROUP, "A" );

T_QueryResults res;
tour.processQuery( qs, res );

Naturally, not all combinations of target and options make sence. Passing invalid queries will result in a T_RuntimeException exceptions thrown. See section Query reference, for a complete listing of possible queries and their results.

Processing query result

A T_QueryResults instance filled in by the T_Tour::processQuery() call contains tabular results of the query. For example, a standings query will build a T_QueryResults object representing the table of standings etc. The cells are of the abstract T_QueryData type. Columns of the table are guaranteed to contain values of the same type derived from T_QueryData. This can be one of the following: T_QueryStringData, T_QueryIntData, T_QueryIntRangeData, or T_QueryBoolData. One can treat the cells polymorphically by using T_QueryData::toString() virtual method. If, however, it is required to access methods of a particular derived class, you will have to downcast.

The code below shows how to loop through a T_QueryResults object:

#include <t_query.hh>
...

//get T_QueryResults res

    for ( size_t row = 0; row < res.nRows(); ++row ) {
        for ( size_t col = 0; col < res[row].nCols(); ++col ) {
            cout << res[row][col].toString() << ' ';
        }
        cout << endl;
    }

Alternatively, you can get the cell content by its row number and column name by means of T_QueryResults::value():

    for ( size_t row = 0; row < res.nRows(); ++row ) {
        cout << res.value( row, "DATE" );

Some meta-information (column names mentioned above, their alignment, and the query caption) is stored in a T_QueryResults object as well:

class T_QueryResults
{
public:

    /* returns vector of column alignments, -1/0/1 values
       suggests left/center/right alignment  */
    const vector<int>& alignment() const;

    /* returns vector of headings of the columns */
    const vector<string>& heading() const;

    /* returns caption for the query results */
    const string& caption() const;

Please refer to the implementation of the CLI user application included in the libtour distribution for a working example of T_QueryResults processing.

Query reference

Description of each query consists of the following parts:

Target and options specification is used for constructing the proper T_QuerySpec object (see section Making a query object). Details related to T_QueryResults describe what to expect in the returned results (see section Processing query result).

Please note that all read-only queries are guaranteed to succeed (provided they are correct) for any stage in any state. For stages in uninitialized state the result will contain fake data (e.g. stage-local team IDs in place of real team names) or empty strings. Refer to the following subsections for details.

Read-only queries

read-only query: info

Query tournament information

TARGET

OPTIONS

RESULT

read-only query: stages

Query stage information

TARGET

OPTIONS

RESULT

read-only query: groups

Query group(s) for a stage.

TARGET

OPTIONS

RESULT

read-only query: teams

Query teams of a group of a stage.

TARGET

OPTIONS

RESULT

read-only query: schedule

Query game schedule for a stage. Filter on group ID and/or game IDs if provided.

TARGET

OPTIONS

RESULT

read-only query: standings

Query table of standings for a group within a stage.

TARGET

OPTIONS

RESULT

read-only query: sorting-conflicts

Query sorting conflicts for a group.

TARGET

OPTIONS

RESULT

read-only query: sorting-conflict-details

Query details of a sorting conflicts for a group.

TARGET

OPTIONS

RESULT

read-only query: excessive games

Query excessive game IDs for [a group within] a stage

TARGET

OPTIONS

RESULT

read-only query: groups-that-contain-a-game

Query group IDs within a stage that contain a game with given ID

TARGET

OPTIONS

RESULT

read-only query: team-fields

Query team fields.

TARGET

OPTIONS

RESULT

read-only query: standings-fields

Query standings fields for a stage.

TARGET

OPTIONS

RESULT

read-only query: game-result-fields

Query game result fields for a stage.

TARGET

OPTIONS

RESULT

read-only query: schedule-fields

Query game schedule fields for a stage.

TARGET

OPTIONS

RESULT

read-only query: date-format

Query date format used in the schedule definition.

TARGET

OPTIONS

RESULT

read-only query: winners

Query winners of the tournament. Will not throw exception if winners are not known yet.

TARGET

OPTIONS

RESULT

read-only query: home-team-position

Query value of the SCHEDULE-HOME definition (see section Game schedule definition)

TARGET

OPTIONS

RESULT

read-only query: team-filters

Query team fiters available for a stage (see section Filtered groups).

TARGET

OPTIONS

RESULT

read-only query: game-filters

Query game fiters available for a stage (see section Filtered groups).

TARGET

OPTIONS

RESULT

read-only query: filter-arguments

Query arguments for a filter and their types (see section Filtered groups).

TARGET

OPTIONS

Note that TEAM_FILTER and GAME_FILTER options are mutually exclusive.

RESULT

read-only query: max-game-points

Query maximum points a team can get in a game for a stage.

TARGET

OPTIONS

RESULT

Modifying queries

modifying query: insert-game-result

Insert or replace a game result.

TARGET

OPTIONS

modifying query: delete-game-result

Delete a game result.

TARGET

OPTIONS

modifying query: compete-stage

Set a stage complete.

TARGET

OPTIONS

modifying query: uncompete-stage

Set a stage uncomplete. This will invalidate any ready or complete following stages (see section TStage state transitions).

TARGET

OPTIONS

modifying query: resolve-sorting-conflict

Resolve a sorting conflict. The stage has to be in the "ready" state (see section TStage state transitions).

TARGET

OPTIONS

modifying query: make-filtered-group

Make a filtered group. The stage has to be in the "ready" or "complete" state (see section TStage state transitions).

TARGET

OPTIONS

Some examples of using this query can be found in See section CLI client sample session.

modifying query: delete-filtered-group

Delete a filtered group (see section Filtered groups).

TARGET

  • T_QuerySpec::DEL_GROUP

OPTIONS

  • T_QuerySpec::STAGE -- stage ID as in ID field of the stage definition (see section Stages definition)
  • T_QuerySpec::GROUP -- group ID to be deleted. Note that this group must have been created with make-filtered-group query


Go to the first, previous, next, last section, table of contents.