A brief overview of a CQL file

A CQL file has the word cql followed by a parentheses enclosed list of arguments, followed by filters. For example, here is a CQL file to find games where Black is in a pure mate: each empty square in the King's field is only attacked once:

      cql (input heijden.pgn)
       btm mate
       square all $empty in attack (k _)
        attack 1 (A $empty)

CQL first reads the input file from the input parameter. Then CQL reads each game in the file heijden.pgn. Next, CQL plays through each position in each game. Each time CQL reads a position, CQL checks whether each of the so-called filters is true of that position.

In this case there are three filters: btm, mate, and

	square all $empty in attack (k _)
	 attack 1 (A $empty)

In this case, btm will be true if the position is black to move; mate will be true if the position is mate; and the square filter checks that every empty square that is attacked by the Black king is attacked exactly once by a White piece.

If all these filters are true for a position, then CQL outputs the game (with some comments) to the output file.

If the CQL file is in "mate.cql" then the output file will be in "mate-out.pgn".

Basic syntax

A CQL file is mostly a sequence of filters separated by whitespace and punctuation.

Everything after a semicolon on a line in a CQL file is ignored as a comment.

moving on

CQL has many other options and features but the main idea is the same: read the cql header to get parameters. Match each filter in the body of the CQL file against each position in each game in the input file. When a match occurs, output the results.