―― filter

A ―― (ASCII --) filter represents a single move that occurs in the PGN file. For explanatory purposes and in conversation the ―― filter is sometimes called a dash filter.

The basic ―― filter has this form:

    F――G

Here F is the left filter and G is the right filter. Each of these is a set filter representing a set of squares in the current position.

There must be no whitespace between the left filter and the left side of the ―― character

If either the left filter or the right filter is absent, it is taken to denote the ▦ filter representing the set of all 64 squares.

This filter matches a move from a square in F to a square in G.

For example,

    e2――e4

matches a move from e2 to e4.

    ♖――

matches any move by the white rook.

    ――♕a4

matches a move to the white queen on a4, that is to say, a capture of white queen.

    ――

matches any move

matching a move

Technically, filters in CQL match positions, not moves. But it is usually easier to think of a ―― filter as matching a move. A ―― filter matches the current position if there is some move from the current position which the ―― filter matches.

For example, the filter

    △――

would match any white-to-move position except a terminal position

matching captures: ×

The × filter (ascii: [x]) has the same syntax as the ―― filter except that the ―― symbol is replaced by the × symbol. Its effect is to restrict the allowed moves to captures:

    ♗×♟h7(check)

means that a ♗ captures the ♟h7 with check.

A × filter is considered a type of ―― filter, so when we talk about ―― filters, we always include × filters as well.

Note that the two filters below are not synonomous:

    ×
    ――◭

The × filter will match any capture. The ――△ will match any capture except for en passant. That is because the destination square of an en passant capture is the square where the capturing pawn moved to, which is empty before the move was made.

Promotions and the =T syntax

A typename designator is a either a piece designator without any square specifier or a string each of whose characters is an ASCII type designator. A typename designator denotes its constituent piece types. Color is ignored in assessing a typename designator.

If X is a typename designator, then

    F――G=X

means the same thing as F――G except that only moves that promote to a type designated by X are considered.

