index Back to help overview   home Back to home page

CQL Syntax

A CQL script has the following generic structure: 

(match
  (position ... )
  (position ... )
  (position ... )
  ...)

In this example, the "..." represent various keywords and commands to be defined below.

For example, here is a simple CQL script to find quadrupled pawns, but only in games played in year 2013: 

(match
  :year 2013
  (position
    :pawncount consecutive(4) >0
    :flipcolor))

In order to understand the format of CQL, some basic syntactic terminology will be defined.

A list is a finite sequence of items, separated by whitespace, and enclosed in parentheses. Each item is either a string of characters without whitespace or another list.

For example

(position :shifthorizontal :flipcolor)

is a list whose three elements are the strings "position", ":shifthorizontal", and ":flipcolor".

Similarly, the list beginning with "(match" above has six elements, the last of which is itself a list containing six elements whose first element is "position" and whose last element is ":flipcolor".

A keyword is a string beginning with ":". For example, the match list above has keyword :year.

A keyword parameter is a list or string immediately following a keyword that accepts a keyword parameter. Some keywords accept multiple parameters, one after the other.

Example of keyword parameter

In the list 

(match
  (position
    :pawncount consecutive(4) >0
    :flipcolor))

:pawncount has keyword parameters consecutive(4) and >0. The other keywords :shifthorizontal and :flipcolor do not take keyword parameters. A list whose first element is "match" is called a match list and defines a match filter.

A list whose first element is "position" is called a position list and defines a position filter.

Overall functioning of CQL

To determine whether a match filter matches a game, CQL acts as follows. Each of the position filters defined in the match filter is applied to the start position. (The CQL standard omits the start position). Next It plays through each move in the game, optionally descending as well into the variations. Each time a position is reached, again each of the position filters is applied to that position.

Example: In a 40 move game in which white makes the first move and black the last move, if there are no variations then CQL will examine exactly 81 positions in the game, inclusive the start positions. (The CQL standard omits the start position).

If each of the position filters in the match filter match some position in the game, then the match filter is said to match the game.

The simplest position filter is defined by the simplest position list:

(position)

This position filter matches every position. Hence, the following CQL script simply selects all games:

(match (position))

In CQL-S this script can be written even more simpler, because in CQL-S, different from CQL standard, the match list must not contain position lists:

(match)

Comments in a CQL script

Any characters following a semicolon are ignored in a CQL script. Example: 

; A CQL script that matches all games
(match
  (position) ; a position filter matching anything
)

Some basic elements