next* and previous* filters

next* and previous* each take an optional range followed by a filter. Optionally, a depth keyword, followed by an integer, can precede the filter.

next* filter
next* range filter
next* depth integer filter
next* range depth integer filter
previous* filter
previous* range filter

semantics of next*

next* filter matches the current position if either the current position matches filter or if some later position matches filter . If variations is set than variations are searched; otherwise only the mainline is searched.

By "later" of course is meant "reachable by a sequence of moves starting from the current position within the current game".

Without a range, next* filter is identical to

next (any* filter)

For example, the following code checks whether the same rook has visited all four corners of the board:

initial
piece $rook in [Rr]
 next* $rook on a1
 next* $rook on h1
 next* $rook on h8
 next* $rook on a8

Note that the code here only looks at initial positions. This is a common idiom in using next*.

semantics of next* range filter

With a range, next* matches the current position only if the number of positions that occur on or after the current position of filter in the current position or later positions lies within the range. With a range, next* is countable and returns the number of matching positions, if they lie in the range.

check next* 1 check

matches a position that is the last check of the game. Note that the current position is a check, so that it will be found by the next* and contribute to the count. Any following checks will make the count over the range limit of 1.

previous*

previous* is identical to next* except that earlier, not later, positions are searched. Also, previous* ignores the variations flag, since every position other than the initial position has exactly one previous position.

The depth keyword

The depth keyword, if present, must be followed by a single non-negative integer. It limits the search depth of the next* or previous* filter to the specified depth from the current position, which has depth 0.

pitfalls in using next* and previous*

next* and previous* are fairly straightforward. One issue to watch out for: Do not search unnecessarily from every position if you can just search from an initial (for next*) or terminal (for previous*) position.

Examples