# 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 (△ ▲ )
ray up (△ ▲ ♙)
ray vertical (△ △ △ ▲ ♚)```

Note: most of the time in CQL, the simpler 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`:

ray from e2 to e8

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:

`  ray dirs (s1 s2 ... sn)`
where dirs indicates a set of basic directions and each si is a set filter.

A ray matches the `ray` filter R if there is a sequence `S` of `n` distinct squares on the ray such that

• The `i`'th square of `S` is a member of the set represented by the set filter si
• 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 `s` that terminate some sequence `S` above.

## Examples of rays

This filter is true whenever a black knight is pinned by a white rook:
```  ray orthogonal (♖ ♞ ♚)
≡
♖→♞→♚
```

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

```  ⬓ray orthogonal (R a k)
≡
⬓♖→▲→♚```

Suppose the current position is the position after

```
1. e4 e5
2. ♘f3 ♘c6```

some rays

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 `♞` represents the squares `[c6,g8]`; `♙` represents the squares `[a2,b2,c2,d2,e4,f2,g2,h2]` and `♘` represents the squares `[f3,b1]`. Thus, the pictured ray would also match the filter

`  ray diagonal (♞ ♙ ♘)`

Likewise, the diagram depicts a matching

`  ray (e1 e4 e5 e8)`
Therefore, the following two filters would also match the diagrammed position:
```ray up (♔ ♙ ♟ ♚)
ray up (♔ □ ♙ ♟ □ ♚)```

Some other matching rays in the position:

```ray right (♜ ♝ ♛ ♚)
ray northeast (♖ ♙ ♟ ♟ ♜)
ray diagonal (♗ ♙ h6)
ray (♕ c2)
ray orthogonal (♔ ♙)```
However, the following ray filter would not match the position:
`  ray (♔ ♟)`

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 wurzburg-plachutta.cql