22.4.16.2 Backtracking

If a specification fails to match at some point, this does not necessarily mean a syntax error will be signaled; instead, backtracking will take place until all alternatives have been exhausted. Eventually every element of the argument list must be matched by some element in the specification, and every required element in the specification must match some argument.

Backtracking is disabled for the remainder of a sublist or group when certain conditions occur, described below. Backtracking is reenabled when a new alternative is established by &optional, &rest, or &or. It is also reenabled initially when processing a sublist or group specification or an indirect specification.

You might want to disable backtracking to commit to some alternative so that Edebug can provide a more specific syntax error message. Normally, if no alternative matches, Edebug reports that none matched, but if one alternative is committed to, Edebug can report how it failed to match.

First, backtracking is disabled while matching any of the form specifications (i.e. form, body, def-form, and def-body). These specifications will match any form so any error must be in the form itself rather than at a higher level.

Second, backtracking is disabled after successfully matching a quoted symbol or string specification, since this usually indicates a recognized construct. If you have a set of alternative constructs that all begin with the same symbol, you can usually work around this constraint by factoring the symbol out of the alternatives, e.g., ["foo" &or [first case] [second case] ...].

Third, backtracking may be explicitly disabled by using the gate specification. This is useful when you know that no higher alternatives may apply.