Ray Filters

The ray Filter

ray [direction …] ( Set₁ Set₂ … ) ⇒ Set

The ray filter accepts zero or more directions followed by a parenthesized list of two or more Set filters. directions may be any simple or compound directions, a default of anydirection is used if no direction is provided. The result of the ray filter is the set of squares on which matching rays terminate. Matching rays are those that begin on a square in Set₁ and, moving in a prescribed direction, consecutively include a square in each successive set Set_i in the list of provided sets with only unoccupied squares being allowed to appear between successive sets.

Some examples of ray filters include:

ray (A a A a)           // Four pieces in a line of alternating color
ray diagonal (B n k)    // White bishop pinning a black knight
ray up (R [Pp] r)       // Opposing rooks on a file separated by a pawn

The following query will match any position for which there is an orthogonal ray containing two white rooks, a black queen, and a black king, in that order, without any other pieces in between, i.e. a rook battery pinning the black queen to its king:

ray orthogonal (R R q k)

Such a situation occurs in the following position:

The table below contains other examples of rays shown in the above diagram.

The filter ray(r r) would not match the position in the above diagram because of the presence of the black king between the two black rooks, only empty squares may appear between the consecutive set arguments in the ray filter.

A single ray filter may match multiple rays in which case the result will be the set of the endpoints of all matching rays. For example, ray(p p) matches rays ending on squares a7, b6, g6, a7, and h7. The filter ray right (a1 _) will also match multiple rays ending on squares b1, c1, and d1 as empty squares may appear between the squares specified by a1 and _.

The result of the ray filter represents the end of the matching rays, to obtain the beginning of matching rays simply reverse the set arguments (and possibly the direction) of the ray filter, e.g. ray orthogonal (k q R R) instead of ray orthogonal (R R q k).

The xray Filter

xray ( Set₁ … Set_n) ⇒ Set

The xray filter finds pieces along a ray such that a sliding piece in Set₁ would attack a square in Set_n if the squares between them were unoccupied. The result of the xray filter is the set of squares on which matching rays terminate. Matching rays must consecutively consist of a square in each successive set Set_i in the list of provided sets with only unoccupied squares being allowed to appear between successive sets.

The colors of the pieces involved are not significant, it is not even required that pieces reside on any of the squares except a square in Set₁.

The following query looks for a white rook that x-rays a black queen through a white knight such that the knight can move to a square not attacked by Black and simultaneously check the black king:

xray(R (move from N to ~(. attackedby a): check) q)

The second argument to the xray filter in the above query uses the speculative move filter to find moves by white knights to squares not attacked by Black that also result in check. The result of the move filter is the set of squares on which matching knights reside since the first parameter to the move filter is from.

One position matching this query is:

In the above diagram, the matching xray is shown in red (the move 1.Nd6+ wins the black queen), some other examples of xrays are shown with blue arrows.

Note that an xray filter of the form

xray (S₁ … S_n )

is functionally equivalent to:

ray orthogonal ((S₁&[RrQq]) … S_n )
| ray diagonal ((S₁&[BbQq]) … S_n )

The pin Filter

pin [from Set] [through Set] [to Set] ⇒ Set

A pin is induced from a piece P_x on square S_x through a piece P_y on square S_y to a square S_z when all of the following are true:

• P_x attacks P_y
• P_x and P_y are opposite colors
• S_z is not attacked by P_x but would be if P_y were not present on S_y
• S_z is unoccupied or is occupied by a piece of the same color as P_y

In such a case, P_y is said to be pinned to S_z by the pinning piece P_x. Note that only sliding pieces (bishops, rooks, and queens) can induce a pin. P_x attacks P_y if P_y would be in check by P_x if P_y were a king. In particular, P_x attacks P_y even if P_x is itself pinned. It can be inferred from the above definition that S_x, S_y, and S_z must be distinct squares.

The pin filter finds pins where the from, through, and to squares each match a particular set of squares specified by the optional from, through, and to parameters. A default value of [Aa] is used for each of from and through if not provided and a default value of [Kk] is used for to if not provided, the result of which is to find absolute pins.

The pin filter is a set filter with a value that depends on the first parameter provided to the filter. If from is specified first, the result is the set of squares occupied by the pinning pieces matching the pin filter. If to is specified first, the result is the set of squares to which the pinned pieces matching the pin filter are pinned. Otherwise, if through is specified first or if no parameters are specified, the result is the set of squares occupied by pinned pieces matching the pin filter.

When no parameters are provided,

pin

is equivalent to

pin through [Aa] from [Aa] to [Kk]

which has a value corresponding to the squares of pieces pinned to their king. The filter

pin from [Aa]

is equivalent to

pin from [Aa] through [Aa] to [Kk]

and finds the same pins as pin but has a value of the squares occupied by the pinning pieces instead of the pinned pieces.

In the above diagram, there are 3 pinning pieces (highlighted in green) that each pin a single opponent piece (highlighted in red). The squares the pinned pieces are pinned to are highlighted in blue. The black rook on b3 pins the white pawn on b5 to the squares b6, b7, and b8 even though there are no pieces on those squares and pawn cannot currently move to another file. The black queen on d8 pins the white pawn on d7 to d6 and d5. The pawn is not pinned to d4 because if the pawn were removed, the queen would not attack d4. The white bishop on b1 pins the black pawn on e4 to the empty f5 square and the king on g6 but not to the square h7 which would not be attacked by the bishop even if the pawn were removed.

The rook on b3 does not pin the bishop on b1 because even though the rook attacks the bishop, there is no square S_z along the ray of attack that is not attacked by the rook but would be if the bishop were removed (because the bishop is on the edge of the board).

Using the pin filter without any parameters in the diagrammed position will find just the black pawn pinned to the black king. To find all of the pins shown, the query

pin to .

can be used which is equivalent to

pin to . from [Aa] through [Aa]

Note that for the purposes of the pin filter, kings may be pinned (may occupy a square in the through set) despite the fact that such a situation would ordinarily be referred to as a skewer as an attacked king cannot legally remain in check.