The GameList class is the main interface to the libkombilo functionality. More...

#include <search.h>

Public Member Functions
	GameList (const char DBNAME, std::string ORDERBY="", std::string FORMAT="", ProcessOptions p_options=0, int BOARDSIZE=19, int cache=100) throw (DBError)

void	export_tags (string tag_db_name, vector< int > which_tags)

void	import_tags (string tag_db_name)

void	reset ()
	Reset gane list so that all games in the database are in currentList.

void	resetFormat (std::string ORDERBY="", std::string FORMAT="")
	Change sort criterion and format string.

int	size ()
	Number of games in currentList.

int	size_all ()
	Number of games in all.

std::string	get_resultsStr (unsigned int i)

std::string	resultsStr (GameListEntry *gle)

int	find_by_ID (int ID)

Processing SGF files
To "set up" the processing, you call `GameList::start_processing()`; (or GameList::start_processing(0) to disable processing of variations). Then, for each game you want to add to the database, call `GameList::process(sgf, path, fn, DBTREE, flags);` Finally, to write everything to the database, call `finalize_processing`.
int	process (const char sgf, const char path, const char fn, std::vector< GameList > glists, const char *DBTREE=0, int flags=0) throw (SGFError,DBError)

int	process_results (unsigned int i=0)

void	start_processing (int PROCESSVARIATIONS=-1) throw (DBError)

void	finalize_processing () throw (DBError)

Pattern search
void	search (Pattern &pattern, SearchOptions *options=0) throw (DBError)

char	lookupLabel (char x, char y)

void	setLabel (char x, char y, char label)

Continuation	lookupContinuation (char x, char y)

int	numHits ()
	Number of hits in most recent pattern search.

Signature search
void	sigsearch (char *sig) throw (DBError)

vector< int >	sigsearchNC (char *sig) throw (DBError)

std::string	getSignature (int i) throw (DBError)

game info search
void	gisearch (const char *sql, int complete=0) throw (DBError)

vector< int > *	gisearchNC (const char *sql, int complete=0) throw (DBError)

Tagging games
It is be possible to have (default and user-defined) categories (or tags). Default categories correspond to properties which can be detected automatically when the game is processed; for instance whether it is a handicap game, or whether the players are professionals (i.e. have a 'p' in their rank). User-defined tags are arbitrary (identified by an integer `handle`); the user interface will have to provide a suitable way for assigning such tags.
void	tagsearch (int tag) throw (DBError)
	Search for all games tagged with the given tag.

void	tagsearchSQL (char *query) throw (DBError)

void	setTag (int tag, int start=0, int end=0) throw (DBError)
	Tag all games in range `start <= i < end`. (Details below.) More...

void	setTagID (int tag, int i) throw (DBError)
	Tag the game with `ID` equal to `i` with tag `tag`.

vector< int >	getTagsID (int i, int tag=0) throw (DBError)

void	deleteTag (int tag, int i=-1) throw (DBError)
	Remove `tag` from game with `ID` `i`, or from all games in the list (if `i` is -1, the default!).

std::vector< int >	getTags (unsigned int i, int tag=0) throw (DBError)

snapshot, restore
int	snapshot () throw (DBError)

void	restore (int handle, bool del=false) throw (DBError)

void	delete_snapshot (int handle) throw (DBError)

void	delete_all_snapshots () throw (DBError)


std::string	get_gameInfoStr (unsigned int i)
	Retrieve information about games in currentList.

pair< int, int >	get_currentList_entry (unsigned int i)

std::string	currentEntryAsString (int i)

std::vector< std::string >	currentEntriesAsStrings (int start=0, int end=0)

std::string	getSGF (int i) throw (DBError)

std::string	getCurrentProperty (int i, std::string tag) throw (DBError)

List of all players
int	plSize ()

std::string	plEntry (int i)

Data Fields
char *	dbname

std::string	orderby

std::string	format1

std::string	format2

int	numColumns

int	processVariations

int	boardsize

std::vector< algo_p >	algo_ps

std::vector< GameListEntry * > *	all

int	current

sqlite3 *	db

char *	labels

vector< Continuation * >	continuations

int	num_hits

int	num_switched

int	Bwins
	number of hits in previous search where B wins (can exceed number of games if there are multiple hits per game)

int	BwinsG
	number of games in currentList where B wins

int	BwinsAll
	number of B wins in all games of the gamelist (independent of currentList)

int	Wwins
	number of hits in previous search where W wins (can exceed number of games if there are multiple hits per game)

int	WwinsG
	number of games in currentList where W wins

