CQL - The position list

The symbol in the title of a keyword description denotes that this keyword is an extension, it is not part of the CQL standard.

The keywords :castling, :endgame, and :inside are borrowed from Chess Assistant 9. The description of these keywords are taken from The CQL 3.GX Extension .

Some of the keywords can be negated with a preceding exclamation, then this is an abbreviation; e.g.

is an abbreviation for

The keywords :nocheck, and :noenpassant are not used anymore in CQL-S – the expressions !:check, and !:enpassant should be used instead – but will be recognized and transformed accordingly when importing CQL scripts.

• •	Index
  •	Logical keywords
  •	Simple keywords
  •	Transformation keywords
  •	Piece configuration keywords
  •	Move keywords
  •	Sequence keywords
  •	Game related keywords
  •	Relation between positions
  •	Matching count keywords
  •	Analyzing keywords
  •	Accumulator keywords
  •	Tagging keywords
  •	Controlling keywords
  •	Meaningless keywords

Index

Logical keywords

:and

Takes a list of position lists and matches a position only if each of them match the position.

Example:

(position
  :wtm
  :check
  :and (
    (position ♔e2 ♚g2 :shift :flip)
    (position ♘e2)))

Will match positions in which the kings are in direct opposition, there is a white knight on e2, and white is in check.

:cond 

This keyword will be used in the following general form:

:cond
  (position <Condition1>) (position <Expression1>)
  (position <Condition2>) (position <Expression2>)
  ...
  (position <Conditionk>) (position <Expressionk>)

:cond expects an arbitrary number of arguments. Each argument <Conditioni> will be called a clause, and each argument <Expressioni> is an association. Successively each clause will be evaluated until a matching clause is found, the associated expression is the result of the whole :cond expression. A game cannot match if no clause is matching. This means that the order of the lists inside an :cond is important. A position cannot match if none of the clauses is matching. It is not allowed that an argument contains a position list.

Often the final pair will be expressed in the following form:

(position) (position <Expression>)

The empty list is matching any position. This case can be expressed in an abbreviated form, by omiting the second last argument (position). Then the result of the last expression will be evaluated if no clause is succeeding.

In fact the keyword :cond is not redundant, because the conversion with the use of keyword :or is not equivalent in all cases (the use of :cut, :exclude, or :skip is breaking the equivalence). Moreover the order inside of :cond is significant.

(position :or (
  (position <Condition1> <Expression1>)
  (position <Condition2> <Expression2>)
  ...
  (position <Conditionk> <Expressionk>)))

Furthermore the :cond expression will be executed quite more efficient (consider the case that <Condition1> will match, but not <Expression1>, then the :or form will proceed with next list, while the :cond form is delivering the result of <Expression1> immediately).

However the :or form shows why the :cond form is also using the association for marking the matches. To give an example:

(match
  (position :cond (
    (position ♙e7) (position ♟e2))))

If a position has a white pawn on square e7, and a black pawn on square e2, both squares will be marked in any matching position.

See :exclude for a real example showing the usage of :cond.

:not

This keyword can be used in two forms: either it is included in a position match list, or it has a sub-position list as argument. In former case: match if the containing match list would not match without the :not. In latter case negate the result of the sub-position list match. The former case is conform with CQL standard of keyword :not, the second form is an extension.

Examples:

(match
  (position
    ; we are searching for either colors
    :flipcolor
    ; the mating position must match each criterion below
    :and (
      ; the black king is surrounded by empty squares and
      ; is attacked once and is in mate
      (position
        :attackcount ♚ . 8
        :attackcount ○ ♚ 1
        :mate
        :btm)
      ; check that no neighbor of the black king is
      ; attacked more than once
      (position
        :not
        :attackcount ♚ .e4 1
        :attackcount ○ .e4 >=2
        :shift))))

This finds all ideal mirror mates: studies in which the king is surrounded by empty squares, is attacked once, such that if the king were to move to one of its neighbors, it would be attacked exactly once.

The follwing position match

is equivalent to

In this case the simpler form with :not is preferable.

:or

Takes a list of position lists and matches a position only if at least one of them matches the position.

Example:

(match
  (position
    :or (
      (position :piececount ♗□? 2)
      (position :piececount ♝□? 2)
      (position :piececount ♗■? 2)
      (position :piececount ♝■? 2))))

Searching for games with one side has two bishops of same color.

:xor

Expects a list of position lists and is matching a position if and only if exactly one of the position lists is matching this position.

Example:

(position :xor ((position ♗■?) (position ♗□?)))

Match all position where either White has a light-squared bishop or a dark-squared bishop, but not both.

Simple keywords

:blackcannotwin 

Match only if black cannot win in this position.

Normally this is equivalent to following query:

:or (
  ; black king only
  (:piececount ● 1)
  ; black king and black minor piece only
  (:piececount ● 2 :piececount ▼ 1))

In chess variant Three-check Chess the query with :blackcannotwin succeeds only if black has no more pieces than the king, and in all other chess variants this query has no meaning and is always failing.

In chess variant King-of-the-Hill :blackcannotwin cannot match any game.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match all position where black (theoretically) still has winning chances.

See also: :whitecannotwin

:btm

Match only if black is to move.

See also: :wtm.

:check

One side is in check. This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Neither side is in check.

See also: :ischeck, :contactcheck, :doublecheck.

:castling 

This keyword specifies castling availabilities for either sides. It takes as an argument a piecetype designator, letters of which have the following meanings:

• ♔	White has kingside castling availability
  ♕	White has queenside castling availability
  ♚	Black has kingside castling availability
  ♛	Black has queenside castling availability

Examples:

White has kingside castling availability.

White has either kingside or queenside castling availability (but not both).

White has either kingside and queenside castling availabilities.

See also: :iscastling.

:contactcheck 

