Piece Designators

A piece designator is a set filter which represents the squares on which certain pieces lie in the current position. Piece designators are the foundation of CQL files: nearly every CQL file includes them. Examples of piece designators are:
Piece designator exampledenoted squares
b2square b2
Qsquares on which there is a white queen
a-h3squares on 3rd rank
[Qq]squares on which there is a white or black queen
Qa3a3, if there is a white queen on a3, otherwise no squares
[PqR]a-h2squares on the 2nd rank on which there is either a white pawn, a black queen, or a white rook
A[b-h2,d5,e-f7-8]squares in b2,c2,d2,e2,f2,g2,h2,d5,e7,f7,e8,f8 on which there is a white piece
_f1-8empty squares on the f file
Formally, a piece designator consists of a piece type designator followed by a square designator. If the piece type designator is absent, all piece types (including empty square) are denoted. If the square designator is absent, all 64 squares are denoted.

The piece type designator

A piece type designator is either a simple piece type designator or a compound piece type designator. The simple piece type designators are these:
Qwhite queen
qblack queen
Bwhite bishop
bblack bishop
Rwhite rook
rblack rook
Nwhite knight
nblack knight
Kwhite king
kblack king
Pwhite pawn
pblack pawn
Aany white piece
aany black piece
_empty square

A compound piece type designator is a string each of whose characters are simple piece type designators, enclosed in square brackets.

Examples of piece type designators are:

compound piece designatormeaning
[Ak]Any white piece or the black king
[KQRBNPk]Any white piece or the black king
[K_]white king or empty square
[Aa_]any piece or empty square

The square designator

A square designator is a simple square designator or a compound square designator. A simple square designator is a file designator followed by a rank designator (without white space between them). A file designator is a file name optionally followed by a hyphen and a file name. A file name is one of the characters a through h.

A rank designator is a number between 1 and 8, or two such numbers separated by a hyphen. Examples of simple square designators are:
simple square designator

A compound square designator is a list of simple square designators separated by commas without whitespace and enclosed in square brackets, such as:
compound square designator

Note that square brackets [] are used to enclose piece types in a compound piece type designator and to enclose squares in a compound square designator. A simple square designator denotes the squares on the chessboard that it names in the obvious way.

A compound square designator denotes the union of the squares denoted by the simple piece designators that it contains. For example, [a1,h1,a8,h8] denotes the corners of the board. [a1-8,a-h1,a-h8,h1-8] denotes the edges of the board.

Note: compound square designators are rarely used in CQL 6. It is usually clearer to use the | symbol to denote union of the sets of squares.

Thus, instead of [a1,h1,a8,h8], you can use


This is a compound filter filter denoting the set containing the four indicated squares.

Piece designators denote squares

In CQL, we think of piece designators as denoting sets of squares in the current position.

  • A simple piecetype designator denotes the square on which the a piece (or empty square) of the kind it describes lie.
  • A compound piecetype designator denotes the union of the squares denoted by its constituent simple piecetype designators.
A piece designator denotes the intersection of the squares denoted by its constituent piecetype designator and its square designator.

For example, if the current position is the start position of a chess game, then the the piece designators in the left column below denote the sets of square in the right column:

piece designatorsquares denoted in start position
R the two squares [a1,h1]
[Rr] the four corner squares
Ra1 the square a1
Ra2 the empty set of squares.
[Pp]d-e1-8 the four squares [d2,e2,d7,e7]
_ the squares [a-h3-6]
[nb] the squares [b-c8,f-g8]