Tour of the filters
This web page is an overview of the filters by functionality:- Logical Operations
- set-theoretic operations
- numeric operations
- static positional features
- game tree filters
- comparing positions
- creating variables
- metadata
- presentation
- programming
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
a3orb5and sets of squares or pieces, likeh1-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 .