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, bristol2.cql, clearance-delayed.cql, excelsior-comment.cql, excelsior-return.cql, excelsior-simple.cql, idealmate.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
Start=currentposition
 piece Excelsior in Pa-h2 | pa-h7
   find move from Excelsior
              to Start:Excelsior

This works by first requiring that the current position is the initial position, and saving the initial position in the variable Start. Then, the piece filter is used to bind the variable Excelsior to each pawn that is on its original square. In any position, the filter Start:Excelsior is now the square on which the piece Excelsior was on at the initial position. The move filter matches a position in which the Excelsior 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