-gui

When CQL is invoked with the -gui option, it outputs additional information that might be useful to developers who want to interface CQL with their own GUI. We envision CQL invoked as a separate process with its stdout read by the calling process.

Ordinarly, CQL outputs all messages to stdout.

Any line beginning with the string <CqlGui indicates a message intended for the invoking process.

A line beginning with the string <CqlGuiMessage> brackets an informational message intended to be seen by the end user. The string bracketed by </CqlGuiMessage>, which may span multiple lines, forms this information message.

A line beginning with the string <CqlGuiError> brackets an error message intended to be seen by the end user. The error message, which may span multiple lines, is terminated by </CqlGuiError>. This message is followed by program termination (via exit(1)). After a CqlGuiError message is sent, any following output is invalid and should be ignored (it may be due to other CQL threads reporting their own errors).

A line beginning with <CqlGuiNormalExit> indicates normal termination and is followed by exit with return value of 0 via exit(0).

A line beginning with <CqlGuiVariable> is followed by a space and a property name and a space and a property value. The property name is a nonempty sequence of alphanumeric characters. The property value is a nonempty string beginning following the space following the last character of the property name and ending at the end of the line.

Valid property names are defined in the following table:

property namevalue
versionversion number of CQL binary
buildbuild number of CQL binary
linenumbererrorline number in CQL file where error occurred (actual error message via CqlGuiError will be two lines below on stdout)
columnnumbererrorcolumn number in line indicated by previous linenumbererror in which error occurred (actual error message via CqlGuiError will be on the next line of stdout)
numbermatchesnumber of games matched at end
numbergamesexaminednumber of input games examined at end
secondstime elapsed in seconds at end
numberthreadsnumber of threads used
outputfilename of output file
currentgamenumbernumber of current game being examined

Where a linenumbererror and columnnumbererror are reported and nonzero, they should be indicated to the user in some way. CQL 6 has a more complex syntax than previous CQL versions, and these error location values are important aids in using CQL.

The current game number is by default output every 1000 games and may be changed by using the -lineincrement option to cql (to output every x games, set -lineincrement to 10 * x ).

-guipgnstdin

If the -guipgnstdin option is specified on the command line, the input PGN is read from standard input. This option overrides any input parameter in the CQL header. This option may not be combined with the -i or -input command line options.

-guipgnstdout

If the -guipgnstdout option is specified on the command line, the output PGN is written to standard output. The output PGN is preceded by a line of the form

  <CqlGuiPgn numbergames=x numberbytes=y>
where x and y are nonnegative integers. There is no space between these integers and the preceding = sign.

This PGN output is followed by the line

</CqlGuiPgn>

In the above, x denotes the number of games in the PGN output. y is the number of bytes in the output PGN. Both are exclusive of the lines containing these <CqlGuiPgn...> and </CqlGuiPgn> lines.

This option overrides any output parameter in the CQL header. This option may not be combined with the -o or -output command line options.