fen support

FEN stands for Forsyth-Edwards Notation. It is a standard syntax for representing individual chess positions. CQL supports FEN via the fen filter inside a CQL file and as a command line argument.

A FEN record is a sequence of fields separated by spaces. Each field is just a sequence of alphanumeric characters.

For example the FEN record representing the start position is

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

CQL actually supports its own "extended" version of FEN in which the piece names in the first record (which agree with CQL's convention for piece naming) can be augmented by using any of the single-character piece designators: A, a, . or _. These have the obvious meanings. For example, if we replace the first four characters of the FEN record for the initial position above to get:

Aa._kbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

then this represents any position with a white piece on a8, a black piece on b8, anything at all or an empty square on c8 and an empty square on d8. (This position can't actually occur, it's just an example).

fen filter

The fen filter consists of the keyword fen followed by a FEN record in quotation marks. The fen filter matches the current position if the board position (the placement of pieces and empty squares) in the current position is identical to the board position of specified by the first field of the FEN record.

Thus, to find games with the board position discussed above, just use

      fen "Aa._kbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"

Note how we left off the last five fields of the FEN record here, although this is optional.

Uses of the FEN filter

FEN is supported by most chess GUIs. Sometimes it is quicker to simply copy the position to a FEN in the GUI, then paste that FEN into CQL, rather than specifying the pieces individually. Of course, if you care about side to move and castling or en passant rights, you would have to specify those separately. (Side to move can be specified using wtm and btm . You can test for castling or en passant rights by move legal castle and move legal enpassant. However, CQL move legal disregards any FEN information regarding prior moves pertaining to castling or en passant rights in its assessment of the legality of castling or en passant. (This is because in our experience such information is frequently incorrect or inadvertently entered).

On the command line, you can specify a FEN using the --fen keyword directly, which lets you quickly search for a position without constructing a new CQL file. Thus,

      cql -input foo.pgn -fen "Aa._kbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"

would match games with the specified position

The fen filter can be flipped and rotated, but not shifted (if an attempt to shift a fen filter is made, CQL thinks the empty squares need to be shifted too, so nothing matches since some empty squares wind up off the board).