int	WwinsAll
	number of B wins in all games of the gamelist (independent of currentList)

Pattern *	mrs_pattern
	most recent search pattern

SearchOptions *	searchOptions

vector< int >	dates_all
	a vector which counts, for each month between January 1600 and December 2020, the number of games in the all list

vector< int >	dates_all_per_year
	a vector which counts, for each year between 1600 and 2020, the number of games in the all list

vector< int >	dates_current
	a vector which counts, for each month between January 1600 and December 2020, the number of games in the current list

Friends
class	Algo_finalpos

class	Algo_movelist

class	Algo_hash_full

class	Algo_hash

class	Algo_hash_corner

int	gis_callback (void gl, int argc, char argv, char *azColName)

int	gis_callbackNC (void pair_gl_CL, int argc, char argv, char *azColName)

Detailed Description

The GameList class is the main interface to the libkombilo functionality.

The GameList class is the most important class in libkombilo. We start with a rough description of the basic functionality. A GameList instance is the main interface to operate on a collection of SGF files, and to do all kinds of searches: pattern search, search for game information (such as players, result, etc.), and others. To construct a GameList, you pass it a file name which will be used to contain the main database, and possibly further options. To add SGF files to the database, you need to GameList::process them. Doing a search produces a list of games satisfying the given search criteria, which we refer to the list of games "currently in the list". Unless you GameList::reset the list, every search is applied only to the games currently in the list. In other words, subsequent searches are automatically AND-combined.

Constructor & Destructor Documentation

GameList::GameList	(	const char *	DBNAME,
		std::string	ORDERBY = `""`,
		std::string	FORMAT = `""`,
		ProcessOptions *	p_options = `0`,
		int	BOARDSIZE = `19`,
		int	cache = `100`
	)
throw	(	DBError
	)

Parameters

DBNAME A file name, such as /home/ug/go/kombilo1.db. This file will contain the sqlite3 database with information about all games in the database.

Further data will be stored in files where the file name is varied by exchanging the final letter of the specified DBNAME, e.g. /home/ug/go/kombilo1.da, /home/ug/go/kombilo1.dd.

Bug:: Possibly problems might arise if the file name contains spaces.

Parameters

ORDERBY ORDERBY is a string which determines how the entries of the game list are ordered; its value can be any column name of the games database, for instance "PW" or "PB" (sort by name of black or white player), or "DT" or "date".

If orderby is the empty string, or equal to "ID", the list is sorted by ID, i.e. in the order in which the games were inserted into the database. This is the fastest option, so it pays off to insert all your games into the database in the order you usually want to work with.

You can use several sort criteria by giving a comma-separated list of column names, e.g. "PW,PB,DATE". The ID will always be the final sort criterion which determines the order in case all other values are equal.

You can sort the items in descending order by adding "desc" to the corresponding criterion, for instance you could write "DATE DESC, PW, PB". (In fact, the specified string is simply appended to all sql select commands, so one could in theory imagine doing more fancy things in this way.)

Parameters

FORMAT This string controls the look of entries in the GameList (e.g. when retrieved using currentEntryAsString). The FORMAT string is a template for the game information string stored for the entries of the game list. It contains place holders of the form [[column name]] , where 'column name', obviously, is the name of a column of the database.

Currently, the columns in the database are

