index Back to help overviewhome Back to home page

CQL - Tagging

It is possible to track the identity of a particular piece. Each piece in the initial position of the game is assigned a unique nonnegative integer, called its mark. Promotion does not change the mark of a piece. A tag is a named mark. We say that a tag is bound to the value of a mark. A tag represents the particular piece whose mark equals the mark of the tag.

:forany in the match list

A tag is defined via the :forany keyword in a match list. The :forany keyword takes two parameters: the alphanumeric name of a tag and a piece designator.

The match filter is then conceptually run once in which each tag is bound to each possible mark, such that two conditions hold:

  • No two tags may be bound to the same mark.
  • A tag may only be bound to a mark that represents a piece that either matches, or eventually matches, the piece designator associated with that tag. Square information associated with that piece designator is ignored.

At most two tags may be contained inside a match list. Tags may not be used in a matchlist if a :relation occurs in a position list inside that match list.

:tagmatch in the position list

A :tagmatch keyword in a position list takes two parameters, the name of a tag and a piece designator. The position list match fails on the current position if the piece and square corresponding to the mark of the tag does not match the given piece designator.

For example, assuming there is a tag named "foo", this position will only match if "foo" is a white pawn:

(position :tagmatch foo )

Piece designators and tags

A piece designator can have a piecetype designator that is the name of a tag preceded by the character '$'. Such a piecetype represents the particular piece represented by the named tag. Because tag names are alphanumeric, square designators in such a piece designator must be enclosed in brackets. Example:

(position $foo[a1])

The piece represented by the tag named "foo" must be on a1.

Longer examples

For longer examples see: Examples for tagging.