Set filters

Some filters are special in that they represent a set of squares in the current position. That is, applied to a particular position, one of these filters is associated with a set of squares. (Sometimes we write just "set" for "set of squares" or "square set". Sometimes we say the filter "returns" the set of squares.

Filters that are associated with square sets are called "set filters".

The most common kind of set filter is the piece designator. A piece designator, like Ra3 or Aa-h7 or .f1-3 represents the set of squares in the current position that are occupied by the piece types it denotes on the squares it denotes.

For example, suppose the current position is the starting position of chess. Then the piece designator R is associated with the set of squares a1 and h1. The piece designator [Rr] is associated with the set of squares a1, h1, a8 and h8. [Nn]h1-8 is the set of squares that have a knight on them on the h file, namely h1 and h8. The piece designator .d1-8 is the empty squares on the d file, namely d3,d4,d5, and d6. The piece designator [Q.]d1-8 would add to that set the square d1.

Not all filters are set filters. For example, check, stalemate, future, previous and relation are not set filters. The set filters are described in the following table:

name of set filterassociated set
attackthe set of squares in its second argument attacked by a piece on a square in its first argument
movethe set of destination squares of any matching move
lightsquares the set of light squares
darksquaresthe set of dark squares
piecethe set of squares to which the associated piece variable is bound making the subsequent filters true
squarethe set of squares to which the associated square variable is bound making the subsequent filters true
direction filters the squares that are the specified distance, in the specified directions, away from its argument
notif its argument is a set filter, then all squares not in the squares denoted by that argument
on the intersection of the sets denoted by its arguments
or if both its arguments are sets, then the union of the sets denoted by those arguments
piece designatorsthe squares described by the piece designator

The documentation for the filter will describe more precisely the set the filter is associated with. The filter "move" for example, is the set of destination squares of any move that occurs from the current position. If White's first move was 1.e4, then if the current position is the initial position, move from any is the set e4.

The significance of this is that many filters have arguments that are sets. For example, the attack filter is associated with the set of squares in its second argument's set attacked by a piece in its first argument. Thus,

attack (k .)
is the set of empty squares attacked by the black King, that is, the empty squares in the King's field. Therefore
attack (A attack (k .))
is the set of empty squares in the Black King's field that are attacked by a white piece. To see this, note that the first "attack" filter has two arguments:
  1. A
  2. attack (k .)
The first argument A is the white pieces (technically, the squares in the current position on which a white piece lies). The second argument, attack (k .), we have just seen represents the empty squares in the Black King's field.

combining square sets

An or filter is a square set if its two arguments are. Thus,
  R or na3
is the set of squares in the current position on which lie either a white Rook or a black knight on a3. but
R or check
is not a square set. If you try and use it as one, like
attack (R or check K)
an error will result. But
attack (R or na3 K)
would be legal. It would be associated with the square on which the K lies exactly if the K is attacked with by a White R or by a black knight on a3.

Using sets as filters

If a filter is a set-filter, then it matches a position exactly when the set associated with the filter for that position is nonempty. This agrees with how we think of things generally. For example, the filter R matches a position if the position has a white rook in it; which is exactly when the set of squares on which a white rook lies is nonempty.

Filters with a range are never sets

Some filters are sets normally, but not if they take a range. For example
attack (A p)
is a filter that is true if a white piece is attacking a black pawn, and is associated with the set of squares on which an attacked black pawn lies. But
  attack 1 (A p)
is a filter that is true if exactly one white piece is attacking exactly one black pawn. This is not a set filter.