Diagnostics

Diagnostic Format

Diagnostics consist of three lines. The first line contains the name of the source containing the CQL query, the line and column number corresponding to the location where the diagnostic emanated, the diagnostic category, and the text of the diagnostic. The second line contains the portion of the query that is being diagnosed and the third line contains a position indicator pointing to the location referenced by the line and column number. The third line may also highlight one or more relevant portions of the query text appearing on the same line. An example of a warning is:

test.cql:2:1 warning: Superfluous transform does not modify any filters in the target filter
rotate90 ray orthogonal (R K)
^        ~~~~~~~~~~~~~~~~~~~~

This is a warning because, while legal, it is suspicious since removing rotate90 will not change the behavior of the query. The position indicator points to the transform in question and the target filter referenced by the diagnostic is highlighted.

Notes

Notes sometimes appear after a warning, error, or info diagnostic to convey additional information about the diagnostic. For example, the query:

function Greater($x $y) { $x > $y }
Greater(A a)

will elicit:

test.cql:1:30 error: Sets cannot be compared using the '>' filter
function greater($x $y) { $x > $y }
                          ~~ ^ ~~   
test.cql:2:1 note: While instantiating function 'greater'
greater(A a)
^            

In this case, the error is not diagnosed until the function is called as the argument types are not known before the call. The note provides the location where the function invocation responsible for the error occurs.

Warning Levels

There are three warning levels in CQLi. At warning level 1 only errors are emitted, at warning level 2 errors and warnings are emitted, at warning level 3 all diagnostics, including infos, are emitted. The default warning level is 2 and can be changed with the --warnlevel or -w option which accepts a single numeric argument, e.g. -w 3.

List of Warnings

• Atomic evaluation of string assignment in 'line' constituent may be inefficient
• Atomic evaluation of slice assignment in 'line' constituent may be inefficient

A constituent of a line filter that was not marked as nonatomic contained an assignment to a String variable. String variable modifications are evaluated atomically in a line filter but may result in suboptimal performance, especially for large strings. Modifying the query so that string variables are modified outside the line filter may be more efficient.

• Regular expression can yield empty matches

The regular expression provided as the RHS argument to the ~~ pattern matching filter will match an empty string which may result in unexpected results. For example:

X ~~ "\d*"

will extract digits from a string but will also match a string that does not contain any digits, yielding an empty string as a match. Since this is likely to be undesired, a warning is emitted.

• Square designators are not influenced by 'rotate45' transforms and should be enclosed by a 'notransform' filter

A square designator appeared within the target of a rotate45 filter. Square designators are not affected by a rotate45 filter and their presence in the target filter is suspicious. The square designator(s) can be wrapped in a notransform filter to make the intention explicit and silence this diagnostic.

• Dictionary assignment in 'line' constituent will not be evaluated atomically

A dictionary assignment appeared in the constituent of a line filter that was not marked as nonatomic. Dictionary modifications in line filter constituents are not evaluated atomically.

• Modification of dictionary variable will not be evaluated atomically in 'line' filter

A dictionary was the target of an unbind filter in the constituent of a line filter that was not marked as nonatomic. Dictionary modifications in line filter constituents are not evaluated atomically.

• Range parameters of transform filters are deprecated, consider using 'count' instead

A range parameter was used with a transform filter. This use is deprecated and support for it may be removed in the future.

• Superfluous transform does not modify any filters in the target filter

A transform filter does not have any effect because none of the filters in the target are subject to the types of transformations employed by the transform filter. For example:

shift up R & k

will elicit this message as the shift transform filter only modifies square designators but there are no square designators in the target filter so the shift filter can be removed without affecting the behavior of the query.

• 'sort' keyword following 'hhdb' award filter is suspicious, parenthesize the preceding 'hhdb' filter or place 'sort' after 'hhdb' to suppress this warning

The sort keyword appeared immediately after an hhdb award filter but was not parsed as part of the award filter because the keyword did not immediately follow the hhdb keyword. Was the sort intended to apply to the award filter or as a standalone filter? If the former, the sort keyword should be moved immediately after the hhdb keyword. Otherwise, the query is parsed as intended but either the preceding hhdb filter or the following sort filter should be braced or parenthesized to make the intention explicit.

• The 'ancestor' filter is deprecated, 'ancestor(x y)' can now be written as 'x < y'
• The 'descendant' filter is deprecated, 'descendant(x y)' can now be written as 'x > y'

Since CQLi{} 1.0.4, the Comparison Filters check for ancestral relationships when applied to Position filters. The ancestor and descendant filters are deprecated in favor of the equivalent comparison operator filters.

List of Infos

• Precedence vitiation was employed to obtain suitable LHS operand for 'Name' filter, parenthesize the highlighted expression to silence this message

A binary infix filter did not receive a LHS argument of the appropriate type when applying the standard parsing precedence. The precedence of the operator specified by Name was temporarily subverted to allow a higher-order grammar production to form the LHS argument. This process produced a LHS operand of the expected type (an error would have been emitted instead if it hadn’t) but the result may not have been parsed according to the user’s expectations. The expression that was used to form the LHS is highlighted to indicate how the expression was parsed. Surrounding the highlighted expression in parentheses will silence this diagnostic.

• Using 'persistent' on variable 'Name' more than once is redundant

The persistent keyword should only appear on the first reference of a variable.

The purpose of the remaining diagnostics in this section are to report the use of filters and language features that are not supported by CQL 6.1 which is useful if compatibility with CQL 6.1 is desired.

• Use of non-variable argument to 'consecutivemoves' filter is a CQLi extension

CQL 6.1 requires that arguments to consecutivemoves be variables.

• Persistent variable merge strategy is a CQLi extension

CQL 6.1 does not support parallel execution of queries that use persistent variables and does not recognize the merge strategy syntax used by CQLi.

• 'quiet' dictionaries are a CQLi extension

CQL 6.1 supports quiet persistent variables but not quiet dictionaries.

• Dictionary type specifier is a CQLi extension

The ability to define dictionaries with alternate key and value types using a type specifier is a CQLi extension.

• Compound assignment for dictionary members is a CQLi extension
• Conditional set assignment for dictionary members is a CQLi extension

CQL 6.1 does not support compound or conditional set assignment for dictionary members.

• Use of 'nonatomic' keyword in 'line' filter is a CQLi extension
• Use of 'nolinearize' keyword in 'line' filter is a CQLi extension

CQL 6.1 does not support the nonatomic or nolinearize keywords to the line filter.

• Speculative 'move' filter is a CQLi extension

CQL 6.1 does not support speculative move exploration.

• Reverse 'move' filter is a CQLi extension

CQL 6.1 does not support reverse move exploration.

• Restricted shift filters are a CQLi extension

CQL 6.1 does not support the restricted shift filter syntax.

• 'noclobber' is a CQLi extension

CQL 6.1 does not support the noclobber keyword parameter to the writefile filter.

• The 'commandpipe' filter is a CQLi extension
• The 'cqlbegin' filter is a CQLi extension
• The 'cqlend' filter is a CQLi extension
• The 'halfmoveclock' filter is a CQLi extension
• The 'legalposition' filter is a CQLi extension
• The identity filter is a CQLi extension
• The 'imagine' filter is a CQLi extension
• The 'key' filter is a CQLi extension
• The 'reachableposition' filter is a CQLi extension
• The 'removetag' filter is a CQLi extension
• The 'replace' filter is a CQLi extension
• The 'standardfen' filter is a CQLi extension
• The 'zobristkey' filter is a CQLi extension

CQL 6.1 does not support any of the above filters.