index Back to help overview   home Back to home page

CQL File Format

All .cqls files have in their first lines an identifier with a version number. Just behind this identifier there is a parenthesized comma-separated list, enumerating all chess variants intended for this script. A second parenthesized comma-separated is following, enumerating all chess variants which must be supported by the application in order to execute the script. The first line is mandatory.

The first line in a .cqls file may look like:

; CQL-S 1.0 (normal,threecheck) (normal)

The first 11 characters can be used by third party applications for the detection of the file type.

These are the supported chess variants:

normal Normal Chess
threecheck Three-check Chess
kingonthehill King-of-the-Hill
crazyhouse Crazyhouse
suicide Suicide
giveaway Giveaway
losers Losers

Immediately after an additional blank line Scidb is writing the creator (the application), the author, and the date: 

; Creator: Scidb 1.0
; Author:  NobodyKnowsMe
; Date:    2014/11/18

In next lines, after a blank line, an optional description of the script may follow. This description will be multilingual any may look like this: 

; Description (en): Smothered Mate
; This ingenious script ...
;
; Description (de): Ersticktes Matt
; Dieses grandiose Skript ...

With a similar format also the standard CQL scripts will be written by Scidb, in this case the file suffix is .cql. But the chess variants are not supported in standard CQL. Example for the first line:

; CQL 1.0

In this case the first 9 characters can be used for file type detection. Currently only Scidb is writing this identifier.

All CQL and CQL-S scripts are UTF-8 encoded.

This is the Backus-Naur description of a CQL file: 

<CQL-Header>     ::= <Identification> <LF> <Creator> <Author>
                     <Date> <LF> <Descriptions> <Body>
<Identification> ::= <Id-CQL-S> | <Id-CQL>
<Id-CQL>         ::= ";␣CQL␣" <Version>
<Id-CQL-S>       ::= ";␣CQL-S␣" <Version> "␣" <Variants> "␣" <Variants>
<Version>        ::= <Digit> "." <Digit>
<Variants>       ::= "(" <Variant> ( "," <Variant> )* ")"
<Creator>        ::= "Creator:" <Spaces> <UTF-8-String> <LF>
<Author>         ::= "Author:" <Spaces> <UTF-8-String> <LF>
<Date>           ::= "Date:" <Spaces> <YYYY/MM/DD> <LF>
<Descriptions>   ::= ( <Description> <LF>* )*
<Description>    ::= "Description␣(" <ISO-639-1> "):" <Spaces>
                     <Title> <LF> ( <CommentLine> )*
<Title>          ::= <UTF-8-String>
<CommentLine>    ::= ";" ( <Spaces> <UTF-8-String> )? ( <LF> )+
<Spaces>         ::= ( <SpaceOrTab> )*

The line break <LF> is dependent from the operating system where the application is running (modern editors should recognize all types of line breaks). Instead of ISO-639-1 for the language code the alternative ISO-639-2 can be used, but only when unavoidable.

This is an example for a complete script: 

; CQL-S 1.0 (normal,threecheck,king-of-the-hill,crazyhouse,bughouse,losers) (normal)

; Creator: Scidb 1.0
; Author:  Gregor Cramer
; Date:    2014/06/24

; Description (en): Smothered Mate
; A smothered mate is a checkmate delivered by a knight
; in which the mated king is unable to move because he is
; surrounded (or smothered) by his own pieces.

; Description (de): Ersticktes Matt
; Ein ersticktes Matt liegt vor, wenn ein Springer Matt
; setzt und der König nicht entweichen kann, weil er
; von eigenen Figuren umgeben (erstickt) ist.

(match
  (position
    flipcolor            ; either color
    attackcount k [A.] 0 ; king is smothered by own pieces
    btm                  ; black to move
    mate))               ; and is mate