The ray filter
The ray filter is a fundamental building block of CQL matching. The ray filter is most commonly used to find pins, but it can be used for more complex configurations as well.The syntax of the ray filter is as follows:
ray optional_range '(' setfilters ')' ray optional_range direction_keyword '(' setfilters ')' ray optional_range attack '(' setfilters ')'
Here, optional_range
is a range that is optionally present.
The setfilters are a whitespace separated list of at least two
set filters. For example:
ray (A a ) ray up (A a P) ray vertical (A A A a k) ray attack (A a k)A ray on the chessboard is all the squares in a straight line with a startpoint and an endpoint that is in one of the eight basic directions. For example, there is an up ray from the start point e2 to the endpoint e8 in the up direction. That ray has seven squares e28.
Each ray orders the set of its squares. The ordering is determined by the direction of the ray. If squares s and t are on the ray, then s is earlier than square t if t can be reached from s by moving along the ray's basic direction.
For example, in the up ray from e2 to e8, the square e3 is earlier than e7. But in the down ray from e8 to e2, the square e7 is earlier than e2.
A ray R is said to match a list of n distinct squares in the current position, s_{1}, s_{2}, ...,s_{n} if
 Each s_{1}, ..., s_{n} is on the ray

 s_{1} is earlier than s_{2}
 s_{2} is earlier than s_{3}
 ...
 s_{n1} is earlier than s_{n}.
 If a square t is on the ray then either
 t is one of s_{1},...,s_{n} or
 t is empty (or both)
The basic directions of a ray
Each ray filter has a set of allowed basic directions depending on its direction parameter and its argument setfilters.If the direction parameter is omitted, then the basic directions allowed are the eight basic directions.
If a direction_keyword is specified, then the basic directions are the elements of the directions given by that keyword.
ray attack (s_{1} s_{2} ... )is shorthand for
ray orthogonal ({[QqRr] on s_{1}} s_{2} ...) or ray diagonal ({[QqBb] on s_{1}} s_{2} ...)
ray filter matching a position
A ray filter with arguments s_{1}, s_{2}, ..., s_{n} matches the current position if: there is some basic direction D that is one of the basic directions of the ray
 there is a ray R in the direction D
 there are squares t_1, t_2, ... such that t_1 is in the set represented by s_{1}; t_2 is in the set represented by s_{2}; and so on,
 R matches s_{1}, s_{2}, ...
 s_{1} is the startpoint of R and s_{n} is the endpoint of R
Examples of rays
This filter is true whenever a black knight is pinned:ray attack (A n k)To match a position with any pinned black piece, use
ray attack (A a k)To match any pinned piece, use
flipcolor ray attack (A a k)Suppose the current position is the position after 1e4 e5 Nf3 Nc6. Then some rays that would match the position are:
ray diagonal (c6 e4 f3) ray diagonal (n P N) ray (n P N) ray up (K P p k) ray up (K _ P p _ k) ray right (r b q k) ray northeast (R P p p r) ray attack (B P h6) ray (Q c2) ray orthogonal (K P)However, the following ray filters would not match the position:
ray (K p) ray (K p k) ray diagonal (K p) ray attack (N ah18)
counting rays
If the ray keyword is followed by a range, then the ray matches the position only if the number of distinct rays matching the arguments lies within the range. For example,ray 2 4 attack (A a k)matches a position only if two, three, or four Black pieces are pinned