One side is in check, and it is a contact check (it's not possible to place a piece between the checker and the king, even not theoretical). This includes knight checks and double checks.

This is equivalent to:

(position
  :check ; exclude Antichess games
  :or (
    (position :doublecheck)
    (position :attackcount [♘♙] ♚ 1 :flipcolor)
    (position [♕♖]d4 ♚[c4,e4,d3,d5] :flipcolor :shift)
    (position [♕♗]d4 ♚[c3,c5,e3,e5] :flipcolor :shift)))

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Neither side is in check, or it is not a contact check.

:iscontactcheck, :check, :doublecheck.

:doublecheck 

One side is in check, and it is a double check.

In fact this is an abbreviation for:

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match all position where neither side is double checked.

See also: :isdoublecheck, :check, :contactcheck.

:endgame 

The position is an endgame position. The keyword is equivalent to the following query:

  (position
    :or (
      (position
        :piececount [♕♛] 0
        :piececount [♖♗♘] 0 3
        :piececount [♜♝♞] 0 3)
      (position
        :piececount ♕ 1
        :piececount ♛ 1
        :piececount [♖♜] 0
        :piececount ▽ 0 1
        :piececount ▼ 0 1)
      (position
        :piececount ♕ 1
        :piececount ♖ 0
        :piececount ▽ 0 1
        :piececount ♛ 0
        :power [♜♝♞] 0 16
        :flipcolor)))

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match all positions which are not an endgame position.

:fen 

The position is equal to the described position in given argument. This argument must be a valid FEN (Forsyth-Edwards Notation).

Example:

(position
  :fen "rnbqkbnr/pppp1ppp/4p3/8/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2")

This position denotes a basic position of the French line. Normally this position will be achieved with the line 1.e4 e6 2.d4 d5.

See also: :line*.

:fiftymoverule 

First position in game where no capture has been made and no pawn has been moved in previous fifty consecutive moves. Inside of sub-variations this keyword has no effect and will always fail.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match all positions where the fifty move rule does not apply. Inside of sub-variations this query is always successful.

See also: :halfmoveclocklimit.

:gameisover 

This is an abbreviation for:

  :or (
    (position :mate)
    (position :stalemate)
    (position :losing)
    (position :checkcount 3)
    (position :nomatingmaterial))

Note that this keyword may effect unwanted results if the search includes sub-variations.

Examples:

Matches all games ending in a position which prevents continuing.

Match all position which can be continued (according to the chess rules).

:halfmoveclocklimit 

This keyword is matching a position where the halfmove clock is equal or less given limit.

Halfmove clock: This is the number of halfmoves since the last pawn advance or capture. This is also used to determine if a draw can be claimed under the fifty-move rule (⇒ :fiftymoverule).

Example:

Exclude all positions where no capture has been made and no pawn has been moved since more than thirty halfmoves (15 moves by each side).

See also: :fiftymoverule.

:initial

This is the first position in the game (before first move). In fact this is an alternative notation for:

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match all positions except the first position in the game.

The following expressions are not equivalent:

The first expression is matching empty games (games without moves), but the second expression is not doing this.

See also: :halfmovenumber.

:insidevariation 

This keyword matches if a position will be found inside a sub-variation. This cannot happen as long as :variations is not used to include sub-variations.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

This position is not found inside a sub-variation.

See also: :variations.

:losing 

Will match the final position if one side has lost all pieces. This is possible only in Antichess games.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Only match positions where neither side has lost all pieces.

:mate

Match only if the position is a mate.

When searching for mate positions this keyword should always be used even if this keyword might be superfluous because other conditions are ensuring a mate position, it is accelerating the search (only testing final positions).

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Exclude all checkmate positions.

One more example:

Only matches if one side is mated in first 20 moves.

See also: :ismate.

:matingmaterial 

Match a position if either player has mating material (⇒ :nomatingmaterial). In chess variant Three-check Chess this search cannot match as soon as only kings are on board. In all other chess variants (except Three-check Chess, and Normal Chess) this keyword is meaningless and always successful.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match positions where neither player has mating material. Normally this query is equivalent to:

:or (
  ; king versus king
  (position :piececount ◑ 2)
  ; king and minor piece versus king
  (position :piececount ◑ 3 :piececount [▽▼] 1)
  ; king and bishop versus king and bishop,
  ; both bishops are either light-squared, or dark-squared
  (position :piececount ◑ 4 :piececount [♗♝]□? 2)
  (position :piececount ◑ 4 :piececount [♗♝]■? 2))

The negated form is always unsuccessful in all other chess variants than Three-check Chess.

:mustcapture 

In this position the side to move has the obligation to capture a piece (this also means that a capture is possible). This keyword is provided for chess variant Antichess, and cannot be successful in all other chess variants.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

In this position the side to move ist not obligated to capture a piece (this also means that a capture is not possible at all). This condition will be always fulfilled in other chess variants than Antichess.

See also: :mustcapture,

:nocheck

This keyword is deprecated and should not be used anymore. It will be supported only for compatibility reasons, ans has the same meaning as the expression !:check.

:stalemate

Match only if the position is a stalemate.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match only if the position is not stalemate.

See also: :isstalemate,

:terminal 

This is the last position in the game (after last move). In fact this is only an alternative form for:

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

This is not the final position in the game.

The following expressions are not equivalent:

The first expression is matching empty games (games without moves), but the second expression is not doing this.

See also: :halfmovenumber.

:threefoldrepetition 

Match first position of mainline which occurred the third time in this game, with same player to move, and each player has the same castling and en-passant capturing rights. The repeated positions need not occur in succession. This accords with the threefold repetition rule .

Inside of sub-variants this keyword has no effect and will always fail.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match any position which is not occurring the third time. If it is not wanted to match positions after a threefold repetition has occurred, then realize this with :cut:

:variations

Look in the variations to find matches. Without this keyword the variations will be skipped.

:variationsonly

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

:whitecannotwin 

Match only if white cannot win in this position.

Normally this is equivalent to following query:

:or (
  ; white king only
  (position :piececount ○ 1)
  ; white king and white minor piece only
  (position :piececount ○ 2 :piececount ▽ 1))

In chess variant Three-check Chess this query succeeds only if white has no more pieces than the king, and in other chess variants this query has no meaning and is always failing.

This keyword can be used in a negated form; with a preceding exclamation mark. Example:

Match all positions where the white player still has the option to win (even if only theoretical).

See also: :blackcannotwin

:wtm

Match only if white is to move.

Transformation keywords

:flip

Same as :flipdihedral (⇒ Transformations).

:flipcolor

The color flip transformation (⇒ Transformations).

This color flip transformation will have two effects: on one hand a flip about the vertical bisector of the board (⇒ Transformationen) and, on the other hand, a color flip: exchange white with black, and black with white. This color flip transformation has no impact to the match list (match ...) (:eithercolor : match is designated for this).

:flipdiagonal

The diagonal flip transformation (⇒ Transformations).

:flipdihedral

All dihedral transformations (⇒ Transformations).

:fliphorizontal

The horizontal flip transformation (⇒ Transformations).

:flipvertical

The vertical flip transformation (⇒ Transformations).

:inside 

This keyword filters shift transformations in order to some matching pieces will stay inside a specified region of the board. It takes two arguments, a piece designator and a square designator. Any shift transformation affects only the first argument. A shift transformation match :inside limitation if at least one piece matching the first argument (taking into account the transformation) is placed on a square matching the second argument.

The following examples are only demonstrations for the usage of :pawncount. For the search of tripled pawns the keyword :pawncount is recommended.

We use the following query to find tripled pawns:

(position
  :piececount ♙[b2-7] 3
  :shifthorizontal)

To find one of tripled pawns placed on the main diagonal we design the query

(position
  :inside ♙[b2-7] [b2,c3,d4,e5,f6,g7]
  :piececount ♙[b2-7] 3
  :shifthorizontal)

:shift

The shift transformations (⇒ Transformations).

:shiftdiagonal

The off-diagonal and main-diagonal shift transformations (⇒ Transformations).

:shifthorizontal

The horizontal shift transformations (⇒ Transformations).

:shiftmaindiagonal

The main-diagonal shift transformations (⇒ Transformations).

:shiftoffdiagonal

The off-diagonal shift transformations (⇒ Transformations).

:shiftvertical

The vertical shift transformations (⇒ Transformations).

Piece configuration keywords

:attackcount

This keyword takes as arguments two piece designators followed by a range specifier. The first piece designator is the attacker piece designator. The second piece designator is the attacked piece designator. An attack by a piece to a square occurs if the piece could move to that square were it empty and disregarding any possible checks. A valid attack is an attack by a piece on a square that matches the attacker piece designator to a square on which is a piece that matches the attacking piece designator.

The :attackcount keyword matches a position if the total number of valid attacks in the position lies with the range given by its range specifier.

Examples:

Will match any position in which white has a double attack on the black king (note that the use of :doublecheck combined with :btm should be preferred).

Will match any position in which a king is under double attack (again the use of :doublecheck should be preferred).

Will match a position in which exactly one white piece attacks an empty h3 square.

Will match a position in which the number of times a white rook or white bishop on a8, b8, or c8 attacks a square on the first rank is between 5 and 9 inclusive.

Will match position for which the number of times a black knight attacks a white King or white major piece is at least 3.

Both kings cannot move in this position.

In this position no white piece can move onto the black back rank.

Only one move is possible in this position.

No knight can be dropped in this position (Crazyhouse, Bughouse Chess).

:goodbishop 

Match positions with at least one bishop which is rated good or bad. This keyword expects a piece designator as first argument, containing only bishops. Then either two range specifiers, or two percentage range specifiers will follow. The first one is denoting the count or the percentage of the opposing pawns – the percentage refers to the total count of opposing pawns – and the second range is the count or the percentage of all own pawns which are not blockading the bishop – in this case the percentage refers to the total count of own pawns. Both ranges will be applied for each bishop individually. The ranges must be separated by symbol :.

Examples:

White has at least one good dark-squared bishop, because more than 50% of the opposing pawns are dark-squared (thus attackable), and more than 50% of the own pawns are light-squared (thus not blocking the bishop).

White has at least one good bishop.

One side has a bad bishop.

:opposition 

This keyword is matching all positions where the specified king has the opposition. It takes a piecetype designator as an optional argument, where the piecetypes have the following meaning:

• ♔	White king has opposition to black king.
  ♚	Black king has opposition to white king.

If no piecetype designator is given, the king of the side to move will be investigated.

The use of this keyword is appropriate only in certain endgame situations, to check whether the king is in opposition again, for example. Whether a king has the opposition will be decided with a purely formal computation over the distance of the kings, considering the side to move, but disregarding all other pieces on the board, even possible checks will no be taken into consideration. Hence the following example would match even the start position:

:pawncount 

:pawncount serves for counting pawn structures or pawn attributes. The first argument is a piece designator, which contains only pawns, followed by a hyphen-separated enumeration of attributes. The last argument is either a range specifier, or a percentage range specifier. The percentage specification refers to the total count of pawns on the board with the same color as specified in the piece designator. This keyword is matching if the distribution of those pawns, fulfilling all the given attributes, is inside the specified range.

The supported pawn structures and pawn attributes are:

Es muss mindestens eine dieser Bauerneigenschaften verwendet werden.

Alle Bauerneigenschaften können auch mit einem vorangestellten Ausrufungszeichen negiert werden, dazu Beispiele:

Mehr als 50% der weißen Bauern stehen keine gegnerischen Bauern auf der gleichen Linie gegenüber.

Mehr als 50% der weißen Bauern stehen keine gegnerischen Bauern auf der gleichen Linie unmittelbar gegenüber.

Mindestens ein Freibauer ist nicht mehr innerhalb der Reichweite des gegnerischen Königs.

Bemerkung: Das Attribut passed ist nur eine Kurzschreibweise:

• passed

  =

  unblocked-unstoppable

Jedoch ist !passed keine Kurzschreibweise.

Bemerkung: Das Attribut candidate! ist nur eine Kurzschreibweise:

• candidate!

  =

  candidate-!passed

Die folgenden Attribute, die ebenfalls mit einem vorangestellten Ausrufungszeichen negiert werden können, schränken die Sichtweise auf die Bauern ein:

Die Position von forefront bzw. rear innerhalb der Liste der Eigenschaften beeinflußt, für welche Attribute die Sichtweise eingeschränkt wird. Beispiel:

Dies findet nebeneinanderstehende Doppelbauern gleicher Farbe auf, wobei sie auf den gleichen Reihen stehen müssen. forefront muß nach double! verwendet werden, ansonsten ist kein Doppelbauer auffindbar (tatsächlich meldet die Applikation dann einen Fehler). Die Reihenfolge zu duo spielt hier keine Rolle.

Die unterstützen Attribute für die Modifikation der Zählweise sind:

Eine Zählung erfolgt immer am Schluß, nachdem aller Bauern mit den gewünschten Eigenschaften aufgefunden wurden. Damit dies klarer beim Lesen des Ausdrucks wird, dürfen Attribute für die Zählung nur am Ende einer Attributliste verwendet werden.

Die Attribute für die Zählweise haben keinen Einfluß auf die Auswahl der gezählten Bauern. Sobald beispielsweise islands in einer Verknüpfung verwendet wird, werden immer die Anzahl der Insel gezählt. Dazu Beispiele:

Nun wird die Anzahl aller Bauerntrios gezählt, nicht mehr die Anzahl der beteiligten Bauern.

Die Anzahl der Bauernketten wird gezählt, nicht die Anzahl der beteiligten Bauern.

Manche dieser Attribute können ein Zähler als Argument haben. Der Zähler muß den Wertebereich einhalten:

Grundsätzlich können alle Attribute miteinander verknüpft werden, jedoch sind nicht alle Verknüpfungen sinnvoll. Es erfolgt eine Fehlermeldung, wenn sich in einer Verknüpfung Attribute widersprechen (wie z.B. bei chained-isolated, oder mirrored-unblocked).

Die Attribute wirken als Filter, d.h. jedes Attribut filtert die Bauern mit der spezifizierten Eigenschaft, und das nachfolgende Attribut filtert dann die verbliebenen Bauern aus der vorhergehenden Zählung. Daraus resultiert, daß die Reihenfolge der verknüpften Attribute generell eine Rolle spielt, so sind die folgenden Beispiele nicht äquivalent:

Im ersten Fall können tatsächlich nur dann Bauern auf einer Linie gezählt werden, wenn es keinen weiteren der gleichen Farbe auf dieser Linie gibt, aber im zweiten Fall würde behind evt. nur Bauern zurücklassen (filtern), die dann ganz alleine auf der Linie sind (gegnerische Bauern werden nicht berücksichtigt), und diese werden dann alle als Einzelbauern gezählt. Diese Methodik mit der Filterung erlaubt mehr Einflußmöglichkeiten auf die Zählung als eine einfache Und-Verknüpfung.

Weitere Beispiele:

Alle weißen Bauern sind blockiert, d.h. jedem weißen Bauern steht ein schwarzer Bauer (möglicherweise entfernt) gegenüber.

Alle Bauern auf dem Damenflügel sind blockiert, d.h. jedem Bauern auf dem Damenflügel steht ein gegnerischer Bauer (möglicherweise entfernt) gegenüber.

Mindestens der Hälfte der weißen Bauern auf dem Damenflügel steht ein schwarzer Bauer direkt gegenüber (dies kann niemals zutreffen, wenn es keine weißen Bauern auf dem Damenflügel gibt).

(position
  :flipcolor
  :pawncount ♙ double-!advanced-compounds >=2)

Einer der Parteien hat mindestens zwei Doppelbauern, wobei keiner der betroffenen Bauern in der gegnerischen Hälfte steht.

Findet isolierte Trippelbauern auf verbundenen Feldern, wie in folgender Stellung:

8/p4pk1/8/2R1P1N1/6P1/6P1/2P2KP1/1r5r w - - 0 1

Die Alternative

wäre hier nicht das gewünschte, denn in diesem Fall werden beispielsweise auch Trippelbauern gezählt, die nicht allesamt miteinander verbunden sind, beispielsweise zwei isolierte Doppelbauern auf einer Linie. Wird jedoch

verwendet, dann werden zwar wieder hintereinanderstehende isolierte Trippelbauern gefunden, aber keine Stellungen mit mehr als drei hintereinanderstehenden isolierten Bauern. Aber in diesem speziellen Beispiel ist die folgende alternative Formulierung äquivalent zu isolated-consecutive(3):

Hier ist das Attribut triple redundant, macht aber die Sache einfacher lesbar.

Einer der Parteien hat mindestens einen rückständigen Bauern, der keinen gegnerischen Bauern auf der gleichen Linie vor ihm hat, aber von einem gegnerischen Bauer auf einer benachbarten Linie in direkter Weise am Vorücken gehindert wird.

Weiß hat hängende Bauern auf der vierten Reihe: ein Bauerduo (zwei Bauern nebeneinander auf einer Reihe), die sich auf halboffenen Linien befinden (d.h. sie sind nicht blockiert, aber auch keine Freibauern).

Schwarz hat nicht mehr auf beiden Flügeln Bauern aufzuweisen.

Schwarz hat alle seine Bauern entweder auf dem Damenflügel oder auf dem Königsflügel, aber nicht auf beiden Flügeln.

Siehe bei CQL-Beispiele für weiter Beispiele.

See also: :piececount, :pawncountdifference, :piececountdifference.

:pawncountdifference 

:pawncountdifference filtert Positionen, wenn die Differenz der Zählung von Bauern mit den spezifizierten Eigenschaften oder Strukturen innerhalb der gegebenen Bereichsangabe liegt. Dieses Schlüsselwort kann ein oder zwei Figurenbezeichner, die nur Bauern enthalten dürfen, als Argumente erhalten, gefolgt von einer bindestrich-separarierten Aufzählung von Eigenschaften, und als letztes Argument wird eine Bereichsangabe erwartet. Ist nur ein Figurenbezeichner gegeben, dann wird die Differenz des Resultats der Zählung der weißen Figuren im Figurenbezeichner minus dem Resultat der Zählung der schwarzen Figuren im Figurenbezeichner ermittelt. Bei der Angabe von zwei Figurenbezeichnern wird die Differenz des Resultats der Zählung des ersten Figurenbezeichners minus dem Resultat der Zählung des zweiten Figurenbezeichners ermittelt. Diese Differenz muß innerhalb der Bereichsangabe liegen, damit eine Position gefiltert wird.

Die unterstützen Bauerneigenschaften bzw. Bauernstruktureigenschaften sind die gleichen wie unter :pawncount.

Beispiele:

(position
  :pawncountdifference ♙[?5-7] ♟[?2-4] passed-lines >0)

Weiß hat mehr Freibauern, die in der gegnerischen Hälfte stehen, als Schwarz. Es werden hier jedoch für jede Farbe nur ein Freibauer pro Linie gezählt (in diesem speziellen Fall könnte statt lines auch forefront verwendet werden).

See also: :pawncount, :piececount, :piececountdifference.

:piececount

This keyword takes a piece designator argument followed by a range specifier. It matches the position if and only if the number of occurrences of the piece designator in the position is given by the range specifier.

Examples:

This will match any position with exactly two white rooks - a position with three white rooks would fail to match.

(position
  ♘d4
  :piececount [♖♜][a1-8] 1 3
  :piececount [♕♛][a-h8] 4)

This will match any position with a white knight on d4, between one and three rooks on the a file, and exactly four queens on the eight rank. Another way to write this position list is:

(position
  ♘d4
  :piececount [♖♜][a?] 1 3
  :piececount [♕♛][?8] 4)

:power

This keyword takes as argument a piece designator followed by a range specifier. It matches positions for which the total power of all pieces in the position matching the piece designator lies within the range specifier. The power of a piece is their chess material power, depending on the chess variant:

• 	♔	♕	♖	♗	♘	♙
  Normal Chess, Three-check Chess , King-of-the-Hill	0	9	5	3	3	1
  Crazyhouse, Bughouse Chess	0	5	3	3	3	1
  Losers	0	5	4	3	4	1
  Suicide, Giveaway	30	3	9	0	9	1

Examples:

This will match positions in which the total power of the black pieces on the board equals 6.

This will match positions in which the total power of the white pieces on the white half of the board is between 10 and 25 inclusive.

:powerdifference

This keyword takes as argument a piece designator followed by a range specifier. It matches positions in which the difference in power (⇒ :power) between the white and black pieces matching the piece designator (that is, the numeric value of the power of the matching black pieces subtracted from the power of the matching white pieces) lies within the range specifier.

A color flip by :flipcolor is negating the difference in power.

Examples:

This matches positions in which the white pieces have power precisely 4 greater than the black pieces.

This matches positions in which white has between one fewer and two more rooks than black.

This matches positions in which black is up at least an exchange.

(position
  :flipcolor
  :powerdifference [♖♜♗♝♘♞] <=-2)

This matches positions in which one side is up at least an exchange.

(match
  (position
    :result 1-0
    :sequence (
      (position
        :powerdifference [♕♛] <=-9
        :powerdifference ◑ <=-9)
      (position
        :run 12 (position
          :powerdifference [♕♛] <=-9)))
    :flipcolor))

This example shows a way how to search for queen sacrifices using :powerdifference. One side sacrifices a queen, and remains at least 9 pawns down in material for at least 12 moves, and finally wins.

See also: :powerdifference*.

:ray

A ray specifier is a list of piece designators. A ray is a contiguous set of squares on a straight line on the chessboard parallel to an axis, the a1-h1 diagonal, or the a8-h8 diagonal.

Let R by a ray with ordered set of squares in a contiguous line S₁, S₂, ..., S_n. Suppose a given ray specifier (G₁, G₂, ..., G_k) where each G is a piece designator. The ray R is valid with respect to the ray specifier if G₁ matches the piece on S₁, and if G_k matches the piece on S_n, and if the remaining G_i can be paired to some subset of the squares in the ray in an order-preserving way such that each G_i matches the piece on its corresponding square and such that all unpaired squares in the ray are empty.

The :ray keyword takes a ray specifier and an optional range specifier. If the range specifier is absent, it is taken to be >=1. Otherwise, :ray matches a position if the number of rays in the position valid with respect to the ray specifier lies within the range specifier.

Examples:

Will match a position in which a white queen attacks the black king.

Will match a position in which a white queen on the a file pins a black knight to the black king on the last four ranks.

Will match a position in which either three white queens and the black king are on the same rank, with exactly one empty square between them, and one of the queens is on the a-file, or a position in which the three white queens and black king form a diagonal with one empty squares between successive pieces, and the queens on the a, c, and e files in either cases.

Between two and for black knights are pinned to the black king.

See also: :rayattack.

:rayattack

Has the same syntax as :ray. It has the semantics of :ray, except that only orthogonal rays that start on a square containing a rook or queen are included, and only diagonal rays starting on a square containing a bishop or queen are included.

Examples:

Will match a position in which a black piece is pinned to the black king.

Will match positions in which there are three black pieces pinned by a white piece on d5 against either a black rook or king in the first four ranks.

Finds multiple-pin stalemates.

See also: :ray.

:raydiagonal

This keyword function exactly like :ray but the given rays are restricted to being diagonal. A diagonal ray is a ray that is not vertical or horizontal.

:rayhorizontal

This keyword function exactly like :ray but the given rays are restricted to being horizontal. A horizontal ray is a ray that is horizontal.

:rayorthogonal

This keyword function exactly like :ray but the given rays are restricted to being orthogonal. A orthogonal ray is a ray that is not diagonal.

:rayvertical

This keyword function exactly like :ray but the given rays are restricted to being vertical. A vertical ray is a ray that is vertical.

Move keywords

In a position, the next move is the move about to be played, if any. A move has three characteristics: its origin square designator, its destination square designator and its promotion designator. These refer respectivelyto the piece and square from which the piece moves; to the piece and square to which it is going to move (but before it actually moves there), and to the piece and square to which it promotes, if any. In chess variants Crazyhouse and Bughouse Chess there is a fourth characteristic: the piecedrop designator. It refers to the piecetype which will be dropped, if any.

For example, the destination designation of a white rook on a4 capturing a black knight on d4 is ♞d4, and its origin designation is ♖a4. The destination designation of a move to e4 that is not a capture is .e4.

:enpassant

The next move is an en-passant capture.

See also: :noenpassant

:halfmovenumber 

:halfmovenumber expects a range specifier as argument, and is matching a position only if the actual half move number is inside the given range. Inside of sub-variants this keyword has no effect and will always fail.

Examples:

This denotes the first position in the game (prior to first move). This is identical to:

As an extension also end, or end−N can be used as a range argument. Two examples:

This is matching the final position (after last move in game); see also :final.

Will match the third from last half move in the game, this means three half move will follow.

Match all games where a piece will be captured in the last move of the game. This is simpler and more efficient than this equivalent notation:

(position :sequence (
  (position :moveto ◑)
  (position :final))

The use of :halfmovenumber may reduce the search time considerably.

See also: :initial, :final, :movenumber.

:iscastling 

The next move is a castling move. As an optional argument the piece designators ♔, ♚, ♕, and ♛ will specify the castling more exactly.

Examples:

See also: :castling, :nocastling.

:movefrom

Takes a single parameter, a piece designator. It matches a move whose from designator matches that piece designator.

Examples:

Will match a position in which the next move is of a white rook on a3.

Will match a position in which the next move is of some piece on the 8th rank.

A white queen will be dropped on Black's back rank. (Crazyhouse, Bughouse Chess).

This expression is useful in Crazyhouse, and Bughouse Chess: in this position no piece (from backhand) will be dropped.

This can never match, even a piece drop move (Crazyhouse, Bughouse Chess) will not match.

See also: :line, :moveto, :null, :promote.

:movenumber

:movenumber takes a range specifier as parameter and matches positions only if the current move number is within the specified range. The move number computation assumes white moves first.

Examples:

Will match a position in which there is a check between moves 10 and 20.

Will match a position in which move 35 is mate.

As an extension (to the CQL standard) also end, or end−N can be used as an argument for the range. But the behaviour is undefined when the search inside sub-variations is switched on (⇒ :variations), this means that this extension shouldn't be used in such cases. Two examples:

This denotes the final position (after last move in game); see also :final.

This denotes the third to last move in the game (do not confuse this with half moves; see siehe :halfmovenumber).

This denotes the range from fourth to last until third to last move in the game.

See also: :halfmovenumber, :initial, :final.

:moveto

Takes a single parameter, a piece designator. It matches a move whose destination designator matches its parameter.

Examples:

Is matching a position where next move is a capture move.

Is matching a position where next move is not a capture move.

Will match a position in which the next move is to capture a white rook on the b file. Note that this is quite different from the natural PGN  interpration of its being a move of a white rook to the b file. That would be done via:

Will match a move of the white rook to the b file. This excludes a rook from backhand (Crazyhouse, and Bughouse Chess). If a piece from backhand should be included, we need an extended definition:

In next case we will handle an en passant capture:

A pawn on e5 will be captured en passant.

See also: :line, :movefrom, :null, :promote.

:nocastling 

The next move is not a castling move.

See also: :castling, :iscastling.

:noenpassant

The next move is not an en-passant capture.

See also: :enpassant.

:null 

The next move is a null move.

Match all games containing a null move.

See also: :line, :movefrom, :moveto, :promote.

:promote

Takes a single parameter, a piece designator. It matches a move if that move is a promotion whose promotion designator matches its parameter.

Examples:

Will match a position whose next move is a white underpromotion.

Will match a position whose next move is a white promotion to bishop or knight.

Will match a position in which the next move is of a pawn on f7 capturing a black queen on e8 and promoting to a rook.

Will match a position in which the next move is not a promotion (because the piecetype designator is empty).

See also: :line, :movefrom, :moveto, :null.

Sequence keywords

:gappedsequence

Takes one argument, a list of position lists. A position list A is said to be a refinement of a position list B if A may be formed from B by inserting zero or more position lists of the form (position) into the top level of B. For example:

refines

because it was formed by inserting a single position list into the latter list.

A :gappedsequence with argument B will match a position if and only if there is a refinement A of B such that a :sequence with argument A would match that position. That is, :gappedsequence is like :sequence except that the sequence of matching positions may include intervening positions from the game.

Examples:

(position
  :gappedsequence (
    (position :movefrom ♖a3)
    (position :movefrom ♖b4)))

This will match any position for which the positions that occur successively in the game starting with that position comprise zero or more positions, followed by a position from which a white rook on a3 moves, followed by zero or more positions, followed by a position from which a white rook on b4 moves.

Standard CQL has the following limitation: The total number of :sequence and :gappedsequence position lists that can occur at the top level of a position list cannot exceed one. To get the effect of either a :gappedequence and :sequence keywords in one position list, use :and. But CQL-S does not have any limitations with the use of :sequence and :gappedsequence.

:line 

The argument is a string which contains a valid line. The long algebraic notation has to be used. It is allowed to use piece and square designators. Note that a pawn move will be assumed if the piece of the from square is not specified. Furthermore check and mate signs can be used. Moreover a pawn move may be designated as an en-passant move. Optional move numbers will be considered when searching, the move numbers have to be strictly ascending. Examples:

This keywords serves for a simpler notation of move sequences. Therefore the position list

(position :line "e2-e4 e7-e6 d2-d4 d7-d5")

is identical to the following sequenc:

(position :sequence (
  (position :movefrom Pe2 :moveto e4)
  (position :movefrom pe7 :moveto e6)
  (position :movefrom Pd2 :moveto d4)
  (position :movefrom pd7 :moveto d5)))

The special letter * at the end of the string is denoting a transposition invariant search, and the search will start automatically with the first move in the current start position. Moreover possible en passant rights will be ignored. Example:

(position :line "e2-e4 e7-e6 d2-d4 d7-d5 *")

Match all positions starting with French, inclusive move transpositions like "d2-d4 d7-d5 e2-e4 e7-e6". In games with a normal start position (position 518 in Chess960) this equivalent to the following query:

(position
  :fen "rnbqkbnr/pppp1ppp/4p3/8/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2")

If the exact opening line "e2-e4 e7-e6 d2-d4 d7-d5" should be found, the following query has to be used:

(position :line "1.e2-e4 e7-e6 2.d2-d4 d7-d5")

See also: :fen, :sequence.

:sequence

Takes a single argument that is a list of position lists. It will match a given position if and only successive occurring positions, beginning with the current position, match each corresponding element in its argument.

Example:

(position
  ♖e8
  :sequence (
    (position ♕f3 .g2)
    (position .f3 ♕g2)))

This position list will match exactly those positions with a white rook on e8 such that:

1. In that position, white has a queen on f3 and g2 is empty, and
2. After the next move, f3 is empty and there is a white queen on g2.

In consequence, this position list is identical in effect to

Furthermore this is identical to:

The following more typical usage of :sequence will search for all queen staircase checking maneuvers by either side:

(position
  :shift :flip :flipcolor
  :sequence (
    (position :movefrom ♕a2)
    (position :check)
    (position :movefrom ♕b2)
    (position :check)
    (position :movefrom ♕b3)
    (position :check)
    (position :movefrom ♕c3)
    (position :check)
    (position :movefrom ♕c4)
    (position :check)))

This position list will match any position with a white queen on a2 for which there are successively moves by queens on the indicated squares giving check; the :shift, :flip, and :flipcolor search for this variation reflected or rotated anywhere on the board. But this can be expressed much simpler:

(position
  :shift :flip :flipcolor
  :line "♕a2-b2+ ♕b2-b3+ ♕b3-c3+ ♕c3-c4+")

See also: :line.

Game related keywords

Several keywords relate to the game parameters and are not affected by the contents of the position; they are included as position list keywords instead of match list keywords so the :flipcolor can be used with them. these are:

:blackelo

This keyword takes a range specifier; the ELO of the black player must lie within its range. One special case:

In this case all games will match whose black player does not have an ELO rating.

See also: :whiteelo, :blackrating, :whiterating.

:blackrating 

Match all games where the specified rating score of black player is between given range. For a detailed description see :rating (match) : match.

See also: :blackelo, :blackrating, :whiterating.

:elo

This keyword is supported only due to compatibility reasons with the CQL standard. It is recommended to use instead the identically named keyword :elo : match in the match list. For a description also see :elo : match.

:ischess960 

Matches all games starting with a Chess960 Position. This includes the standard start position 518.

See also: :ischess960 : match, :isshufflechess.

:isshufflechess 

Matches all games starting with a Shuffle Chess Position. This includes all Chess960 positions.

See also: :isshufflechess : match, :ischess960.

:result

This keyword takes one argument, the same as the argument to :result (match) : match in a match list. Inside a position list it will be affected by :flipcolor.

Example:

(match (
  (position
    :result 1-0
    :whiteelo 0 2300
    :blackelo >=2600
    :flipcolor))

Searches for games in which a 2300 player or below defeated a 2600 player or above.

:startposition 

This will take a comma-separated list of start positions. A start position is either a position number, or a FICS variant identifier. For a detailed description see :startposition : match.

See also: :ischess960, :isshufflechess.

:variant

For a description see identically named keyword :variant (match) : match in match list. This keyword is added for the possibility to distinguish between different chess variants in each position list.

:whiteelo

This keyword takes a range specifier; the ELO of the white player must lie within its range. One special case:

In this case all games will match whose white player does not have an ELO rating.

See also: :blackelo, :blackrating, :whiterating.

:whiterating 

Match all games where the specified rating score of white player is between given range. For a detailed description see :rating (match) : match.

See also: :blackelo, :blackrating, :whiteelo.

Relation between positions

:relation

Takes one argument, a relation specification. is used to search for games with pairs of positions P1 and P2 that satisfy certain properties. See relation list for a desription of the relation specification keywords.

Matching count keywords

Two keywords pertain to the number of positions which a position list matches. These each take a range specifier as parameter. They can only be used in a position list at the top level of a match list.

:checkcount 

If the parameter is a single number (between 0 and 3 is allowed), it is matching all positions where last move is giving n-th check to other side.

If the parameter has the form +<n1>+<n2>, where <ni> is a number between 0 and 3, it is matching first position where white has given n₁ times check to black, and black has given n₂ times check to white.

This query is working only in chess variant Three-check Chess, in other chess variants it fails always (except all values in given parameter are zero).

Examples:

Match as soon as any side has given second check.

Match if black has given third check to white king. This must be a final position.

This is in fact a useful query. Assume that a game is starting with the following position (described with Forsyth-Edwards Notation):

• rnb1k1nr/pppp1ppp/8/4p3/3PP2q/2N5/PP3PPP/R1BQKBNR w KQkq - 1 5 +0+2

This game would match (note keyword :not), because black has already given second check to white king. With other words, this query is searching for games starting with an advanced position, where one side has already given a check.

:matchcount

Will match if and only if the number of times this position list matches a position in the current game lies within the range specifier.

Example:

Will match any game in which at least four queen captures have occurred.

:pretransformmatchcount

Has the same syntax as :matchcount. For a description of this keyword we will suppose the following general form of a position list:

(position
  T1 T2 ... Tk
  X1 X2 ... Xn
  :pretransformmatchcount n1 n2)

All Ti are denoting the transformation keywords, and all other elements (but no transformation keywords) are denoted with Xi. n1 n2 is the range specifier. Now we suppose that Yi,j is denoting an element formed by one transformation step j applied to Xi (possibly identical to Xi because it is transformation-invariant). m denotes the total count of all transformation steps. Now we will form a new position list:

(position
  :or (
    (position Y1,1 Y2,1 ... Yn,1 :matchcount n1 n2)
    (position Y1,2 Y2,2 ... Yn,2 :matchcount n1 n2)
    ...
    (position Y1,m Y2,m ... Yn,m :matchcount n1 n2)))

The position list containing :pretransformmatchcount is matching exactly those positions matched from our newly formed position list. With other words: the match count will be performed for each individual transformation step.

Example:

(position
  :moveto [Aa]d4
  :pretransformmatchcount >=12
  :shift))

This would match any game in which at least 12 captures occur on the same square. Were the :pretransformmatchcount replaced by :matchcount, the position list would match games in which at least 12 captures occurred anywhere on board.

Analyzing keywords

The following keywords are analyzing positions. :evaluation and :moveevaluation should be used with care, these are very slow operations. In some cases the keywords :exchangeevaluation and :maxswapevaluation might be an alternative, these functions are quite faster, although fairly time consuming.

:evaluation 

This is a very slow operation and should be used with restrictions.

This keyword is evaluating the current position with the help of an external chess engine. The first two parameter are specifying the computation mode:

• depth <d>	search <d> plies only
  movetime <ms>	search exactly <ms> milli-seconds per move

Now you can either specify a search for mate, or a search for position evaluation.

A search for mate expects one more parameter: namely the word mate. A query is successful if a mate has been found.

The search for position evaluation is expecting three additional parameters. The first one denotes the lower bound, the second one denotes the upper bound, both scores are in pawn units. The query succeeds if the evaluation of the position is within the specified bounds (inclusive the ranges). If the lower-bound value is specified with unlimited, it means negative unlimited. If the upper-bound value is specified with unlimited, it means positive unlimited. The third parameter is either sidetomove or absolute. sidetomove means that the evaluation value depends on side to move, and absolute means that the evaluation value is independent from side to move.

Please note that in mode movetime the specification of the milli-seconds will be rounded up to centi-seconds if the engine is restricted to WinBoard/XBoard protocol. If the UCI protocol is available then the exact number of milli-seconds will be used.

Examples:

Side to move has (probably) a winning position, because he is at least 2.5 pawn units ahead.

Side to move has (probably) a losing position, because he is at least 2.5 pawn units behind.

Black is (probably) losing, because he is at least 3 pawn units behind.

Either side can be mated in maximal 3 moves (6 plies).

:exchangeevaluation 

This keyword is analyzing capture moves to see whether or not they appear to be profitable.

The keyword will match the current move if this value is in the specified range, a lower and an upper value in pawn units. Only capture moves will be evaluated. If lower range is specified with unlimited, it means negative unlimited. If the lower range is specified with unlimited, it means positive unlimited. The evaluation function is taking into account that pieces may be pinned or defended by other pieces. The value of the function does not depend on which side is to move.

Concerning the piece values see :power.

Note that this function is not evaluating the position, instead it is estimating the exchange values.

Example:

This capture move is (probably) a blunder.

:maxswapevaluation 

This keyword allows to estimate exchange values of possible moves. It takes as arguments two piece designators followed by a range specifier. The first argument specifies moving pieces, the second one specifies target squares. For each possible moves we compute an integer value that is a material benefit of the move (in pawns, like in case of the :power keyword) according to possible piece exchanges on the target square after the move. After that the maximum of all computed values will be selected.

The keyword match the position if this value lies in the specified range (a lower and an upper value). If lower range is specified with unlimited, it means negative unlimited. If the lower range is specified with unlimited, it means positive unlimited. The evaluation function is taking into account that pieces may be pinned or defended by other pieces. The value of the function does not depend on which side is to move.

Concerning the piece values see :power.

Note that this function is not evaluating the position, instead it is estimating the exchange values.

This keyword is alike the keyword :maxswapvalue from Chess Assistant 9 (⇒ The CQL 3.GX Extension ), but quite different implemented.

Examples:

This query selects positions in which white threatens with winning some material.

This query selects positions in which a white queen can invade rank 8 without a material loss.

:moveevaluation 

This is a very slow operation and should be used with restrictions.

This keyword is matching the difference between the evaluation of the current position and the evaluation of the preceding position. The evaluation will be done with the help of an external chess engine. It takes seven parameters. The first and second parameter are piece designators. The former is specifies moving pieces, the second one specifies target squares. The third and fourth are specifiying the computation mode:

• depth <d>	search <d> plies only
  movetime <ms>	search exactly <ms> milli-seconds per move

The fifth parameter denotes the lower bound score, the sixth parameter denotes the upper bound score, both scores are in pawns units. If the lower-bound value is specified with unlimited, it means negative unlimited. If the upper-bound value is specified with unlimited, it means positive unlimited. The query succeeds if the scoring of preceding move is within the given bounds (inclusive the ranges). The score of preceding move is the difference between the score of the current position minus the score of the preceding position. In case of mating positions the difference will be always greater than 10,000.

The seventh parameter is either sidetomove or absolute. sidetomove means that the evaluation value depends on side to move, and absolute means that the evaluation value is independent from side to move.

Please note that in mode movetime the specification of the milli-seconds will be rounded up to centi-seconds if the engine is restricted to WinBoard/XBoard protocol. If the UCI protocol is available then the exact number of milli-seconds will be used.

Examples:

Match first position were the score difference is at least 3.0 pawn units. This means that last move was (probably) a blunder.

Match first position were the evaluation difference is at least 3.0 pawn units better for black. This means that last white move was (probably) a blunder. Only capture moves were evaluated.

(match
  (position :moveevaluation [♙♟] ?[?1,?8]
             <=0.0 movetime 5000 absolute)
  (position :promotion ◑ :cut)))
  (position :preceding)

Search for positions where side to move is doing first promotion in game, but without gaining a better score. We have ensured that only promoting moves will be evaluated.

Accumulator keywords

There are mainly two accumulator keywords, :accumulate and :sumrange. These are used to accumulate and to test the number of transforms of the enclosing position list that match the current position. Each time a transform of a position list matches a position, the accumulator associated with that position is incremented. Any position with a sum range can then test if the accumulator is within a certain range.

:accumulate

This takes one parameter, the name of an accumulator. Each time the application of some element of the transform set of the position list matches a position, the accumulator associated with this name is incremented. The accumulator is cleared when a new position is reached. In consequence :accumulate should not be used inside of :not, or the :sequence and :gappedsequence keywords). Note that :flipcolor likely has unexpected results when used with :accumulate, because the accumulator is not cleared between color flips.

