index Back to help overviewhome Back to home page

CQL - 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 a2 denotes a white rook on a2. The piecetype designator is and the square designator is a2. It will match any position with a white rook on a2.

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

The piece designator []d1 denotes either a white rook or a black bishop on d1. The piecetype designator is [] 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 [][d1,h3] denotes either a white queen or a black rook on either d1 or h3. The piecetype designator is [] 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

white king
black king
white queen
black queen
white rook
black rook
white bishop
black bishop
white knight
black knight
white pawn
black pawn

Additional piecetype designators

. empty square
any white piece
any black piece
white major piece
black major piece
white minor piece
black minor piece
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.