CQL Syntax

A CQL file has the following generic structure:

(match
 :pgn input_filename
 :output output_filename
   (position ... )
   (position ... )
   (position ... )
 ...
)

In this example, the "..." represent various keywords and commands to be defined below.

For example, here is a simple CQL file to find quadrupled pawns:

(match
  :pgn heijden.pgn
  :output out.pgn
  (position
	:piececount P[b2-7] 4
	:shifthorizontal
	:flipcolor
	)
  )

This will read all the games from the file heijden.pgn and will write a PGN file named out.pgn that contains the games in heijden.pgn that have a position with quadrupled pawns.

In order to understand the format of a @CQL file, some basic syntactic terminology will be defined.

A list is a finite sequence of items, separated by whitespace, and enclosed in parentheses.

Each item is either a string of characters without whitespace or another list.

For example

(position :shifthorizontal :flipcolor)

is a list whose three elements are the strings "position", ":shifthorizontal", and ":flipcolor" .

Similarly, the list beginning "(match" above has six elements, the last of which is itself a list containing six elements whose first element is "position" and whose last element is ":flipcolor".

A keyword is a string beginning with ":". For example, the match list above has keywords :pgn and :output .

A keyword parameter is a list or string immediately following a keyword that accepts a keyword parameter.

Some keywords accept multiple parameters, one after the other.

Example of keyword parameter

In the list

(match
  :pgn heijden.pgn
  :output out.pgn
  (position
	:piececount P[b2-7] 4
	:shifthorizontal
	:flipcolor
	)
  )

:pgn has keyword parameter heijden.pgn, :output has keyword parameter out.pgn, and :piececount has keyword parameters P[b2-7] and 4.

The other keywords :shifthorizontal and :flipcolor do not take keyword parameters.

A list whose first element is "match" is called a match list and defines a match filter.

A list whose first element is "position" is called a position list and defines a position filter.

Overall functioning of CQL

CQL is invoked on a CQL file which itself must contain exactly one match list.

This match list has a :pgn keyword which defines the PGN file that has the games (or studies) to be searched.

When CQL is started up, it reads the CQL file given to it on the command line and parses the match list.

It then opens the PGN file specifed by the :pgn keyword.

It successively reads each game in the PGN file. After it reads a game, it applies the match filter to that game.

If the match filter matches the game, the game is printed to the pgn file defined by the :out keyword.

If the match filter does not match the game, then CQL ignores the game and goes onto the next game.

To determine whether a match filter matches a game, CQL acts as follows. It plays through each move in the game, optionally descending as well into the variations.

Each time a position is reached, each of the position filters defined in the match filter is applied to that position.

Example

In a 40 move game in which white makes the first move and black the last move, if there are no variations then CQL will examine exactly 80 positions in the game.

If each of the position filters in the match filter match some position in the game, then the match filter is said to match the game.

The simplest position filter is defined by the simplest position list:

(position)

This position filter matches every position. Hence, the following CQL script simply copies each game from its :pgn input to its :output file:

(match 
   :pgn heijden.pgn
   :output out.pgn
   (position)
)

Comments in a CQL file

Any characters following a semicolon are ignored in a CQL file.

Example of comments

The following CQL file is exactly the same as the one above:

; A CQL file that copies input to output
(match 
   :pgn heijden.pgn ; the PGN file to be copies
   :output out.pgn  ; where to write it
   (position)        ;  a position filter matching anything
)

Piece designators

A piece designator is a string that denotes a set of pieces, each of which can be on a set of squares.

A piece designator comprises a piecetype designator followed by a square designator.

The piecetype designator denotes a set of pieces and the square designator denotes a set of squares.

The set of pieces may include the "empty square piece" which denotes an empty square.

A piece designator matches a position if there is a square in the set of squares denoted by that piece designator which contains a piece in the set of piecetypes denoted by the piece designator.

Examples of piece designators

The piece designator Ra2 denotes a white rook on a2. The piecetype designator is R and the square designator is a2. It will match any position with a white Rook on a2.

The piece designator bc1 denotes a black bishop on c1. The piecetype designator is b and the square designator is c1. It will match any position with a black Bishop on c1.

The piece designator [Rb]d1 denotes either a white rook or a black bishop on d1.

The piecetype designator is [Rb] and the square designator is d1 . It will match any position that has either a white rook or a black bishop on d1.

The piece designator [Qr][d1,h3] denotes either a white queen or a black rook on either d1 or h3.

The piecetype designator is [QR] and the square designator is [d1,h3] .

It will match any position that has either a white queen or a black rook on either d1 or h3. (Of course, the position can also have a white queen or black rook on both d1 and h3).

Allowed piecetype designators

These are the allowed piecetype designators:

Standard piecetype designators

K white king
k black king
N white knight
n black knight
B white bishop
b black bishop
P white pawn
p black pawn
R white rook
r black rook
Q white queen
q black queen

 

Additional piecetype designators

. empty square
A any white piece
a any black piece
M white major piece
m black major piece
I white minor piece
i black minor piece
U any piece at all
? any piece or an empty square

 

Tagging piecetype designators

Anywhere a piecetype designator may occur, a tag name preceded by a '$' may occur.

This piecetype represents the exact piece represented by the named tag.

For more information, see the section on tagging.

Square designators

A square designator defines a set of squares.

An empty square designator denotes all 64 squares of the board.

Example

The piece designator R has an empty square designator. Hence, this piece designator denotes a white rook anywhere on the board.

