next2 and previous2

Sometimes we only care about what one color does. Consider the following filter, in which the side to move is checked three times and is then mated:
next (check . check . check . mate)
In this case, we have the convenience of next2:
next2 (check check check mate)
which (loosely speaking) inserts an implicit . between every two positions.

More precisely, next2 is like next except that only every other position, beginning with the current position, is considered when matching the constituents.

Similarly, previous2 is just like previous except that only every other position (starting with the current position) is considered in matching constituents.

Examples

The next2 filter is particularly useful in conjunction with regular expressions. For example, the CQL file consecutive-checks-by-one-color.cql illustrates how to find the games with a sequence of at least 20 checks by one color, sorting the results by the length of that sequence:
    not previous2 (. check)
    sort
      next2 20 100 (check+)
The first line, not previous2 (. check) makes sure that the current position is not part of a longer sequence of checks. The next line matches the checks, but only considers checks by a single color.

A more sophisticated examples is in staircase-sort.cql, which finds examples of queen staircases, sorted by the length of the staircase.

The staircase is found in these lines:

  sort "staircase size"
   next2 5 100 
   ((move from Q to up 1 Q
     move from Q to right 1 Q)+
    {move from Q to up 1 Q}? 
   )
Here, one "step" in the staircase is given by
    move from Q to up 1 Q
This matches a position in which the white Queen moves one square upwards. To see this, suppose the only white Queen is currently on d4. Then
    up 1 Q = up 1 d4
           = d5

Hence, in such a position,

    move from Q to up 1 Q 
    = move from Q to d5
    = move from Qd4 to d5
  
which is what we want.

In exactly the same way, move from Q to right 1 Q matches a position in which the white Queen will move one square right. Now, a staircase (in the up-right direction) is simply a sequence of one or more of these pairs of moves - a move up followed by a more right - which is what

    (move from Q to up 1 Q
     move from Q to right 1 Q)+
means.

The main point to note here is that, if the current position when the next2 is encountered is wtm, then only the wtm positions will be matched against. The btm positions will be ignored.

Two finish matching the queen staircases, we just need to do three more things:

  1. Since the sequence of up-right moves by the queen might possibly end with an up move (so that there would be an odd numbe of moves in the staircase), we have to put in an optional:
    	move from Q to up 1 Q?
    at the end of the next2 arguments.
  2. To make the output look neater, without a bunch of unnecessary "MATCH" annotations, we only start looking when we are sure that we are not in the middle of a staircase already. That is the purpose of the guard:
    	not previous2
    	     (.
           	      move from Q to right 1 Q)
    that precedes the next2 filter.
  3. Finally, since we are looking for any pair of orthogonal directions instead of up and right, we have to wrap the entire series of filters in a giant flip. Since we also want to look at black queen staircases, we wrap it in a flipcolor as well (to "wrap" the filters, we put them inside braces to form a compound filter.

Note that sort and counts work as expected with next2 and previous2: only the matched positions of the given color are counted, and only those counts are considered when matching the range and sorting.