The line Filter

Constituent Repetition

Constituents of a line filter may optionally be followed by a quantifier which modifies the number of times the constituent must match (by default each constituent must match once). The quantifiers that may be used in line constituents are shown in the table below.

For example, to find sequences that start with a check, followed by any number of captures (including zero), followed by mate, the * quantifier may be added to the move filter constituent:

line --> check
     --> move previous capture . *
     --> mate

Constituent quantifiers are always greedy meaning they match as many times as possible, but not at the expense of the line filter failing. For example, the query:

line --> move previous capture . +

will match the longest sequence of captures starting at the current position and the query:

line --> move previous capture . + --> mate

will match a series of captures followed by mate even if the move that results in mate is a capture (the move constituent will not consume the final position, allowing the mate constituent to match instead so that the line filter can match).

If a * or + token appearing in a constituent could be interpreted as multiplication or addition, it will be. To force the token to be interpreted as a repetition quantifier it may be enclosed in braces, e.g. {?}, {*}, and {+}. In addition to being unambiguous, enclosing repetition quantifiers in braces help them stand out visually.

The m and n appearing in counted repetition quantifiers must be non-negative Numeric literals and m, if present, must not be greater than n.

Constituent Grouping

Multiple line constituents may be grouped by enclosing the constituents in parentheses and repetition may then be applied to the group as a whole. For example, the following query will find games that end in checkmate with at least three check-then-capture sequences immediately preceding mate:

line --> (check --> move previous capture (flipcolor A attacks k)) {3,}
     --> mate

Constituent groups may be nested and separate repetition for constituents within a group may be specified. Note that each instance of <-- or --> represents the next position in the specified direction, even within a grouping, e.g. the above query will not match sequences of less than seven positions.

An example of a game matching the above query is here. The diagrams below show the critical positions.

Auxiliary Comments

Unless the quiet parameter is specified, the longest sequence found by a matching line filter at the current position will be annotated with auxiliary comments. The matching position at the start of this sequence will be annotated with the comment:

Start line that ends at move end-position

and the position that ends the sequence will be annotated with the comment:

End line of length sequence-length that starts at move start-position

where sequence-length is a positive non-zero numeric value that represents the length of the annotated sequence and start-position and end-position are the textual portrayals (as described in String Portrayal of Types) of the positions that start and end the sequence, respectively.

Multiple Matching Sequences

When variations are processed, it is possible for multiple sequences of the same length to be found at the current position. When this happens, the selected sequence (the one which contains auxiliary comments, comments retained by Smart Comments, the final position returned when using the lastposition parameter, and the sequence that determines the the final state of modified variables) is the one that ends with the position with the lowest position ID. If the –keepallbest option is used, comments (both user-comments and auxiliary comments) are preserved for all matching sequences but the position returned when lastposition is used and the final state of modified variables is the same as when this option is not used.

When multiple constituents in a line filter contain repetition quantifiers, it is possible for a matching sequence to have several ways to match, even outside of variations. For example, consider the query:

initial
line --> comment "A" * --> comment "B" *

applied at the beginning of a game that contains two positions. Since repetition is greedy, we know that both positions will be consumed by this line filter but how many times will each constituent match? Since the * quantifier can successfully match zero times, the possible outcomes are that the first constituent matches zero times and the second one matches two times, both constituents match once, or the first constituent matches both times. In most cases it won’t make a difference but it can when the constituents have side-effects, such as modifying a variable or adding a comment. When the line filter has multiples ways to match a sequence of the same length, it is unspecified how the positions in the sequence will be correlated to the corresponding constituents. In other words, the result of the above query could be that both positions are commented with “A”, both are commented with “B”, or the first position is commented with “A” and the second with “B”.

The firstmatch Parameter

When the firstmatch parameter is specified, CQLi will find the shortest sequence that matches the constituent filters instead of the longest. Despite the name, this is not necessarily the “first” successful match that is encountered. This parameter was used in CQL 6 to partially mitigate situations in which variables modified in line constituents could have inconsistent states when backtracking while looking for a longer match although it doesn’t always achieve that goal. CQLi employs a more robust mechanism (Atomic Evaluation described below) to ensure variable consistency while evaluating constituents so specifying firstmatch is not necessary to accommodate such filters. Additionally, CQLi utilizes a different, non-backtracking, matching algorithm and the behavior that is closest to the CQL 6 behavior is simply to yield the shortest matching sequence.

The lastposition Parameter

The lastposition parameter indicates that the last position of the best matching sequence found by line should be returned instead of the length of the longest sequence.

The nestban Parameter

When nestban is used, all of the positions in the sequence of a matching line filter will be banned from starting a sequence in a later evaluation of the same line filter for the same game. The nestban parameter may not be used with backwards-looking line filters (ones where the constituent introducer is <--).

The nestban parameter is used to prevent subsequences of the longest matching sequence from being reported. For example, the following query will find sequences of 5 or more consecutive captures:

line nestban --> move capture . {5,}

Without the nestban parameter, all later subsequences of the initial sequence will also be found which is typically not desired.

The nolinearize Parameter

The nolinearize parameter disables Move Linearization within all constituents of the line filter. Linearization may be independently disabled for individual constituents as described below.

The nonatomic Parameter

By default, CQLi performs atomic evaluation of constituent filters that modify non-dictionary variables. The nonatomic parameter may be used to suppress this atomic evaluation.

The primary and secondary Parameters

If secondary is specified, only positions that start a variation are considered after the current position. If primary is specified, only positions that do not start a variation are considered after the current position.

The quiet Parameter

If the quiet parameter is provided, auxiliary comments normally added by the line filter will be suppressed for matching sequences.

The singlecolor Parameter

When singlecolor is specified, only positions with the same side to move as the position that starts the sequence are considered. For example, the query;

line singlecolor --> check {10,}

will find sequences where one side checks the other 10 or more times in a row.