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.
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.
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).
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:
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.
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.
Description of each query consists of the following parts:
T_QuerySpec target
T_QuerySpec options
T_QueryResults columns and their types
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.
Query tournament information
TARGET
T_QuerySpec::INFO
OPTIONS
RESULT
<tour-name>::INFO variable (see section Defining a tournament module), string type for each field
Query stage information
TARGET
T_QuerySpec::STAGE
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition), optional
RESULT
Id -- stage ID as in ID field of the stage definition
(see section Stages definition), string type
Name -- stage name as in NAME field of the stage
definition (see section Stages definition), string type
State -- stage state (see section TStage state transitions), one
of T_STATE_UNINIT, T_STATE_READY,
T_STATE_COMPLETE; string type
Query group(s) for a stage.
TARGET
T_QuerySpec::GROUP
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition), optional
RESULT
Id -- group ID as in ID field of the group definition
(see section Groups definition), string type
Name -- group name as in NAME field of the group
definition (see section Groups definition), string type
Description -- optional group description (see section Groups definition), string type
State -- group state one of T_STATE_UNINIT,
T_STATE_READY, T_STATE_COMPLETE; (see section Game results and formula), string type
Schedule -- whether the group schedule is sufficient,
bool type; it is undefined for groups with no formula
(see section Group formula definition) or for any group in an
uninitialized state
Summary -- whether the group has a formula (see section Group formula definition), bool type
Filtered -- whether the group was created by the user as a
filtered group (see section Filtered groups), bool type
Query teams of a group of a stage.
TARGET
T_QuerySpec::TEAM
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition)
RESULT
GbId -- global team ID as defined in the Scheme data
(see section Teams definition). Empty string if the stage is
uninitialized.
LCId -- stage-local team ID (see section Structure of a tournament)
TEAM-FORMAT fields (see section Teams definition), string
type EACH. If the stage is uninitialized NAME field will
contain the stage-local team ID surrounded by angle brackets, and the
rest of the TEAM-FORMAT fields will be empty.
Query game schedule for a stage. Filter on group ID and/or game IDs if provided.
TARGET
T_QuerySpec::SCHEDULE
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition)
optional
T_QuerySpec::GAME -- space-separated list of game IDs as in
ID field of the game definition (see section Game schedule definition), optional
RESULT
SCHEDULE-FORMAT fields (see section Game schedule definition),
string type for each field. If the stage is uninitialized
TEAM1 and TEAM2 fields will contain the stage-local
team ID surrounded by angle brackets
GAMERES-FIELDS fields (see section Standings and Game result fields definitions), types as
defined in GAMERES-FIELDS. Empty if game has no result
p1 -- points the first team earned, int type. Empty if
game has no result
p2 -- points the second team earned, int type. Empty if
game has no result
ro -- read-only flag, bool type
Query table of standings for a group within a stage.
TARGET
T_QuerySpec::STANDINGS
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition)
RESULT
Pos -- team position, int range type
Team -- team name as in NAME field of teams definition
(see section Teams definition), string type
STANDINGS-FIELDS fields (see section Stages definition),
int type
Query sorting conflicts for a group.
TARGET
T_QuerySpec::S_CONFLICT
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition)
RESULT
Pos -- team position, int range type
Resolved -- whether this conflict is resolved, bool type
Query details of a sorting conflicts for a group.
TARGET
T_QuerySpec::S_CONFLICT_DET
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition)
T_QuerySpec::POS_RANGE -- a string representing position range
as returned by the read-only T_QuerySpec::S_CONFLICT query
RESULT
Team -- team name, string type
Pos -- -1 if this conflict is not resolved, otherwise
0 or greater to notify the relative team position within this
conflict; int type
Query excessive game IDs for [a group within] a stage
TARGET
T_QuerySpec::EXCESSIVE_GAMES
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition), optional
RESULT
Id -- game ID as in ID field of the schedule definition
(see section Game schedule definition), string type
Query group IDs within a stage that contain a game with given ID
TARGET
T_QuerySpec::BELONGS
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GAME -- game ID as in ID field of the
schedule definition (see section Game schedule definition)
RESULT
Id -- group ID as in ID field of the group definition
(see section Groups definition), string type
Query team fields.
TARGET
T_QuerySpec::TEAM_FIELDS
OPTIONS
RESULT
Value -- names of TEAM-FORMAT fields (see section Teams definition), string type
Query standings fields for a stage.
TARGET
T_QuerySpec::STANDINGS_FIELDS
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
RESULT
Value -- names of STANDINGS-FIELDS fields
(see section Standings and Game result fields definitions), string type for
each field
Query game result fields for a stage.
TARGET
T_QuerySpec::GAME_FIELDS
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
RESULT
Value -- names of GAMERES-FIELDS fields (see section Standings and Game result fields definitions), string type
Type -- types of GAMERES-FIELDS fields (see section Standings and Game result fields definitions), string type
Query game schedule fields for a stage.
TARGET
T_QuerySpec::SCHEDULE_FIELDS
OPTIONS
RESULT
Value -- names of SCHEDULE-FORMAT fields (see section Game schedule definition), string type
Query date format used in the schedule definition.
TARGET
T_QuerySpec::DATE_FORMAT
OPTIONS
RESULT
Value -- date format as in strptime(3) C library
function (see section Game schedule definition), string type
Query winners of the tournament. Will not throw exception if winners are not known yet.
TARGET
T_QuerySpec::WINNERS
OPTIONS
RESULT
Winner -- winner names as in keys of the winners definition
(see section Winners definition), string type
Name -- team name as in NAME field of teams definition
(see section Teams definition), string type
Query value of the SCHEDULE-HOME definition (see section Game schedule definition)
TARGET
T_QuerySpec::HOME_POSITION
OPTIONS
RESULT
Value -- value for the home team position, int type
Query team fiters available for a stage (see section Filtered groups).
TARGET
T_QuerySpec::TEAM_FILTER
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
RESULT
Name -- filter name which corresponds to name of the
procedures in the TEAM-FILTERS definition (see section Filters definition), string type
Description -- documentation of the filter-making procedure,
string type
Query game fiters available for a stage (see section Filtered groups).
TARGET
T_QuerySpec::GAME_FILTER
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
RESULT
Name -- filter name which corresponds to name of the
procedures in the GAME-FILTERS definition (see section Filters definition), string type
Description -- documentation of the filter-making procedure,
string type
Query arguments for a filter and their types (see section Filtered groups).
TARGET
T_QuerySpec::FILTER_ARGS
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::TEAM_FILTER -- name of a team filter available
for this stage (see section Filters definition)
T_QuerySpec::GAME_FILTER -- name of a game filter available
for this stage (see section Filters definition)
Note that TEAM_FILTER and GAME_FILTER options are
mutually exclusive.
RESULT
Name -- description of the argument, string type
Type -- type of the argument, string type
(see section Filtered groups), string type
Query maximum points a team can get in a game for a stage.
TARGET
T_QuerySpec::MAX_POINTS
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
RESULT
Value -- maximum number of points in a game, int type;
or a uninitialized value if not defined in rules
Insert or replace a game result.
TARGET
T_QuerySpec::GAME
OPTIONS
T_QuerySpec::GAME -- game ID as in ID field of the
schedule definition (see section Game schedule definition)
T_QuerySpec::G_RESULT -- a string representing a game result;
values corresponding to GAMERES-FIELDS fields (see section Standings and Game result fields definitions) separated by spaces
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
Delete a game result.
TARGET
T_QuerySpec::UN_GAME
OPTIONS
T_QuerySpec::GAME -- game ID as in ID field of the
schedule definition (see section Game schedule definition)
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
Set a stage complete.
TARGET
T_QuerySpec::COMPLETE
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
Set a stage uncomplete. This will invalidate any ready or complete following stages (see section TStage state transitions).
TARGET
T_QuerySpec::UN_COMPLETE
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
Resolve a sorting conflict. The stage has to be in the "ready" state (see section TStage state transitions).
TARGET
T_QuerySpec::S_CONFLICT
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- group ID as in ID field of the
group definition (see section Groups definition)
T_QuerySpec::POS_RANGE -- a string representing position range
as returned by the read-only T_QuerySpec::S_CONFLICT query
T_QuerySpec::S_CONFLICT_SOL -- list of team names (in double
quotes) in the order they should appear in the table of standings, an
empty string if resolution of this sorting conflict should be reset
Make a filtered group. The stage has to be in the "ready" or "complete" state (see section TStage state transitions).
TARGET
T_QuerySpec::GROUP
OPTIONS
T_QuerySpec::STAGE -- stage ID as in ID field of the
stage definition (see section Stages definition)
T_QuerySpec::GROUP -- base group ID as in ID field of
the group definition (see section Groups definition)
T_QuerySpec::ID -- new group ID, should be unique within this
stage
T_QuerySpec::NAME -- new group name, optional
T_QuerySpec::TEAM_FILTER -- a team filter expression; a
string that contains white space delimited tokens: the first is
the filter name and the following are the arguments for the
corresponding filter-making procedure (see section Filtered groups).
T_QuerySpec::GAME_FILTER -- a game filter expression; a
string that contains white space delimited tokens: the first is
the filter name and the following are the arguments for the
corresponding filter-making procedure (see section Filtered groups).
Some examples of using this query can be found in See section CLI client sample session.
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.