22.4.16.1 Specification List

A specification list is required for an Edebug specification if some arguments of a macro call are evaluated while others are not. Some elements in a specification list match one or more arguments, but others modify the processing of all following elements. The latter, called keyword specifications, are symbols beginning with ‘&’ (e.g. &optional).

A specification list may contain sublists which match arguments that are themselves lists, or it may contain vectors used for grouping. Sublists and groups thus subdivide the specification list into a hierarchy of levels. Keyword specifications only apply to the remainder of the sublist or group they are contained in and there is an implicit grouping around a keyword specification and all following elements in the sublist or group.

If a specification list fails at some level, then backtracking may be invoked to find some alternative at a higher level, or if no alternatives remain, an error will be signaled. See Backtracking for more details.

Edebug specifications provide at least the power of regular expression matching. Some context-free constructs are also supported: the matching of sublists with balanced parentheses, recursive processing of forms, and recursion via indirect specifications.

Each element of a specification list may be one of the following, with the corresponding type of argument:

sexp

A single unevaluated expression.

form

A single evaluated expression, which is instrumented.

place

A place as in the Common Lisp setf place argument. It will be instrumented just like a form, but the macro is expected to strip the instrumentation. Two functions, edebug-unwrap and edebug-unwrap*, are provided to strip the instrumentation one level or recursively at all levels.

body

Short for &rest form. See &rest below.

function-form

A function form: either a quoted function symbol, a quoted lambda expression, or a form (that should evaluate to a function symbol or lambda expression). This is useful when function arguments might be quoted with quote rather than function since the body of a lambda expression will be instrumented either way.

lambda-expr

An unquoted anonymous lambda expression.

&optional

All following elements in the specification list are optional; as soon as one does not match, Edebug stops matching at this level.

To make just a few elements optional followed by non-optional elements, use [&optional specs…]. To specify that several elements should all succeed together, use &optional [specs…]. See the defun example below.

&rest

All following elements in the specification list are repeated zero or more times. All the elements need not match in the last repetition, however.

To repeat only a few elements, use [&rest specs…]. To specify all elements must match on every repetition, use &rest [specs…].

&or

Each of the following elements in the specification list is an alternative, processed left to right until one matches. One of the alternatives must match otherwise the &or specification fails.

Each list element following &or is a single alternative even if it is a keyword specification. (This breaks the implicit grouping rule.) To group two or more list elements as a single alternative, enclose them in […].

&not

Each of the following elements is matched as alternatives as if by using &or, but if any of them match, the specification fails. If none of them match, nothing is matched, but the &not specification succeeds.

&define

Indicates that the specification is for a defining form. The defining form itself is not instrumented (i.e. Edebug does not stop before and after the defining form), but forms inside it typically will be instrumented. The &define keyword should be the first element in a list specification.

Additional specifications that may only appear after &define are described here. See the defun example below.

name

The argument, a symbol, is the name of the defining form. But a defining form need not be named at all, in which case a unique name will be created for it.

The name specification may be used more than once in the specification and each subsequent use will append the corresponding symbol argument to the previous name with ‘@’ between them. This is useful for generating unique but meaningful names for definitions such as defadvice and defmethod.

:name

The element following :name should be a symbol; it is used as an additional name component for the definition. This is useful to add a unique, static component to the name of the definition. It may be used more than once. No argument is matched.

arg

The argument, a symbol, is the name of an argument of the defining form. However, lambda list keywords (symbols starting with ‘&’) are not allowed. See lambda-list and the example below.

lambda-list

This matches the whole argument list of an SXEmacs Lisp lambda expression, which is a list of symbols and the keywords &optional and &rest

def-body

The argument is the body of code in a definition. This is like body, described above, but a definition body must be instrumented with a different Edebug call that looks up information associated with the definition. Use def-body for the highest level list of forms within the definition.

def-form

The argument is a single, highest-level form in a definition. This is like def-body, except use this to match a single form rather than a list of forms. As a special case, def-form also means that tracing information is not output when the form is executed. See the interactive example below.

nil

This is successful when there are no more arguments to match at the current argument list level; otherwise it fails. See sublist specifications and the backquote example below.

gate

No argument is matched but backtracking through the gate is disabled while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See Backtracking for more details. Also see the let example below.

other-symbol

Any other symbol in a specification list may be a predicate or an indirect specification.

If the symbol has an Edebug specification, this indirect specification should be either a list specification that is used in place of the symbol, or a function that is called to process the arguments. The specification may be defined with def-edebug-spec just as for macros. See the defun example below.

Otherwise, the symbol should be a predicate. The predicate is called with the argument and the specification fails if the predicate fails. The argument is not instrumented.

Predicates that may be used include: symbolp, integerp, stringp, vectorp, atom (which matches a number, string, symbol, or vector), keywordp, and lambda-list-keywordp. The last two, defined in edebug.el, test whether the argument is a symbol starting with ‘:’ and ‘&’ respectively.

[elements…]

Rather than matching a vector argument, a vector treats the elements as a single group specification.

"string"

The argument should be a symbol named string. This specification is equivalent to the quoted symbol, 'symbol, where the name of symbol is the string, but the string form is preferred.

'symbol or (quote symbol)

The argument should be the symbol symbol. But use a string specification instead.

(vector elements…)

The argument should be a vector whose elements must match the elements in the specification. See the backquote example below.

(elements…)

Any other list is a sublist specification and the argument must be a list whose elements match the specification elements.

A sublist specification may be a dotted list and the corresponding list argument may then be a dotted list. Alternatively, the last cdr of a dotted list specification may be another sublist specification (via a grouping or an indirect specification, e.g. (spec . [(more specs…)])) whose elements match the non-dotted list arguments. This is useful in recursive specifications such as in the backquote example below. Also see the description of a nil specification above for terminating such recursion.

Note that a sublist specification of the form (specs . nil) means the same as (specs), and (specs . (sublist-elements…)) means the same as (specs sublist-elements…).