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 filter	associated set
attack	the set of squares in its second argument attacked by a piece on a square in its first argument
.	all squares on the board
move	the set of destination squares of any matching move
lightsquares	the set of light squares
darksquares	the set of dark squares
piece	the set of squares to which the associated piece variable is bound making the subsequent filters true
square	the set of squares to which the associated square variable is bound making the subsequent filters true
ray	the set of squares terminating a ray described by the ray filter.
direction filters	the squares that are the specified distance, in the specified directions, away from its argument
not	if 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
_	the empty squares
piece designators	the 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 . 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.