Revision History
Changes in Version 1.0.6 (February 10, 2026)
- The new
cqlbeginandcqlendfilters can be used to perform actions at the start and end of processing. - The new
--noclobberoption may be used to prevent CQLi from overwriting existing output files. - The new
--createdirectoriesoption may be used to create non-existent directories specified in the name of output PGN files. - The new
--maxopenoutputfilesoption can be used to limit how many output PGN files are open at a time. - The version information displayed when using the
--versionoption now includes the build date and the version of ICU4C that is statically linked to CQLi. - The presence of multiple
-a/-ooptions on the command line is now diagnosed as an error.
Changes in Version 1.0.5 (December 24, 2025)
New Features
- The “Dynamic Output File Specifiers” feature allows matching games to be split across multiple output files based on user-defined criteria.
- The new
--dryrunoption can be used to show the files that would have been created without actually creating them. - The new
replacefilter supports replacing portions of a string that match a provided regular expression. - Dictionary Variables can now be declared to have keys and values of Numeric and Set type in addition to String type.
- Compound assignment and conditional set assignment can be used with dictionaries.
- The new
keyfilter is used to iterate over non-String dictionary keys.
General Improvements
- Some Set filters (including
dark,light,attacks,attackedby, and the set operators&,|, and~) would previously yield a value ofNonewhen provided with an argument with theNonevalue. Outside of variable access filters (which yieldNonefor unbound variables or non-existent dictionary elements), set filters now consistently yield the empty set ([]) when they do not match the position. - Several Boolean filters (including
ancestor/descendant,echo,in, andsettag) would previously yield a value ofNoneinstead offalsein certain situations. Additionally, a Boolean compound filter ({ ... }with a Boolean terminating filter) would yieldNoneinstead offalseif any of its constituent filters failed to match the position. WhileNoneandfalseare treated identically in almost every context, noticeable inconsistencies could occur when the value of one of these filters was converted to a string via thestr,comment, ormessagefilters. Boolean filters will now consistently yield the valuefalsewhen they do not match the position. - The
legalpositionfilter previously incorrectly evaluated tofalsefor positions where a King resided on a square it could not have reached without passing through check by an opposing pawn. Such positions will now only be diagnosed by thereachablepositionfilter. - The
reachablepositionfilter had the potential to incorrectly deduce a rook was impossibly positioned when there were adjacent pawns on the third rank that could have swapped files via captures, resulting in a previously open file that would have allowed rook traversal. This scenario is now properly handled. - The
reachablepositionfilter now detects impossible escaped promoted rooks when all of the opposing side’s pawns are on ranks 2-3/6-7. - The
reachablepositionfilter now detects additional situations in which a King resides on a square it could not have reached without passing through check by an opposing pawn. - The
reachablepositionfilter can now detect situations in which a Rook is impossibly trapped on the second rank by a Bishop and Pawns.
HHDB Improvements
- Added support for the newly-released HHdbVII database including:
- Added the
--viioption. - Updated the
hhdb composerandhhdb stipulationcommands to support the conventions used by HHdbVII. - Updated the
hhdb "(c)",hhdb "(m)",hhdb "(s)", andhhdb "(v)"commands to support the format used to represent these attributes in HHdbVII. - Added the command aliases
hhdb C,hhdb M,hhdb S, andhhdb V. - Included an Examples section to demonstrate how to accomplish the searches discussed in the HHdbVII documentation with CQLi.
- Added the new
hhdb CE/hhdb computer_based_endingandhhdb MR/hhdb material_restrictioncommands to support new study attributes available in HHdbVII. - Updated references and statistics as appropriate.
- Added the
- Updated the behavior of
hhdb composerto better handle inconsistencies in HHdbVI.
Changes in Version 1.0.4 (September 27, 2024)
- Added the new
--nosortoption which writes matching games immediately instead of storing them in memory until processing is complete. - Previously, games containing very long lines (thousands of moves) could cause CQLi to crash. This issue has been corrected.
- Added new “Filter Semantics in Illegal Positions” section.
- Ordinary move filters do not consider any moves when evaluated in imaginary positions.
- The
move previousfilter used in an imaginary position now corresponds to the move associated with the most recently evaluated speculative move filter in effect on the current position, if any. - Added the CQLi version number to the title page of this Reference Manual.
- CQLi now employs multi-threaded execution by default.
curposis now an alias for thecurrentpositionfilter.- An implicit
.cqlextension will now be added to an input query file name that does not contain an extension and cannot be located with the provided name. - Added support for the
--vioption which is equivalent to-i HHdbVI.pgn. - Comparison operators applied to position operands now check for an ancestral relationship between positions. The previous behavior for
XopYwhereXandYare position filters andopis a comparison operator can be obtained usingX:positionidopY:positionid. In particular, the filterX:positionid < Y:positionidmay be used inside ofechofilters to prevent the same pair of positions from being evaluated twice.
Changes in Version 1.0.3 (February 12, 2022)
- The
hhdbfilter is now supported. - The
movefilter now honors theprimaryandsecondaryparameters when combined with thepreviousparameter. - If
quietand<--both appear in afindfilter,quietmust now be specified first which matches the behavior of CQL 6.1. - The new
--appendoption may be used to append PGN output to an existing file. - Added new
--helpand--licenseoptions. - Added new “Appendix D: License” section.
- String articulations of the
reachablepositionfilter are now prefixed withReachableorUnreachableinstead ofValidorInvalid.
Changes in Version 1.0.2 (January 26, 2022)
General Improvements
- Messages diagnosing the presence of invalid tokens in PGN games now always include the offending token in the message.
- Improved handling of unescaped embedded quotes in malformed PGN tag pairs.
- Improved handling of malformed FEN tags in PGN files.
- Restored support for Windows 7 which broke in version 1.0.1.
- The performance of the regex iteration filter with large strings has been substantially improved.
- The performance of string slicing, string cardinality (
#), and the\-nregex group index filter have been significantly improved for long strings. - The performance of the
+=filter applied to string operands has been improved.
Functional Changes
- The
\-nregex group index filter now correctly counts characters outside the Basic Multilingual Plane. - The
readfileandwritefilefilters now work correctly with filenames containing Unicode characters on Windows. - The
currentfenfilter (and thefenfilter when not followed by a string literal) now produce a normalized FEN string with a halfmove clock value of0and a move counter of1. The newstandardfenfilter may be used to obtain a FEN string with values for the halfmove clock and move counter that correspond to the current position. - The target of an
imaginefilter is now always evaluated. Previously the target was not evaluated and the filter did not match in some situations where a piece placement or swap specifier did not effect a change in the position.
New Features
- Added the new
--skipunknownvariantsoption. - Added the new PGN output options:
--elidecomments/--noelidecomments--elidenags/--noelidenags--elidevariations/--noelidevariations--movenumberaftercomment/--nomovenumberaftercomment--movenumberafternag/--nomovenumberafternag--splitmoves/--nosplitmoves--movenumbers/--nomovenumbers
Documentation Improvements
- Numerous refinements including the addition of many more cross-reference links, clarification of key points and ideas, and various technical and typographical corrections.
- Added the new “System Requirements” section.
- Added descriptions of the
\nand\-nregex group filters. - Added new “Code Points and Graphemes” section.
- Added more “Synoptic Examples”.
- Extended the “Regular Expression Matching” section by adding a table of parenthetical constructs and the new “Escape Sequences” sub-section. Appendix A now lists CQLi-specific regex extensions.
Changes in Version 1.0.1 (November 26, 2021)
- The condition of an
iffilter no longer needs to be parenthesized when the optionalthenkeyword is not present. This matches the behavior of CQL 6.1. - The new
--nestedcommentsoption supports processing of PGN files that contain nested braced comments. - The summary message emitted at the end of processing no longer uses a digit separator for decimal numbers which produced undesired effects for some locales.
- A default output PGN file is now used if no output file is specified instead of writing matching games to standard output which can now be accomplished with the option
-o stdout. - Added descriptions for the
--lineincrementand--showmatchesoptions. - The string slicing operator now correctly indexes the Unicode code points of the provided string instead of the bytes in the UTF-8 encoding.
- Added description for the
#string cardinality operator. - The new Command Pipe extensibility feature allows CQLi to communicate with external programs during processing.
- CQLi will now emit user-requested messages immediately following evaluation of the corresponding
messagefilter instead of queueing such messages and emitting them all at once when processing of the game has completed. The previous behavior may be restored using the new--noasyncmessagesoption. - CQLi will now handle runtime errors immediately instead of waiting until processing of the current position or game has completed. Additionally, CQLi will no longer wait for other query threads to complete before terminating due to a fatal error.
- The option
--threads 0may now be specified to indicate that CQLi should use as many threads as are supported by the hardware. - CQLi will no longer add a superfluous move indicator for a move by Black in the output PGN file when appearing as the second move in a variation when the last move preceding the start of the variation contained a comment or NAG.
- Added a new “Variable Scopes” section to elaborate on how this mechanism works in CQLi.
- PGN files are now opened in binary mode which prevents undesired handing of certain control characters on Windows.
- The
settagfilter will now replace\rand\ncharacters in the provided tag value argument with spaces before writing the tag pair. - Added the new section “Notes for CQL6 Users”.
- The
inputandoutputCQL header parameters are now ignored when using the--secureoption.