Types of directions

A direction in CQL denotes a set of 1 or more basic directions on the chessboard. The name of a direction can also be used as a filter that translates a set of squares along certain directions by a certain length.

There are eight basic directions:

basic direction
These refer to the natural directions on the chessboard from the white perspective: e.g., up is in the direction of increasing rank.

There are also five compound directions, which represent two or more basic directions:

compound directionbasic directions represented
diagonalnortheast, northwest, southeast, southwest
orthogonalup, down, left, right
verticalup, down
horizontalleft, right
anydirectionorthogonal, diagonal

A direction keyword is the name of a direction, like northeast.

direction filters

A direction filter consists of a direction keyword, one of:

  • up
  • down
  • left
  • right
  • northeast
  • northwest
  • southeast
  • southwest
  • diagonal
  • orthogonal
  • vertical
  • horizontal
  • anydirection

followed by an optional range followed by a set filter:

  direction range set
  direction set

For example,

  orthogonal K
  diagonal 2 5 [Pp]
  up 1 p

If range is absent it is taken to be 1 7.

A direction filter represents the set of squares by shifting the set of squares represented by its argument, in the direction indicated by its direction keyword, a number of times indicated by its range. For example:

up 1 d4    d5
up 2 d4    d6
up 3 d4    d7
up 1 3 d4    d5-7
up d4    d5-8
down 1 d4    d3
down d4    d1-3
left 1 [d4,e5]   [c4,d5]
left [d4,e5]    [a-c4,a-d5]
right a1-8    b-h1-8
right 1 a-h2    b-h2
right 6 7 a-h2    [g2,h2]

The range in the direction filter can include negative numbers. These denote a direction opposite to the direction of the direction keyword in the direction filter.

up -2 d4    d2
right -1 1 d4    c-e4

Each compound direction keyword is likewise associated with a direction filter. These represent the union of the sets corresponding to the basic directions in the compound direction filter. For example:

vertical 3 d4 
   {up 3 d4} or {down 3 d4}

diagonal 1 d4 [e5,c5,c3,e3]

orthogonal d4 [a-c4,d5-8,e-h4,d1-3]

Although a compound direction filter can have a range with negative bounds, it is unnecessary to include this, since each compound direction filter includes the opposite direction of each of its basic direction elements:

horizontal 0 1 d4    c-e4
horizontal -1 0 d4    c-e4
horizontal -1 1 d4    c-e4
Note that these examples can be used for any sets, not just squares. For example, suppose the current position is the start position:

Then the following relations would hold:

up 1 P    a-h3

up N [b2-8,g2-8]

right 1 [Rq] [b1,b8]

right 1 A attackedby Q right 1 [c-e2,e1,c1] [d-f2,f1,d1]

These can be combined with other primitives, including direction filters. For example, to find squares a knight's hop away from a Q, use:

flip up 2 right 1 Q

If the current position were the starting position, for example, this expression would be represent [f2,e3,c3,b2]


  diagonal diagonal h1
is the set of light squares:
  diagonal diagonal h1
     diagonal diagonal 1 7 h1
     diagonal [g2,f3,e4,d5,c6,b7,a8]
     diagonal 1 7 [g2,f3,e4,d5,c6,b7,a8]
This last expression is the set of light squares, because every light square can be reached by moving a distance from 1 to 7 along a diagonal direction from one of these squares. For instance:
  h1    southwest 1 g2
  g8    northeast 3 d5

directions in ray

Directions are also used as a parameter to the ray filter.


Directions are used throughout the examples: in Qq-rotations.cql (right filter); in chameleon.cql (right; in staircase.cql and staircase-sort.cql (up and right); in quadrupled-pawns2.cql (vertical) in bristol2.cql (diagonal, both as a filter and as a keyword to ray); in bristol-universal.cql (anydirection).

Let us consider the use of directions in the staircase-sort.cql file. This file finds a number of studies using queen staircases, one of which is

Aliev/Shukurov 2008, after 2...Kg1
(found from CQL file: staircase-sort.cql)

The arrows in the diagram trace the path of the white queen.

If we consider a filter from the CQL file

  move from Q to up 1 Q
Suppose there is only one white queen on the position, say on e4. Then
  up 1 Q  up 1 e4  e5


  move from Q to up 1 Q
  move from Qe4 to e5

In other words, the queen moves one square up the board.


   move from Q to right 1 Q
   move from Qe4 to f4

that is, the queen moves one square to the right.

Lets call these movements Q_UP and Q_RIGHT respectively.

The line syntax is a bit cryptic if you are not familiar with it. Basically,

  (move from Q to up 1 Q
    --> move from from Q to right 1 Q)
  (Q_UP --> Q_RIGHT) 
This means a Q_UP move followed by a Q_RIGHT move.

Let's call a Q_UP followed by a Q_RIGHT a stair.

The + at the end means one or more repetitions

  (move from Q to up 1 Q
    --> move from Q to right 1 Q) +
means one or more successive stairs.


move from Q to up 1 Q ?
at the end is just
Q_UP ?
where the ? means "optional". Thus, the whole sequence means:

one or more stairs followed optionally by Q_UP.

This would define an up staircase, like this (assuming the queen is a1)

up-right staircase

To get a staircase in any direction, put flip in front of the above staircase's filter. (If you reflect the above staircase starting at a1 about the horizontal bisector, you get the original staircase starting at a8).