The structure of a CQL File

A CQL file has three parts:
  1. The word cql
  2. The cql parameters: a sequence of cql parameters enclosed in parentheses
  3. The cql body: a sequence of filters
For example, here is a CQL file to find games where black is stalemated and is pinned at least twice, sorted by the number of pins: 
  cql (input heijden.pgn)
  btm
  stalemate
  sort ray 2 8 attack (A a k)
In this example, there is one cql parameter: 
  input heijden.pgn
This parameter, input heijden.pgn specifies that the games are to be read from the file heijden.pgn.

This CQL body has three filters:

  1. A btm filter, which matches a position with black to move.
  2. A stalemate filter, which matches a position that is stalemate
  3. 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 file

    CQL 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 MATCH appears 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 -out appended and the extension .pgn); or as a parameter inside the CQL file itself; or on the command line.