id the ID within the database (a positive integer)
path, filename path and file name of the corresponding sgf file
filename. the file name without the suffix '.sgf' or '.mgt'
pos the position of the game inside the sgf file (=0 unless the sgf file is a collection of several games
date date in format YYYY-MM-DD; see below
BR, CA, DT, EV, HA, KM, PB, PC, PW, RE, RO, RU, SZ, US, WR SGF properties from the root node of the game. The most important ones are PW, PB (white, black player), RE (result), DT (date). Only tags specified via ProcessOptions at creation time of the database can be used.
winner not a database column, but available as a shortcut for the first letter of the re column, if this first letter is B (black win), W (white win) or J (jigo). Otherwise winner will be set equal to '-'

The column names are case-sensitive. You must not use [[ at other places than indicating column names as described above. If the format string is empty, the example given below will be used.

Example:

[[PW]] - [[PB]] ([[WINNER]]), [[DT]],

With this format string, a typical entry in the game list would be

Cho Chikun - O Rissei (W), 2005-04-20,21,

If the database contains hits from a pattern search, then currentEntriesAsStrings() returns the concatenation of the game info string as above and the list of hits.

The difference between DT and date

DT is the date as given in the SGF file, date is always in format YYYY-MM-DD Upon processing the SGF file, the program tries to extract date from the DT entry. For instance the entry in the sgf file might be "Published on 1960-01-01", in which case date will be "1960-01-01". It usually makes more sense to sort the list by date, but maybe you want to use DT in the format string.

Parameters

p_options	p_options will be copied by GameList, so the caller has to free the pointer; only used for newly built GameList
BOARDSIZE	The board size. Note that the board size is fixed for all games in the GameList. If you need different board sizes, you have to work with several instances of GameList.
cache	Cache size for the sqlite3 database. Usually does not have a big impact.

Member Function Documentation

vector< int > GameList::getTags	(	unsigned int	i,
		int	tag = `0`
	)
throw	(	DBError
	)

If tag is 0, return vector with all tags attached to i-th game of currentList. If tag is not 0, return vector with single element tag, or empty vector, depending on whether tag is attached to game i.

Here i refers to the index of the game in the list of games "currently in the game list".

vector< int > GameList::getTagsID	(	int	i,
		int	tag = `0`
	)
throw	(	DBError
	)

If tag is 0, return vector with all tags attached to game i. If tag is not 0, return vector with single element tag, or empty vector, depending on whether tag is attached to game i.

Here i refers to the row ID of the game in the sqlite database.

void GameList::gisearch	(	const char *	sql,
		int	complete = `0`
	)
throw	(	DBError
	)

Search for given sql query. The string sql is inserted into the following query: select id from GAMES where s " order by id;" % sql (putting the gamelist in the right order is dealt with separately) If complete==1, then sql is passed as an sql query without any changes (i.e. you must put in the "select ..." stuff in yourself).

vector< int > * GameList::gisearchNC	(	const char *	sql,
		int	complete = `0`
	)
throw	(	DBError
	)

Execute the given sql query (inserted in select id from GAMES where s " order by id;" % sql without changing the GameList. Returns a vector of int's containing all indices (in currentList) of games that match the query. If complete==1, then sql is passed as an sql query without any changes (i.e. you must put in the "select ..." stuff in yourself).

int GameList::process	(	const char *	sgf,
		const char *	path,
		const char *	fn,
		std::vector< GameList * >	glists,
		const char *	DBTREE = `0`,
		int	flags = `0`
	)
throw	(	SGFError,
		DBError
	)

sgf, path and fn are strings (that is char*'s) which contain the content of the SGF file to be processed, the path where the file lives and the file name. (You can pass empty strings as path and fn if you do not want to store this information in the database.) DBTREE is a string which is stored in the database and can be accessed via a gisearch - this can be used to organize your database in a tree structure.

You can use the following flags to determine the behavior for the game to be processed:

CHECK_FOR_DUPLICATES
CHECK_FOR_DUPLICATES_STRICT
OMIT_DUPLICATES
OMIT_GAMES_WITH_SGF_ERRORS

Combine the flags using bitwise OR.

Return value

0: An SGF error occurred when parsing the "tree structure" (i.e. before parsing the individual nodes), database was not changed.
a positive integer n: n games were processed. Use process_results to access the individual results

int GameList::process_results ( unsigned int i = 0 )

For the processed games (0 <= i < n), use process_results(i). Its return value is a combination of the following flags:

UNACCEPTABLE_BOARDSIZE (database not changed)
SGF_ERROR An SGF error occurred when playing through the game (and the rest of the concerning variation was not used). Depending on OMIT_GAMES_WITH_SGF_ERRORS, everything before this node (and other variations, if any) was inserted, or the database was not changed.
IS_DUPLICATE
NOT_INSERTED_INTO_DB
INDEX_OUT_OF_RANGE

void GameList::setTag	(	int	tag,
		int	start = `0`,
		int	end = `0`
	)
throw	(	DBError
	)

Tag all games in range start <= i < end. (Details below.)

Setting end to 0 means: tag only the game with index start. start and end refer to indices in currentList, i.e. in the list of games "currently in view".

void GameList::tagsearchSQL	(	char *	query	)
throw	(	DBError
	)

The tagsearchSQL method allows specifying SQL which will simply be inserted into the following SELECT statement: select GAMES.id from GAMES where %(query)s order by GAMES.id Typically, you will build query as an AND/OR/NOT combination of snippets like exists(select * from game_tags where game_id=games.id and tag_id=%(t)s) with one or more tag_id's.

The documentation for this class was generated from the following files:

/home/ug/devel/kombilo-py-dev/kombilo/libkombilo/search.h
/home/ug/devel/kombilo-py-dev/kombilo/libkombilo/search.cpp

Public Member Functions

Data Fields

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation