The structure of a CQL FileA CQL file has three parts:
- The word
- The cql parameters: a sequence of cql parameters enclosed in parentheses
- The cql body: a sequence of filters
cql (input heijden.pgn) btm stalemate sort ray 2 8 attack (A a k)In this example, there is one cql parameter:
input heijden.pgnThis parameter,
input heijden.pgnspecifies that the games are to be read from the file heijden.pgn.
This CQL body has three filters:
- A btm filter, which matches a position with black to move.
- A stalemate filter, which matches a position that is stalemate
- A sort filter that matches a position that its argument filter matches. In this case,
its argument filter is the ray filter:
ray 2 8 attack (A a k)This ray filter matches a position in which there are between 2 and 8 pins of a black piece by a white piece.
This CQL file will output every game from heijden.pgn in which there is a black stalemate with at least two pinned black pieces. The output will be sorted by the number of pins in the stalemate.
Operation of a CQL fileCQL successively reads each game in its input PGN file. For each such game, CQL plays through each move in the game.
Every time CQL reaches a position, it sets the current position to that position. Then CQL tries to match each of its filters against that position. If all the filters in the CQL file match the position, then CQL is said to have matched the position. In this case, CQL comments the position with the word
MATCH. (Note that because PGN comments are associated to a move, not a position, the word
MATCHappears at the end of the previous move leading to the position. If the position is the initial position, the comment appears just before the first move.)
When CQL has finished trying to match all the positions in the game against its filters, then if any of the positions matched, CQL will output the game to the output file. The output file can be specified either by default (in which case its name is the name of the CQL file with
-outappended and the extension
.pgn); or as a parameter inside the CQL file itself; or on the command line.