next* and previous* filters
previous*each take an optional range followed by a filter. Optionally, a
depthkeyword, 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* filtermatches the current position if either the current position matches
filteror if some later position matches
variationsis 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
semantics of next* range filterWith 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 checkmatches 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*is identical to
next*except that earlier, not later, positions are searched. Also,
variationsflag, since every position other than the initial position has exactly one previous position.
The depth keywordThe
depthkeyword, if present, must be followed by a single non-negative integer. It limits the search depth of the
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