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 example	denoted squares
`b2`	square b2
`Q`	squares on which there is a white queen
`Qu`	squares on which there is a white queen
`a-h3`	squares on 3rd rank
`[Qq]`	squares on which there is a white or black queen
`♕♛`	squares on which there is a white or black queen
`♕a3`	a3, if there is a white queen on a3, otherwise no squares
`[PqR]a-h2`	squares on the 2nd rank on which there is either a white pawn, a black queen, or a white rook
`♙♛♖a-h2`	squares 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
`△[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-8`	empty squares on the f file
`□f1-8`	empty 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 an ASCII simple piece type designator, a Unicode simple unicode piece type designator, or a compound piece type designator. The ASCII simple piece type designators are these:

designator	meaning
`Q`	white queen
`q`	black queen
`B`	white bishop
`b`	black bishop
`R`	white rook
`r`	black rook
`N`	white knight
`n`	black knight
`K`	white king
`k`	black king
`P`	white pawn
`p`	black pawn
`A`	any white piece
`a`	any black piece
`_`	empty square

A unicode simple Unicode piece type designator is one of

	♕ ♔ ♗ ♘ ♖ ♙
	♛ ♚ ♝ ♞ ♜ ♟
	△ ▲ □
        ◭

These mean the same thing as, respectively,

	QKBNRP
	qkbnrp
	A a _
	[Aa]

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 designator meaning

[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

If all the characters in a compound piece designator are Unicode, the surrounding brackets may be omitted:

unicode compound piece designator meaning

△♚ Any white piece or the black king

♔♕♖♗♘♙♚ Any white piece or the black king

♔□ white king or empty square

◭□ 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

d4

d4-5

a-h1-8

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

[a1,h1,a8,h8]

[a1-8,a-h1,a-h8,h1-8]

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

    {a1|h1|a8|h8}

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