QQqq.cqlThe CQL file QQqq.cql is a simple introduction to CQL that illustrates some basic features.
running CQLYou 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.cqlThe effect of this will be to run
QQqq.cql on each position in each game in the pgn file
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.cql line by lineThe 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:
Intuitively, this will match any position with exactly two white queens and two black queens. It is equivalent to the two lines:
♕==2 ♛==2Now, 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
♕ would stand for a set with two squares in it,
Given any set of squares at all in CQL, say
x, the expression
#xis the number of squares in
would has a numeric value equal to the number of white queens in the current position.
x is any set, then
x == 2is shorthand for
#x == 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.
♛==2 is true if there are two black queens in the current positions.
The last line of the body is
◭ 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).
summaryThe 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
♕==♛==2which is true when there are exactly two black queens and exactly two white queens in the current position.
The second filter is
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.