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 heijden.pgn output out.pgn gamenumber 100 1000 variations sort matchcount 2 5 ) other filtersThis CQL file will look in
heijden.pgnfor the games and write its output to
out.pgn. It will start examining the 100th game of heijden.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 range|
||suppress all annotations added by CQL|
|sort matchcount range||
||search in variations as well as in the mainline|
||Current game must match the specified metadata filter|
output filenameIf an
output filenameparameter is present then the output will be written to that file, which must end in the extension ".pgn". But if a the cql executable was invoked with the --output option, then the output will be written to the filename given by that option. If neither an output parameter nor an output option was specified then the output will be written to the file cqlfilename-out.pgn, where 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, the 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 that filename.
silentDo not print any CQL-generated annotations except for those generated by a comment filter. See silent documentation for more information on this filter.
If all the filters in the body of the CQL form match, then the position 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 -out.pgn appended.).
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 rangeWhether a game is output if
sort matchcount rangeparameter is included is the same as if matchcount range were included without the prefatory
sort. However, if
sortis specified then the output games are sorted in descending order by the value of the
matchcount(that is by the number of positions matched in that game.)
variationsparameter is specified then CQL will search in variations as well as in the mainline. In this case we sometimes say "
variationsis set." By default, CQL only searches mainline positions.