# piece

The `piece` filter has two forms:
```    piece variable in infilter body
piece all variable in infilter body
```
Here:

For example:

```    piece x in A
x attacks n```

is a `piece` filter with variable equal to `x`; infilter equal to `A`; and body equal to `x attacks n`.

### Piece filter versus piece assignment filter

The `piece` filter should not be confused with the piece assignment filter (for instance, `piece x = N`) which is entirely different.

# Operation of the piece filter

The operation of the `piece` filter is as follows:
1. The set of squares inset represent by the infilter in the current position is computed
2. For each square s in the set inset on which there is a piece:
1. The piece variable variable is bound to the identity of the piece on s
2. The body filter is evaluated
If the `all` keyword is not present after `piece`, then the `piece` filter is a set filter that represents the set of squares s in inset to which variable was bound and for which body was true.

If the `all` keyword is present after `piece`, the the `piece` filter matches the position only if body is true whenever x is bound to a square in inset.

For example, suppose the current position is the following:

From the above position, what pieces does the following filter represent?

```piece Pinner in R
xray (Pinner a k)```

This is a piece filter that matches a position in which a white Rook pins a black piece (the same positions as would be matched by `pin from R`).

To work out the pieces (actually, the squares on which the pieces reside) that the filter represents, we successively set `Pinner` to each white rook:

• `Re1 Ke3 ke5` fails because `Ke3` is not a black piece
• `Ra5 bb5 ke5` succeeds
• `Re8 ne6 ke5` succeeds
• `Rh8 rg7 ke5` fails because it is not an xray.
• `Rh5 pg5 pf5 ke5` fails because there are two black pieces between `R` and `k` instead of one.
Therefore, our filter represents the two white rooks on `a5` and `e8`, or more exactly the squares `[a5,e8]`

For example, consider the following piece filter:

```piece Promoting in Pa-h2
find Promoting&a-h8 ```

This filter has value of the set of squares on the second rank on which there is a white pawn that later promotes (the so-called Excelsior theme).

# Examples

The `piece` filter is used in bristol-universal.cql, clearance-delayed.cql, excelsior-return.cql, excelsior-simple.cql, movedblackpieceecho.cql, platzwechselecho.cql, platzwechseln1.cql, platzwechseln2.cql, rook-corners-1.cql, rook-corners-2.cql, rook-corners-rotate-with-range.cql, serialpin.cql, turton.cql, wurzburg-plachutta.cql.

In excelsior-return.cql, the `piece` filter ensures the same pawn returns to its original square:

```  initial
S=∙
piece E in ♙a-h2 | ♟a-h7
find E――S:E```

This works by first requiring that the current position is the initial position, and saving the initial position in the variable `S`. Then, the `piece` filter is used to bind the variable `E` to each pawn that is on its original square. In any position, the filter `S:E` is now the square on which the piece `E` was on at the initial position. The ―― filter matches a position in which the `E` piece moves to its original square, which can only happen if that piece promoted. The find filter finds any position in which this return move occurs.

This will find for example the following position from a van Reek study:

J. van Reek, 1987, diagram 1
(found from CQL file: excelsior-return.cql)
.

The pawn at `e2` promotes and returns to `e2`, reaching the position

J. van Reek 1987, diagram 2