# The ray filter

The`ray`

filter is used to find patterns of pieces that are arranged along a straight line.
A `ray`

filter consists of the keyword `ray`

followed by an optional directions followed by a list of set filters enclosed in parentheses:

ray (A a ) ray up (A a P) ray vertical (A A A a k)

*Note*: most of the time in CQL, the simpler xray is all that is needed instead of `ray`

.

A *ray* on the chessboard is the set of squares along a straight line from a given *start point* along one of the 8 basic directions .

For example, there is an `up`

ray from the start point `e2`

. That ray has seven squares, `e2-8`

:

Each ray *orders* the squares on that ray. The ordering is
determined by the direction of the ray. If squares *s* and *t* are on the
ray, then *s* is *earlier*
than *t* if *t* can be reached from *s* by moving along the
ray's basic direction.

For example, in the `up`

ray starting on `e2`

, the square `e3`

is earlier
than `e7`

. But in a `down`

ray starting on `e8`

, the square `e7`

is earlier
than `e2`

.

The *basic directions* of a ray filter are the basic directions contained in the set of directions indicated by its direction parameter (recall that
some directions represent a set of basic directions: `vertical`

represents the set containing `up`

and `down`

for example. If there is
no direction parameter to the `ray`

filter, the direction parameter is taken to be `anydirection`

, all the 8 basic directions.

Let *R* be the following `ray`

filter:

raywheredirs(s_{1}s..._{2}s)_{n}

*dirs*indicates a set of basic directions and each

*s*is a set filter.

_{i}
A ray *matches* the `ray`

filter *R* if there is a sequence

of *S*

distinct squares on the ray such that
*n*

- The

'th square of*i*

is a member of the set represented by the set filter*S**s*_{i} - The direction of the ray is a member of the set of basic directions indicated by
*dirs* - There are no pieces between two consecutive squares in
*S*

*R* is also a set filter representing the set of squares

that terminate some sequence *s*

above.
*S*

## Examples of rays

This filter is true whenever a black knight is pinned by a white rook:ray orthogonal (R n k)

To match a position where some piece is pinned by a rook of either color, use:

flipcolor ray orthogonal (R a k)

Suppose the current position is the position after

1. e4 e5 2. Nf3 Nc6

One ray that would match the position is

ray diagonal (c6 e4 f3)

That is because starting at `c6`

the ray moves diagonally, skipping over empty squares (one empty square in this case at `d5`

and the reaches `e4`

, and then, skipping over zero empty squares, reaches `f3`

.

If this position were the current position, then `n`

represents the squares `[c6,g8]`

; `P`

represents the squares `[a2,b2,c2,d2,e4,f2,g2,h2]`

and `N`

represents the squares `[f3,b1]`

. Thus, the pictured ray would also match the filter

ray diagonal (n P N)

Likewise, the diagram depicts a matching

ray (e1 e4 e5 e8)Therefore, the following two filters would also match the diagrammed position:

ray up (K P p k) ray up (K _ P p _ k)

Some other matching rays in the position:

ray right (r b q k) ray northeast (R P p p r) ray diagonal (B P h6) ray (Q c2) ray orthogonal (K P)However, the following ray filter would not match the position:

ray (K p)

This is because there is a white pawn between the king at `e1`

and the best target of such a ray, the black pawn at `e5`

.

# Examples

The`ray`

filter is used in bristol1.cql and wurzburg-plachutta.cql