For examples see: Using accumulators to count passed pawns.

See also: :accumulate*

:accumulate* 

To use the accumulation combined with :flipcolor CQL-S provides an extension: in the case variant :accumulate* is used, each color will be counted separately.

For an example see: Using accumulators to count passed pawns.

See also: :accumulate

:reset 

This keyword takes as a parameter the name of an accumulator. It clears the accumulator associated with this name after applying a transformation. If variant variant :accumulate* is used, color flips (by :flipcolor) will not be reseted.

Example:

Tripled pawns can be found by the query:

(position
  :reset acc
  ♙e2
  :flipcolor
  :accumulate* acc
  :sumrange acc 3
  :shiftvertical
  :shifthorizontal)

Note that this is only an example for the use of this keyword (taken from The CQL 3.GX Extension ), it is not recommended to use this statement for triple pawn search. A much better way is:

(position
  :piececount ♙d[2-7] 3 6
  :shifthorizontal
  :flipcolor))

:sumrange 

This takes as parameter the name of an accumulator and a range specifier. It matches a position if the value of the given accumulator lies within the range specifier. If variant :accumulate* is used, :sumrange will distinguish between colors automatically.

For examples see: Using accumulators to count passed pawns.

Tagging keywords

:tagmatch 

The :tagmatch keyword takes two parameters, the name of a tag and a piece designator. It matches only if the piece corresponding to the named tag matches the given piece designator. For more information, see the section on tagging.

