The Position List

A position list (or position filter) is applied to a position and it either matches or it does not. The keywords in the position list determine how the match is performed, and the piece designators define what is matched.

Some keywords themselves take arguments that are lists of positions. Some keywords modify the way other options work perform their matching.

By default, when a position filter matches a position in a game, if the game itself matches then the game is printed out with the word MATCH preceding the position that matches.

Piece designators inside a position

The major work in a position is usually done by its piece designators. Any position list can have 0 or more piece designators. Without any keywords, a position filter matches a position if and only if each piece designator matches that position.

For example, the position list:

(position Ra3 )
will match any position with a white rook on a3. The position list
(position [RQ][a1-8])
will match any position with a white major piece on the a file.

The position list

(position [RQ][a1-8] q[h1-8])
will match any position with a white major piece on the a file and a black queen on the h file.

The position list

(position .d4 id3 U[a1,h1,a8,h8])

will match any position with an empty square on d4, a black minor piece on d3, and a piece on one of the corners.
Note that in consequence of this repeating piece designators has no effect. The position lists:
(position R Q)

and

(position R R Q Q)
each match any position with a white rook and a white queen.

Simple keywords in a position list

Some keywords take no arguments. These are called simple keywords. Transform keywords will be discussed in the next section. They are:

:mate

Match only if the position is a mate.

:stalemate

Match only if the position is a stalemate

:wtm

Match only if white is to move

:btm

Match only if black is to move

:variations

Look in the variations to find matches

:variationsonly

Look only in the variations to find matches, not in the main line

:initial

This is the first position in the game or study

:terminal

This is the last position in the game or study

:markall

Do not stop after the first match is found, but keep looking.

:check

One side is in check

:nocheck

Neither side is in check

:noannotate

Do not print "MATCH" when this position list matches a position in the game.

Examples using simple keywords

This position list


(position R Q :mate)
matches a position with a white rook and a white queen in which one side is in mate.

We can force white to be in mate:

(position R Q :mate :wtm)
Now white must be mated.

This

(position R Q :initial)
only matches if White has a rook and queen in the first move (of the study, presumably). We can force white to be incheck on the first move:
(position R Q :initial :check :wtm)

Transformation keywords in a position list

Certain keywords within a position list specify that the position list should match a position if some transformation of the position list matches the position. For example, the :fliphorizontal keyword specifies that the position list matches a position if either the original position list matches the position, or if the position list, when flipped about the horizontal bisector, matches the position.

To apply a transformation to a position list we apply the transformation to each piece designator that occurs in the position, and we recursively apply the transformation to any other position lists contained in that position list. If the transformation is a color flip translation, then we also flip interchange any :btm keywords with :wtm ones, and we flip the :result keyword arguments appropriately.

For example, consider the position list

(position Rc2 Bh8 :wtm)
This matches any position with white to move that has a white rook on c2 and a white bishop on h8. The result of applying a unit left shift transformation to this position list is the new position list:
(position Rb2 Bg8 :wtm)
that matches any position with white rook on b2 and white bishop on g8 with white to move.

Similarly, the result of applying a horizontal flip to this position list is the position list:

(position Rb8 Bg1 :wtm)
The result of applying a color flip transformation to the
(position Rb2 Bg8 :wtm)
is thus
(position Rb8 Bg1 :btm)

Remember that shifts interact specially with certain squares on the edge. For example the result of applying a unit up shift to this position list:

(position R[a1,a8,h1,a8])
is the position list:
(position R[a1,a2,h1,h2])
A transformation set is any set of transformations. A transformation set applied to a position list is the set of all position lists that result from applying any transformation in the transformation set to the position list.

Each transformation keyword is associated to a transformation set, each of which also includes the identity transformation. The transformation keywords and their associated transformation sets are:

Examples of transformation keyword uses

Consider this position list:
(position Rc3 qg3)
which matches any position with a white rook on c3 and a black queen on g3. We can add a :shifthorizontal keyword:
(position Rc3 qg3 :shifthorizontal)
The set of transformed position lists is:
(position Rc3 qg3)
(position Rb3 qf3)
(position Ra3 qe3)
(position Rd3 qh3)
A position will match the new position list, if there is a white Rook and black queen on the third rank and the white rook is four squares to the left of the black queen.

Similarly, the position list:

(position Rc3 qg3 :shiftvertical)
will match any position in which there is a white rook on the same rank as a black queen such that the rook is on the c file and the queen on the g file.

The position list:

(position Rc3 qg3 :shift)
will match any position with a white Rook and a black queen on the same rank, in which the white rook is four squares to the left of the black queen. The position list:
(position Rc3 qg3 :fliphorizontal)
will match any position in which either the white rook is on c3 and the black queen is on g3, or the white rook is on c6 and the black queen on g6.

The position list:

(position Rc3 qg3 :flipdiagonal)
will match a position in which either a white rook is on c3 and a black queen on g3, or in which a white rook is on c3 and a black queen is on c7. The position list:
(position Rc3 qg3 :flip)

The following position list matches any position in which a white rook is somewhere behind a white pawn on the c file:

(position Pc2 Rc1 :shiftvertical)
Because of the way edge squares are treated, this will match a position in which, say, the white rook is on c2 and the white pawn on c7.

To match any position in which a white rook is behind a white pawn on the same file, use:

(position Pc2 Rc1 :shift)

Multiple transformation keywords

When multiple transformation keywords occur, the associated transformation set is any transformation that can be expressed as a composition of transformations from the corresponding transformation sets. This feature is most often used when looking for a piece configuration that can occur anywhere on the board, possibly rotated or reflected: adding :shift :flip to the position specifier does this.

For example, this position list

(position Nd4 kf3 :shift :flip)
matches any position in which a white knight attacks a black King, while
(position Nd4 kf3 :shift :flip :flipcolor)
matches any position in which a knight attacks a king of the opposite color.

Note: This example can be written much more efficiently as

 (position :attackcount N k 1 100 :flipcolor)
however.

Piece configuration keywords

Some position list keywords apply the geometrical configuration of the pieces themselves. Most of these can take a range specifier argument as well which counts the number of times the configuration occurs in the position. These piece configuration keywords are: