fen supportFEN stands for Forsyth-Edwards Notation. It is a standard syntax for representing individual chess positions. CQL supports FEN via the
fenfilter 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:
_. 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/RNBQKBNRthen this represents any position with a white piece on
a8, a black piece on
b8, anything at all or an empty square on
c8and an empty square on
d8. (This position can't actually occur, it's just an example).
fenfilter consists of the keyword
fenfollowed by a FEN record in quotation marks. The
fenfilter 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 filterFEN 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
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).