Controlling keywords

With the help of controlling keywords the search flow or search result will be affected. Actually none of these keywords is extending the capability of CQL, each of them can be replaced, but the use of these keywords may improve the search time considerably, and the expression may have a clearer form.

:cut 

This keyword can be used in two forms: either it is included in a position match list, or it has a sub-position list as argument. In former case: stop position search for this game as soon as the match of the containing position list succeeds. In latter case: stop position search of this game as soon as the match of the sub-position list succeeds. This keyword is never failing, with other words: it is not influencing the result of all other matches.

The :cut position match has lower precedence than all other position matches. This means that a position is matching, if all other position lists are matching this position, independent from the result of the :cut. If the :cut position match should have highest precedende, use keyword :preceding. In this case the search will stop with a negative result, independent from all other matches. Consider the following examples:

Suppose <A> and <B> is matching a position, either the first time. In this case the match of this game succeeds.

Suppose <A> and <B> is matching a position, either the first time. In this case the match of this game fails.

Examples:

(match
  (position
    :mate
    :cut (position :check)))

Search for games ending with mate, and neither side has ever given a check before. Actually keyword :cut is not required for this search criterion, see next example:

(match
  (position :mate)
  (position :check :matchcount 1))

But this version has to search the whole game, and the former version with :cut fails as soon as first check occurs. In complex searches the use of keyword :cut may be much faster than the use of :matchcount.

