QQqq.cql

The CQL file QQqq.cql is a simple introduction to CQL that illustrates some basic features.

running CQL

You should first of all have CQL installed and know how to run CQL. You can download the QQqq.cql example from this link or you can see in the examples directory of the main CQL distribution.

Suppose we run the file. From the command line we can run

cql -i sample.pgn QQqq.cql

The effect of this will be to run QQqq.cql on each position in each game in the pgn file sample.pgn.

Any time a position in such a game matches the CQL file QQqq.cql, the game itself will be output to the output file QQqq-out.pgn.

QQqq.cql line by line

The first line (ignoring comments) is

cql(input hhdbvi.pgn)

This tells CQL that the file is in fact a CQL file and that, by default, the input pgn file containg games to be searched is in the file hhdbvi.pgn. This is the PGN consisting of Harold van der Heijden's file of studies, see Heijden database VI interface.

The next line is the first line of the body of the CQL file, which contains the series of assertions that will be run against each position of the current game being searched. This line is:

♕==♛==2

Intuitively, this will match any position with exactly two white queens and two black queens. It is equivalent to the two lines:

      ♕==2
      ♛==2

Now, one might think that ♕==2 simply means "a position with exactly two white queens." And in a sense that description is accurate.

But more precisely, the symbol ♕ is a piece designator which denotes a set of squares. In this case, ♕ is the piece designator that is the set of squares on which there is a white queen in the current position. (The currentposition is the position being looked at by CQL).

For example, if there were white queens on d4 and e8, then ♕ would stand for a set with two squares in it, d4 and e8.

Given any set of squares at all in CQL, say x, the expression

      #x

is the number of squares in x. Thus,

      #♕

would has a numeric value equal to the number of white queens in the current position.

Finally, if x is any set, then

x == 2

is shorthand for

#x == 2

.

Thus,

♕==2

means

#♕==2

which is true if the set of squares containing white queens has exactly two elements, i.e., that there are two white queens in the current position.

Similarly, ♛==2 is true if there are two black queens in the current positions.

The last line of the body is

  ◭==6

Here, ◭ is a special symbol that means any piece, white or black. more exactly, ◭ is a piece designator that represents the set of squares containing a piece (or pawn).

summary

The body of the CQL file QQqq.cql contains two filters. A filter is an expression that is true or false of any particular position.

The first filter is

♕==♛==2

which is true when there are exactly two black queens and exactly two white queens in the current position.

The second filter is

◭==6

which is true if there are exactly 6 pieces in the position.

A CQL file matches a position if each filter in the body of that CQL file matches the position. The body of QQqq.cql will match any position with 6 total pieces, two of which are white queens and two of which are black queens.

If a game has a position (in the main line) that matches such a position, the game will be output to QQqq-out.cql. In addition, there will be PGN annotations added to each matching position in this matching game. The annotation will be just the single comment CQL although this can be changed in many ways.