# 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
`up`
`down`
`left`
`northeast`
`northwest`
`southwest`
`southeast`
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
`diagonal``northeast`, `northwest`, `southeast`, `southwest`
`orthogonal``up`, `down`, `left`, `right`
`vertical``up`, `down`
`horizontal``left`, `right`
`anydirection``orthogonal`, `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 ♔
diagonal 2 5 ♙♟
up 1 ♟
```

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}
≡  [d7,d1]

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 ♙  ≡  a-h3

up ♘  ≡  [b2-8,g2-8]

right 1 ♖♛  ≡  [b1,b8]

right 1 △ attackedby ♕
≡   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 `♕`, use:

`flip up 2 right 1 ♕`

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

Similarly,

`  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:
```  f1  ≡  southwest 1 g2
h8  ≡  northeast 3 d5```

## directions in `ray`

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

# Examples

Directions are used throughout the examples: in Qq-rotations.cql (`right` filter); in chameleon.cql (`right`; staircase-sort.cql (`up` and `right`); in quadrupled-pawns2.cql (`vertical`); 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

`  ♕――up 1 ♕`
Suppose there is only one white queen on the position, say on `e4`. Then
`  up 1 ♕ ≡ up 1 e4 ≡ e5`

Thus,

```  ♕――up 1 ♕
≡
♕e4――e5```

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

Similarly,

```   ♕――right 1 ♕
≡
♕e4――f4```

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

Lets call these movements `Q_UP` and `Q_RIGHT` respectively.

Basically,

```  (♕――up 1 ♕
♕――right 1 ♕)
≡
(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`

```  (♕――up 1 ♕
♕――right 1 ♕)+```

means one or more successive stairs.

The

`♕――up 1 ♕ ?`
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`).