# piece and square iteration

There are 4 kinds of piece and square iteration filters in CQL
```    x∊Z F
◭y∊Z F
∀x∊Z F
∀◭y∊Z F
```
Here, `x` is a square variable, `y` is a piece variable, `Z` is a set filter, and `F` is any filter. In each filter, the variable is sucessively assigned the value of each member of the set `Z`. After each assignment, the filter `F` is evaluated.

Note: Iteration is also possible through the keys of a dictionary with a similar syntax.

`x` or `y` is called the iterator variable; `Z` is called the domain; and `F` is called the body.

The first two forms are called existential because the filter is true if for some value of `x` or `y`, the filter `F` is true. The second two forms are called universal because the filter is true if for all values of `x` or `y` the filter `F` is true.

## Existential square variable iteration

The filter
`x∊Z F`
matches the position if `F` is true for some value `x` in `Z`. The ASCII of `∊` is `[element]`.

For example, the following filter is true if a white rook is attacking a square on the eight rank:

`x∊a-h8 ♖→x`

This of course is equivalent to

`    ♖→a-h8`

### value of existential square variable iteration

The value of
`    x∊Z F`
is the set of squares in `Z` for which `F` is true.

For example, the following is true if there is exactly one square attacked by both a white rook and a white bishop:

```    1==x∊▦
♖→x and
♗→x
≡
1==(▦←♖)←♗```

The following checks that there at least three pinned black pieces:

`    3≤x∊▲ △→x→♚`

## Existential piece variable iteration

The existential piece variable iterator
`    ◭y∊Z F`
is true if there is some piece `y` which is on a square in `F` in the current position, and for which `F` is true when `y` is assigned that piece.

Spaces are not allowed between the symbol and the piece variable.

Recall that a piece variable represents the position of a particular piece, and its square value changes as the piece moves.

For example, to check that some white pawn currently on the second rank later promotes to a rook, use:

```    ◭y∊♙a-h2
find y――=♖```

Note that this would not work without the `◭` specifier, because in that case the variable `y` would hold the particular square when it was assigned, which would be some square on the second rank.

### Value of existential piece variable iteration

The value of the existential piece variable iterator
`  ◭y∊Z F`
is the set of squares in `Z` on which there is a piece which, when assigned to the piece variable `y`, makes `F` true.

For example, to check that there are at least two white pawns that are currently on the second rank but that later promote to a rook use:

```    2≤ ◭y∊♙a-h2
find y――=♖```

# universal piece and square iteration

If the piece or square iteration is preceded by the universal quantification symbol `∀` (ascii: `[forall]`), then the associated filter is true only if every element of the domain, when assigned to the iterator variable, makes the body true.

For example, the following filter is true if every empty square adjacent to the black king is attacked by a single white piece:

```  ∀x∊□←♚
1==△→x```

The following filter is true if every white pawn on the second rank in the current position later promotes to a rook

```  ∀◭y∊♙a-h2
find y――=♖```

One has to be careful here because the above filter will also be true if there are no white pawns on the second rank in the current position. To avoid this, preface the filter with

`  ♙a-h2`
which verifies that there is some pawn on the second rank

## Value of a universally quantified piece or square iterator

Universally quanitifed piece or square iterators do not have a value. They either match or don't match the current position.