(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.
(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.
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.
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 everyposition. 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) )
; 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 )
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.
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 eithe 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).
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
. 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
An empty square designator denotes all 64 squares of the board.
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.
bb3
has a simple square designator denoting the square b3, and denotes a black bishop on b3.
Any compound square designator not contained in brackets must be contained in brackets.
[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.
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.
A diagonal flip transform, applied to a piece designator, reflects each square in its square set about the main diagonal.
For example, the diagonal flip of Ra8
is Ra1
. 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 Uc3
.
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 any number of one 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]
.
If a range specifier has one integer, it denotes that integer. Otherwise it denotes all the integers between its first and second integers inclusive.
:year
keyword denoting the range of years in which the game in question must lie in order for a match to occur.
:year 1934denotes the year 1934. 1934 is the range specifier.
:year 1934 2000denotes the years between 1934 and 2000 inclusive. The range specifier is
1934 2000