comparison lispref/edebug.texi @ 63526:80bd8eddac37

(Instrumenting): Eliminate duplicate link. (Specification List): Replace references to "below", referring to a later node, with one @ref to that node.

63525:da42b07587f1

@pindex cl-specs.el
  Edebug knows how to instrument all the standard special forms,
@code{interactive} forms with an expression argument, anonymous lambda
expressions, and other defining forms.  However, Edebug cannot determine
on its own what a user-defined macro will do with the arguments of a
macro call, so you must provide that information; see @ref{Edebug and
Macros}, for details.

  When Edebug is about to instrument code for the first time in a
session, it runs the hook @code{edebug-setup-hook}, then sets it to
@code{nil}.  You can use this to load Edebug specifications
(@pxref{Edebug and Macros}) associated with a package you are
using, but only when you use Edebug.

@findex eval-expression @r{(Edebug)}
  To remove instrumentation from a definition, simply re-evaluate its
definition in a way that does not instrument.  There are two ways of
evaluating forms that never instrument them: from a file with

plus some context-free grammar constructs: the matching of sublists with
balanced parentheses, recursive processing of forms, and recursion via
indirect specifications.

Here's a table of the possible elements of a specification list, with
their meanings:

@table @code
@item sexp
A single unevaluated Lisp object, which is not instrumented.
@c an "expression" is not necessarily intended for evaluation.

as one does not match, Edebug stops matching at this level.

To make just a few elements optional followed by non-optional elements,
use @code{[&optional @var{specs}@dots{}]}.  To specify that several
elements must all match or none, use @code{&optional
[@var{specs}@dots{}]}.  See the @code{defun} example below.

@item &rest
@c @kindex &rest @r{(Edebug)}
All following elements in the specification list are repeated zero or
more times.  In the last repetition, however, it is not a problem if the

a list specification.

@item 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.

@item gate
@cindex preventing backtracking
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
@ref{Backtracking}, for more details.  Also see the @code{let} example
below.

@item @var{other-symbol}
@cindex indirect specifications
Any other symbol in a specification list may be a predicate or an
indirect specification.

If the symbol has an Edebug specification, this @dfn{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 @code{def-edebug-spec}
just as for macros. See the @code{defun} example below.

Otherwise, the symbol should be a predicate.  The predicate is called
with the argument and the specification fails if the predicate returns
@code{nil}.  In either case, that argument is not instrumented.

is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
of @var{symbol} is the @var{string}, but the string form is preferred.

@item (vector @var{elements}@dots{})
The argument should be a vector whose elements must match the
@var{elements} in the specification.  See the backquote example below.

@item (@var{elements}@dots{})
Any other list is a @dfn{sublist specification} and the argument must be
a list whose elements match the specification @var{elements}.

argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
dotted list specification may be another sublist specification (via a
grouping or an indirect specification, e.g., @code{(spec .  [(more
specs@dots{})])}) 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 @code{nil} specification
above for terminating such recursion.

Note that a sublist specification written as @code{(specs .  nil)}
is equivalent to @code{(specs)}, and @code{(specs .
(sublist-elements@dots{}))} is equivalent to @code{(specs

@end table

@c Need to document extensions with &symbol and :symbol

Here is a list of additional specifications that may appear only after
@code{&define}.  See the @code{defun} example below.

@table @code
@item name
The argument, a symbol, is the name of the defining form.

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

@node Backtracking
@subsubsection Backtracking in Specifications

63526:80bd8eddac37

@pindex cl-specs.el
  Edebug knows how to instrument all the standard special forms,
@code{interactive} forms with an expression argument, anonymous lambda
expressions, and other defining forms.  However, Edebug cannot determine
on its own what a user-defined macro will do with the arguments of a
macro call, so you must provide that information using Edebug
specifications; see @ref{Edebug and Macros}, for details.

  When Edebug is about to instrument code for the first time in a
session, it runs the hook @code{edebug-setup-hook}, then sets it to
@code{nil}.  You can use this to load Edebug specifications
associated with a package you are using, but only when you use Edebug.

@findex eval-expression @r{(Edebug)}
  To remove instrumentation from a definition, simply re-evaluate its
definition in a way that does not instrument.  There are two ways of
evaluating forms that never instrument them: from a file with

plus some context-free grammar constructs: the matching of sublists with
balanced parentheses, recursive processing of forms, and recursion via
indirect specifications.

Here's a table of the possible elements of a specification list, with
their meanings (see @ref{Specification Examples}, for the referenced
examples):

@table @code
@item sexp
A single unevaluated Lisp object, which is not instrumented.
@c an "expression" is not necessarily intended for evaluation.

as one does not match, Edebug stops matching at this level.

To make just a few elements optional followed by non-optional elements,
use @code{[&optional @var{specs}@dots{}]}.  To specify that several
elements must all match or none, use @code{&optional
[@var{specs}@dots{}]}.  See the @code{defun} example.

@item &rest
@c @kindex &rest @r{(Edebug)}
All following elements in the specification list are repeated zero or
more times.  In the last repetition, however, it is not a problem if the

a list specification.

@item 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.

@item gate
@cindex preventing backtracking
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
@ref{Backtracking}, for more details.  Also see the @code{let} example.

@item @var{other-symbol}
@cindex indirect specifications
Any other symbol in a specification list may be a predicate or an
indirect specification.

If the symbol has an Edebug specification, this @dfn{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 @code{def-edebug-spec}
just as for macros. See the @code{defun} example.

Otherwise, the symbol should be a predicate.  The predicate is called
with the argument and the specification fails if the predicate returns
@code{nil}.  In either case, that argument is not instrumented.

is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
of @var{symbol} is the @var{string}, but the string form is preferred.

@item (vector @var{elements}@dots{})
The argument should be a vector whose elements must match the
@var{elements} in the specification.  See the backquote example.

@item (@var{elements}@dots{})
Any other list is a @dfn{sublist specification} and the argument must be
a list whose elements match the specification @var{elements}.

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

Note that a sublist specification written as @code{(specs .  nil)}
is equivalent to @code{(specs)}, and @code{(specs .
(sublist-elements@dots{}))} is equivalent to @code{(specs

@end table

@c Need to document extensions with &symbol and :symbol

Here is a list of additional specifications that may appear only after
@code{&define}.  See the @code{defun} example.

@table @code
@item name
The argument, a symbol, is the name of the defining form.

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

@node Backtracking
@subsubsection Backtracking in Specifications