Note that only type (and not color) of X are considered, so that Q and q (or ♕ and ♛ mean the same thing.

    ――=♖ //promotion to rook
    ――=♖♗♘ //underpromotion
    ――="RBN" // underpromotion
    ――=♜ //promotion to rook
    ♙――d8=♕ //white promotes to ♕d8
    ♟――=△ // black promotes
    ♟×=♘ // black captures and promotes to a knight

the target of a ―― filter

The target position, or just the target, of a move is the position that results from executing that move. You can specify a series of filters that must be true in the target of a move by enclosing them in parentheses and appending these to the end of the ―― filter:

    △――(check)  //white gives check
    △――d4(check) //white checks on d4
    ♟×d1=♘(check) //black underpromotes to a knight on d1 with check
    ♘――(pin through ♖ mate) //white knight move and mates. The final position has a pinned ♖

There must be no whitespace between the left parentheses of the target filters and the right side of the rest of the ―― filter.

If there is no move that matches the specified target filters, the ―― move fails to match.

Tip: use ⊢ for complex targets

For moderately complex targets, it is best to use ⊢ rather than the target syntax. The target syntax can quickly become awkward and hard to read. When using ⊢, the target filters need not be enclosed in parentheses at all, which makes them easier to read. For example, this single ―― filter:

  ♗×h7(check
       ♚×h7(♘――g5 check))

would be much easier to read with the equivalent ⊢ filter

  ⊢
   ♗×h7 check
   ♚×h7
   ♘――g5 check

value returned by ―― filter

When a target is present, the ―― filter returns a value equal to the the value of the last specified target filter of the first matched move (moves are considered in the order of their appearance in the PGN file).

This facility is often used to get the origin or destination squares of a piece move into a variable when used with from or to. Consider this

  x=♘――(to)

Suppose from the current position, the white knight moves to d4. After that move is evaluated, the to filter has value equal to d4. That is because the to is the to square associated with the current move, which is to say, the move leading to the current position. After the filter is evaluated, x will be given the value d4.

Similarly,

  y=△――(from)

will store into the variable y the from square of the next white move, if any.

What if variations are set and we want to get all the from squares of any white piece that moves from the current position, then store this in y?

Then we have to use ∊:

  y=z∊△ z――

Similarly, the following expression has value equal to all the destination squares of any white knight in the current position:

  z∊▦ ♘――z

In many CQL files when variations are not set, you will see this idiom:

  △T= ♕♖――(from)

This idiom is used to set T to be a piece variable that holds a major piece which moves on the next move. That is because

  ♕♖――(from)

will have as value the square from which a white rook or queen moved, and when this is assigned to a piece variable, that piece variable takes on the identity of the piece on that square.

castling and enpassant

Castling is considered a move by both the moving rook and the king. Use o-o, o-o-o, and castle to specify castling in the target filters. These are ordinary filters referring to the previous move, so can be used as targets:

    △――(o-o) //white castles kingside
     ――(o-o-o) //any queenside castle
    ▲――(castle mate) //black castles and mates

Use the enpassant to specify enpassant in the target. enpassant is an ordinary filter that means the current move was enpassant, so

    ――(enpassant)

means that the next move is enpassant.

legal and pseudolegal moves

To get legal moves instead of only moves in the PGN file, use the legal filter:

    legal ――(o-o)

counting moves

Use the countmoves filter to count the number of matching moves from the current position:

    countmoves ♖―― //#♖ moves from current position

Examples

    a4――b3(check)

denotes that from the current position, there is a move of a piece from a4 to b3 resulting in check.

    ♗a4――b5(mate)

means that there is a move from a white bishop on a4 to b5 that delivers mate.

    ♗a4――♞b5(mate)

means that there is a move from a white bishop on a4 capturing a black knight on b5 that delivers mate. It is the same as

    ♗a4×♞b5(mate)

    ♕――d4(check)

means that a white queen moves to d4 and gives check.

    ――d4 mate

means that a piece moves to d4 and mates.

    ♙――="RBN"

means that white underpromotes on the next move.

Philosophy of the ―― syntax

The ―― syntax might initially seem complex and arbitrary. It is helpful to keep in mind that it was chosen to be as close to ordinary chess algebraic notation as possible. Consider a typical move in algebraic notation:

    ♕a2-a4

To transform this move into the corresponding ―― operator, we simply replace the - with ――. (We cannot just use - because that symbol is already used for subtraction).

The ♕a2 plays the role of the left filter. In the ―― notation, it can be replaced by any set filter. Likewise, the right filter can replace a4 with any filter, so we can have, say,

    ♕♖――a1-8

for a white queen or rook that moves to the a file.

The promotion notation is the same as for algebraic notation:

    ♙-a8=♖

as algebraic notation, meaning that a white pawn promotes to a rook on a8, becomes

    ♙――a8=♖

The ♖ can be replaced by any type designator.

Finally, symbols and indications after an algebraic notation move are taken as indicating something about the resulting position:

    ♙-d4+ +-

means that after the pawn moves to d4, black is in check and the position is winning for white. In CQL, we collect all these assertions and put them in parentheses (we need the parentheses to simplify parsing):

    ♙-d4(check comment "white is winning")

Thus, each of the components of a move in algebraic notation corresponds to a component of a ―― filter. When a component of the ―― filter is missing, it corresponds to all possible values

    ――d4 // any move to d4

precedence

A ―― filter has extremely low precedence. To denote a move by a piece other than the black king, use

    ~♚――

This is parsed as

    (~♚)――

To denote a move from a rook to either T or U (which can be set variables), use

    ♖♜――T∪U

―― and piece designator syntax

Thus, the relationships between algebraic notation for moves and the piece designator notation for piece locations are analogous. In each case, the CQL syntax is derived from chess algebraic notation syntax by these rules:

1. An element of chess notation is identical or very close to an element of the CQL syntax; and
2. An element of chess notation can be replaced by any meaningful CQL filter
3. A missing element of the chess notation means that all possible values are allowed.

In the case of piece designators, we apply these meta-syntactic rules as follows: Consider ♖a2. This is valid chess notation for a piece location, and so by rule (1) above, it is also valid CQL notation.

By rule (2) above, we can replace it by say ♖♗a2 or △a2-5 (a white piece on the a file, ranks 2 through 5).

By rule (3) above, if the square is missing, say ♖ in CQL, that means that all possibly squares are implied: ♖a-h1-8. If the piece is missing, a2 in CQL, that means that any piece or even an empty square can be on a2.

Similar considerations apply for the ―― filter, as we saw above. In fact, we can consider the ―― filter to be a generalization of piece designators if we want, which is one reason no spaces are allowed between the different components of a ―― filter.