Tour of the filters

This web page is an overview of the filters by functionality:

Logical operations

Filters can be manipulated logically: and, or, not, and the predefined true, false.

Set-theoretic operations

Sets of squares can be manipulated with standard set theoretic operations: &, |, ~, in. They can be compared for equality and inequality with == and !=. They can be counted with #. The set of all 64 squares is .; therefore, the empty set is ~. .

Numeric operations

Numeric filters, which includes numbers, can be manipulated using basic arithmetic and relational functions: +, -, *, /, % , <, <=, ==, >=, >, and !=.

In addition to these fundamental numeric operations, CQL supports a few specialized numeric functions max, min, sqrt, and abs.

Static positional features

CQL supports a number of filters to search for patterns of squares and pieces in a specific position. These filters only consider the arrangement of pieces or squares: they do not consider side-to-move, next move, or any other dynamic features of a position.

Such filters include:

piecedesignators. These include standard chess piece types: R, r, N, n, B, b, Q, q, K, k, P, p; as well as the empty square _, any white piece A, any black piece a, and any square . . Piece designators also include square names like a3 or b5 and sets of squares or pieces, like h1-8, [Aa]a-b2-7, _f4.
attackedby and attacks
Geometric filters: between, pin, ray, xray
check, mate, and stalemate
pawn structure filters: connectedpawns, doubledpawns, isolatedpawns, passedpawns
dark and light
direction filters: up, down, left, right, northeast, northwest, southeast, southwest, vertical, horizontal, orthogonal, diagonal, anydirection
fen
power
The contents or location of individual squares can be examined with rank, file, makesquare, type, colortype and pieceid.
move legality, including en-passant and castling legality, can be tested with move legal.

Game tree filters

CQL has a number of filters for navigating and searching in the game tree itself.

Basic information about the location of the currentposition can be obtained with ply, movenumber, depth, initial, terminal, mainline, variation, and virtualmainline.

The relationship between two positions in the game tree can be found using child, parent, ancestor, descendant and distance. You can get to a specific position using position (together with positionid).

To find a position with specific characteristics, use find. To find specific sequences of positions, such as consecutive checks, use line. Information about moves in a position can be found by using move.

Comparing positions

To find pairs of positions with a specified relationship, use echo. Use the positional intersection to compare the contents of two positions. Use the : filter to change the current position, which is typically used with echo to compare two positions.

The lca filter is used to find the "latest common ancestor" of two position, which is the point where the game diverged paths between them.

The consecutivemoves filter can compare the moves from the lca to two different positions and determine the longest consecutive sequence they share.

creating variables

Variables can be assigned with = and modified using operator assignments +=, -=, *=, /= and %=. When preceded by persistent, these assignments define a persistent variable.

Set variables can be defined using the square filter. Piece variables are defined using the piece filter .

Programming

Filters can be grouped and executed by enclosing them in {..}. Conditionalization can be accomplished using if/then/else. CQL also has primitive function definition and loop constructs features.

Metadata

Game Metadata can be accessed using elo, event, gamenumber, player, result, site and year. Each of these filters has associated command line options as well: -elo, -event, -gamenumber, -player (together with -white and -black), -result, -site and -year.

Presentation

Comments can be added to the output PGN file using comment. The comment field of a specific move can be accessed using the the hascomment filter.

Messages can be output while CQL is executing using message; this is useful for debugging. The order of the output games can be changed using sort .