:exclude 

This keyword can be used in two forms: either it is included in a position match list, or it has a sub-position list as argument. In former case: exclude this game if the match of the containing position list succeeds. In latter case exclude this game if the match of the sub-position list succeeds. This keyword is not influencing the result of the position match (see example).

This keyword will exclude games even if one of the position matches will succeed before the :exclude expression is succeeding. In short: this keyword is excluding games completely under certain conditions.

Example:

(match
  (position
    <A>
    :exclude (position <B>)))

Search for games containg a position which is matching expression <A>, but not if expression <B> is matching any position in this game. Actually this match can be written without the use of keyword :exclude, in the following way:

(match
  (position
    :and (
      (position <A>)
      (position <B> :matchcount 0))))

But the use of keyword :exclude is simpler and clearer.

:following 

This keyword gives the following position of a match, if any. This means that the final position of a game cannot be found anymore, because it has no successor. The keyword :following can be used only on top level.

Example:

If a position with a knight on d4 will be found, give the successing position as a result.

:preceding 

This keyword gives the preceding position of a match, if any. If the start position is matching, the match of this position will be ignored, and the search is continuing. The keyword :preceding can be used only on top level.

This keyword has a special meaning if combined with keyword :cut (⇒ :cut).

Examples:

The result of this match is the predecessor of first position where one side has given a check. Of course this can be expressed without this keyword:

But the usage of :preceding is easier and the search is faster.

:skip 

With the help of this keyword a matching position can be skipped. This could be expressed without the use of this keyword, but the formulation of the position list with the help of this keyword is sometimes less complicated, and this results often in a faster search.

:markall

This keyword is supported to be compatible with CQL standard, and does not have any meaning in CQL-S.

:noannotate

This keyword is supported to be compatible with CQL standard, and does not have any meaning in CQL-S.