Revision History

Changes in Version 1.0.7

Documentation Improvements

• Many refinements have been made throughout the Reference Manual including adding shaded code blocks, zebra-striped tables, improved page headers, and a cleaner Table of Contents. Many mistakes have been corrected, new examples were added, and explanations of key concepts improved.

• A Brief Tour of CQL was added to better support new users getting stated with CQLi.

• A new Mating Patterns section was added which explores 30 mating patterns, each with a corresponding CQLi query and diagrammed examples.

• A rewritten Synoptic Examples section adds focused subsections, supports a broader set of use cases, and includes over two dozen diagrams.

• The new List of Symbol Filters section was added to supplement List of Named Filters.

• Incorrect rendering of the ^ character in query examples was corrected.

New Features

• Added the new –includetagpattern and –excludetagpattern options which can be used to control which PGN tags are emitted when writing matching games.
• Named capture groups may now be extracted outside of regular expression patterns using \{name} and \-{name}. See Groups, Captures, and Backreferences for details.
• Added the new –binaryoutput option.
• Added the new –sortmatchcount option.
• Added the new tourney_edition, tourney_name, tourney_year, tourney_year_end, tourney_year_part, and distinction hhdb commands to support extraction of the corresponding information from the Event field of the HHdbVII database. See for details.

General Improvements

• The pattern provided as the right-hand operand to the ~~ filter no longer needs to be a string literal.
• The quiet, <--, and all keywords used with the find filter may now appear in any order.
• The speculative move filter now accepts an optional all keyword parameter causing the filter to match the position only if the target filter matches for every position considered.
• CQLi now supports PGN files containing more than 2 billion games.

Changes in Version 1.0.6

• The new cqlbegin and cqlend filters can be used to perform actions at the start and end of processing.
• The new –noclobber option may be used to prevent CQLi from overwriting existing output files.
• The new –createdirectories option may be used to create non-existent directories specified in the name of output PGN files.
• The new –maxopenoutputfiles option can be used to limit how many output PGN files are open at a time.
• The version information displayed when using the –version option now includes the build date and the version of ICU4C that is statically linked to CQLi.
• The presence of multiple -a/-o options on the command line is now diagnosed as an error.

Changes in Version 1.0.5

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 –dryrun option can be used to show the files that would have been created without actually creating them.
• The new replace filter 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 key filter 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 of None when provided with an argument with the None value. Outside of variable access filters (which yield None for 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, and settag) would previously yield a value of None instead of false in certain situations. Additionally, a Boolean compound filter ({ ... } with a Boolean terminating filter) would yield None instead of false if any of its constituent filters failed to match the position. While None and false are treated identically in almost every context, noticeable inconsistencies could occur when the value of one of these filters was converted to a string via the str, comment, or message filters. Boolean filters will now consistently yield the value false when they do not match the position.
• The legalposition filter previously incorrectly evaluated to false for 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 the reachableposition filter.
• The reachableposition filter 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 reachableposition filter now detects impossible escaped promoted rooks when all of the opposing side’s pawns are on ranks 2-3/6-7.
• The reachableposition filter 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 reachableposition filter 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 database including:
  • Added the –vii option.
  • Updated the hhdb composer and hhdb stipulation commands to support the conventions used by HHdbVII.
  • Updated the hhdb "(c)", hhdb "(m)", hhdb "(s)", and hhdb "(v)" commands to support the format used to represent these attributes in HHdbVII.
  • Added the command aliases hhdb C, hhdb M, hhdb S, and hhdb V.
  • Included an section to demonstrate how to accomplish the searches discussed in the HHdbVII documentation with CQLi.
  • Added the new hhdb CE / hhdb computer_based_ending and hhdb MR / hhdb material_restriction commands to support new study attributes available in HHdbVII.
  • Updated references and statistics as appropriate.
• Updated the behavior of hhdb composer to better handle inconsistencies in HHdbVI.

Changes in Version 1.0.4

• Added the new –nosort option 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 previous filter 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.
• curpos is now an alias for the currentposition filter.
• An implicit .cql extension 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 –vi option 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 X op Y where X and Y are position filters and op is a comparison operator can be obtained using X:positionid op Y:positionid. In particular, the filter X:positionid < Y:positionid may be used inside of echo filters to prevent the same pair of positions from being evaluated twice.

Changes in Version 1.0.3

• The hhdb filter is now supported.
• The move filter now honors the primary and secondary parameters when combined with the previous parameter.
• If quiet and <-- both appear in a find filter, quiet must now be specified first which matches the behavior of CQL 6.1.
• The new –append option may be used to append PGN output to an existing file.
• Added new –help and –license options.
• Added new Appendix D: License section.
• String articulations of the reachableposition filter are now prefixed with Reachable or Unreachable instead of Valid or Invalid.

Changes in Version 1.0.2

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 \-n regex 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 \-n regex group index filter now correctly counts characters outside the Basic Multilingual Plane.
• The readfile and writefile filters now work correctly with filenames containing Unicode characters on Windows.
• The currentfen filter (and the fen filter when not followed by a string literal) now produce a normalized FEN string with a halfmove clock value of 0 and a move counter of 1. The new standardfen filter 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 imagine filter 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 change the position.

New Features

• Added the new –skipunknownvariants option.
• 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 \n and \-n regex 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

• The condition of an if filter no longer needs to be parenthesized when the optional then keyword is not present. This matches the behavior of CQL 6.1.
• The new –nestedcomments option 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 –lineincrement and –showmatches options.
• 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 message filter 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 –noasyncmessages option.
• 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 0 may 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 handling of certain control characters on Windows.
• The settag filter will now replace \r and \n characters in the provided tag value argument with spaces before writing the tag pair.
• Added the new section Notes for CQL6 Users.
• The input and output CQL header parameters are now ignored when using the –secure option.