pin

The pin filter matches a position if the position has any pins that match the pin filter.

Any pin has three distinguished features:

1. The pinning piece. This must be a sliding piece (rook, bishop or queen).
2. The pinned piece. This must be a piece of a different color than the color of the pinning piece.
3. The to square. This can be any square, but if it is nonempty it must hold a piece of the same color as that of the pinned piece.

The pin filter has three optional parameters: from, through, and to. Each parameter is specified by its associated keyword followed by a set filter:

  pin
  pin through R
  pin from Q
  pin to q
  pin from Q through r to k

Each parameter has specific defaults according to the following table:

parameter	default	corresponding piece
from	[Aa]	pinning piece
through	[Aa]	pinned piece
to	[Kk]	to square

Thus,

pin

is the same as

pin through [Aa] from [Aa] to [Kk]

Similarly,

  pin from Q

is the same as

  pin from Q through [Aa] to [Kk]

A pin matches a pin filter if

1. The pinning piece of the pin lies within the set represented by the from parameter of the pin filter
2. The the pinned piece of the pin lies within the set represented by the through parameter of the pin filter
3. The to square of the pin lies within the the set represented by the to parameter of the pin filter.

Thus,

  pin

matches a position where some piece is pinned against its own king.

  pin from Q

matches a position in which a white queen pins a black piece against the black king.

pin through a

matches a position in which a black piece is pinned against its own king.

The set represented by a pin filter

A pin filter is a set filter. The squares that it represents depends on which parameter is the first parameter that follows the keyword pin (this is similar to how the move filter determines which set it represents).

• If the first parameter is from then the pin filter represents the squares of the pinning pieces of the pins that match the pin filter.
• If the first parameter is to then the pin filter represents the to squares of the pins that match the pin filter.
• If the first parameter is through then the pin filter represents the pinned pieces of the pins that match the pin filter.

The first parameter following a pin filter without any explicitly given parameters is taken to be through.

Therefore,

  pin

represents the set of squares on which there are pinned pieces.

  pin>4

matches positions with more than 4 pins (of a piece against its own king).

To find positions with more than 2 pinned white pieces, use

  pin through A>2

Examples

The pin filter is used in idealmate.cql, idealstalemate.cql, immured.cql, modelmate.cql, modelstalemate.cql, pins.cql, pinstalemate.cql, puremate.cql, queenpawnpinecho.cql, serialpin.cql.

As discussed above,

 pin through A

is the set of squares on which there is a white piece pinned by black against the white king. Thus,

 pin through A>= 3

is true in a position if there are more than 3 pinned white pieces (due to the conversion of set operands to their cardinality). Likewise,

 comment ("pinned pieces: " pin through A)

will output a comment of the squares of the pinned pieces.

These concepts are combined to find games with the most pins in the file pins.cql, which sorts the output by the number of pins. Note the key filters:

   sort "number of pinned pieces"{
	comment ("Pinned pieces: " pin through A)
	pin through A>= 3

This CQL finds the following stalemate from a 2014 Melnichenko study:

Melnichenko 2014, after 7...R:h6 stalemate
(found from CQL file: pins.cql)

Note how the location of the pinned pieces is output as a comment to Black's 7...R:h6. This is because of the set value of the pin filter here.

Also, note that only the one comment is printed for the position with the maximum number of pins, even though earlier positions in the study had 3 pins and could have matched. This is because of smart comments, which only print the maximal comments in a sort.