19.2.15.4 Specification Examples

It may be easier to understand Edebug specifications by studying the examples provided here.

Consider a hypothetical macro my-test-generator that runs tests on supplied lists of data. Although it is Edebug’s default behavior to not instrument arguments as code, as controlled by edebug-eval-macro-args (see Instrumenting Macro Calls), it can be useful to explicitly document that the arguments are data:

(def-edebug-spec my-test-generator (&rest sexp))

A let special form has a sequence of bindings and a body. Each of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the gate inside of the sublist to prevent backtracking once a sublist is found.

(def-edebug-spec let
  ((&rest
    &or symbolp (gate symbolp &optional form))
   body))

Edebug uses the following specifications for defun and the associated argument list and interactive specifications. It is necessary to handle interactive forms specially since an expression argument is actually evaluated outside of the function body. (The specification for defmacro is very similar to that for defun, but allows for the declare statement.)

(def-edebug-spec defun
  (&define name lambda-list
           [&optional stringp]   ; Match the doc string, if present.
           [&optional ("interactive" interactive)]
           def-body))

(def-edebug-elem-spec 'lambda-list
  '(([&rest arg]
     [&optional ["&optional" arg &rest arg]]
     &optional ["&rest" arg]
     )))

(def-edebug-elem-spec 'interactive
  '(&optional &or stringp def-form))    ; Notice: def-form

The specification for backquote below illustrates how to match dotted lists and use nil to terminate recursion. It also illustrates how components of a vector may be matched. (The actual specification defined by Edebug is a little different, and does not support dotted lists because doing so causes very deep recursion that could fail.)

(def-edebug-spec \` (backquote-form))   ; Alias just for clarity.

(def-edebug-elem-spec 'backquote-form
  '(&or ([&or "," ",@"] &or ("quote" backquote-form) form)
        (backquote-form . [&or nil backquote-form])
        (vector &rest backquote-form)
        sexp))