A simple square designator comprises two characters, the first of which is a file, and the second a rank, in the usual chess notation.

If the file character is '?' then files a through h are designated. If the rank character is '?' then ranks 1 through 8 are designated.

Example

The piece designator bb3 has a simple square designator denoting the square b3, and denotes a black bishop on b3.

Compound square designators

A compound square designator can denote more than one square.

One type of compound square designator comprises a file designator followed by a rank designator.

A file designator comprises either the name of a file or the names of two files separated by hyphens.

A rank designator comprises either the name of a rank or the name of two ranks separated by hyphens.

A three-character file designator denotes all the files inclusive between the files designated by its first and last characters.

A three-character rank designator denotes all the ranks inclusive between the ranks designated by its first and last characters.

A compound square designator can also comprise a sequence of square designators separated by commas.

The set of squares so represented is the union of the sets of squares represented by each of the constituent square designators.

Any compound square designator not contained in brackets must be contained in brackets.

Examples of compound square designators

[a-c1] denotes the three squares a1, b1, and c1.

[b3-5] denotes the squares b3, b4, and b5.

[f-h6-8] denotes the squares f6, f7, f8, g6, g7, g8, h6, h7, and h8.

[a1,c4] denotes the squares a1 and c4 [a-h1-2,a8,h8] denotes the first two ranks plus a8 and h8.

[] denotes no squares at all.

This is very different from the empty square designator, which designates all squares.

Examples of piece designators

Ia1 denotes a white minor piece on a1. It will match any position with a white bishop or white knight on a1.

R[a-h1-2] will match any position with a white rook on the first two ranks.

[Ar][a-h1-2,a8,h8] will match any position that has a white piece or a black rook on the first two ranks or the corners.

[RBNQP][a1,h1,a8,h8] will match any position with a white non-king piece at the corners.

B[] denotes a white bishop on an empty set of squares. This can never match any position of course.

Transforms of piece designators

Certain transforms are defined on piece designators.

A diagonal flip transform, applied to a piece designator, reflects each square in its square set about the main diagonal a1 to h8.

For example, the diagonal flip of Ra8 is Rh1 . The diagonal flip of [Aa][a-h1-2,f6,h7] is [Aa][a-b1-8,f6,g8].

A off-diagonal flip transform applied to a piece designator reflects each square in its square set about the a8 to h1 diagonal.

For example, the off-diagonal flip of Ra8 is Ra8.

The off-diagonal flip of [Pp][a1-8], denoting a pawn on the a file, is [Pp][a-h8], denoting a pawn on the eight rank.

A vertical flip transform applied to a piece designator reflects each square in its square set about the vertical bisector of the board.

For example, the vertical flip of Uf6 , denoting a piece on f6, is Uc6.

A horizontal flip transform applied to a piece designator reflects each square in its square set about the horizontal bisector of the board.

For example, the horizontal flip of Uf6 is Uf3.

A dihedral transformation of a piece designator is either a flip transformation or a rotation by 90 degrees of the chessboard followed by a flip transformation or the identity transformation.

There are 8 distinct dihedral transformations of the board.

For example, the results of applying the 8 dihedral transformations to the piece designator Qc2 is the 8 piece designators Qc2, Qb3, Qf2, Qg3, Qf7, Qg6, Qb6, and Qc7.

A unit right shift transformation, applied to a piece designator, shifts each square in its square set over to the right one square.

If a square is already at the right edge of the board, it is removed from the square set. If a square is at the left edge of the board, it is also added to the new square set.

For example, the unit right shift transformation of Qd4 is Qe4. The unit right shift transformation of Q[c2,h2] is Qd2 .

The unit right shift transformation of Q[a2,c2,h2] is Q[a2,b2,d2].

The definitions of unit left shift transformation, unit up shift transformation and unit down transformation are similar to that of unit right shift transformation, with of course the location of the appropriate board edges altering mutatis mutandis.

A right transformation is a composition of zero or more unit right transformations. For example, the right transformation comprising three successive unit right transformations applied to Qa4 is Q[a4,b4,c4,d4],

since squares on the left edge of the board are always included in the new set. The result of applying this right transformation to Qd4 is Qg4 .

Similar definitions apply for left, up, and down transformation.

A horizontal shift transformation is either a left or a right transformation. A vertical shift transformation is either a down or an up transformation.

A shift transformation is a transformation that can be written as 0 or more horizontal shift transformations followed by 0 or more vertical shift transformations.

There is exactly one shift transformation that sends a given square to another given square. One possible shift transformation of Q[b3,c4] is Q[d4,e5].

A color flip transformation of a piece designator switches the colors of each piecetype in the piece set of the piece designator, and then applies a horizontal flip to the piece designator.

For example, the color flip transformation applied to [Rbp][a2,c2], either a white rook, a black bishop, or a black pawn on either c2 or a2, is [rBP][a7,c7] .

Range specifiers

Many keyword options are followed by optional range specifiers.

A range specifier consists of either a single integer or two integers separated by whitespace.

If a range specifier has one integer, it denotes that integer. Otherwise it denotes all the integers between its first and second integers inclusive.

Range specifier example

The match list can have a :year keyword denoting the range of years in which the game in question must lie in order for a match to occur.

:year 1934

denotes the year 1934. 1934 is the range specifier.

:year 1934 2000

denotes the years between 1934 and 2000 inclusive. The range specifier is

1934 2000