CQL ParametersA CQL file begins with the word
cqlfollowed by a sequence of CQL parameters enclosed in parentheses. The allowed parameters determine which games CQL matches, whether and how the output is sorted, and where the output will be printed. An example of a complicated set of parameters beginning a CQL file is in this file:
cql (input hhdbvi.pgn output out.pgn gamenumber 100 1000 variations sort matchcount 2 5 ) other filtersThis CQL file will look in
hhdbvi.pgnfor the games and write its output to
out.pgn. It will start examining the 100th game of hhdbvi.pgn and will stop after it has examined game 1000 of that file. It will look in the variations. It will only output games with between 2 and 5 matched positions. It will sort the output by the number of positions that match the filters in its body.
The allowed parameters of the CQL file are these:
||specifies the output file where CQL writes results|
||specifies the input PGN file from which CQL reads games|
||number of matched positions must lie in the range|
||Only examine games with game number in the range|
||specify result of game|
||suppress all annotations added by CQL including user comments|
||suppress automatically generated comments except for header comments|
|sort matchcount range||
||search in variations as well as in the mainline|
||set the comment output at matched position|
output filenameIf an
output filenameparameter is present, then the PGN output will be written to the file
filename, which must end in the extension
If neither an output parameter nor an output option was specified then the output will be written to the file
cqlfilename is the name of the CQL file itself without any path prefix or extension.
For example, if the name of the
.cql file is
pins.cql and if no output file is specified within the CQL script or on the command line, then
CQL will write the results to
input filenameIf an
input filenameparameter is present then the games are read from the file
filenamewhich must end in the extension
.pgn. If the command line option
-input) is specified then games will be read from filename that follows the
-icommand line option.
The filename can be enclosed in quotation marks, which is sometimes useful if it contains embedded spaces.
If all the filters in the body of the CQL filter match a position, then the body is said to match the position.
Each time its body matches a position, CQL increments the value of an
internal variable named
When CQL is finished playing through the game, CQL checks the value of
Ordinarily, whenever matchcount is greater than 0, then the game
itself is said to match the CQL form. When that happens, CQL outputs
the game, together with some annotations, to its output
file. (Recall that the output file can be specified as a CQL
parameter inside the CQL file, or as a command line argument, or if
not specified is the name of the input CQL file with
matchcount parameter is specified, however, then the game is output only if the value of the
matchcount variable lies within the
range argument (which can include
sort matchcount range
sort matchtcount rangewill select the exact same games as
matchcount range, but it will sort these games in descending order of the number of matched positions in the game.
variationsparameter is specified then CQL will search in variations as well as in the mainline. This includes not only the main search loop of CQL, but also other filters that can traverse the game tree, like move, line, find, and echo.
variations parameter is specified, we sometimes say "
variations is set." By default, CQL only searches mainline positions.