comparison doc/lispref/edebug.texi @ 103897:e52d10e14bc0

Minor re-phrasings throughout. (Edebug Execution Modes): Sit-for affects continue mode too. (Jumping): Use `forward-sexp' rather than its keybinding. (Edebug Misc): Fix Q binding. (Edebug Eval): Remove cl version. (Printing in Edebug): Clarify print-length etc. (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. (Specification List): Remove edebug-unwrap findex entry. (Specification Examples): defmacro is actually not the same as defun. Escape "`" in example.

103896:a4d216dbf517

@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
@cindex Edebug debugging facility

  Edebug is a source-level debugger for Emacs Lisp programs with which
you can:

@itemize @bullet
@item
Step through evaluation, stopping before and after each expression.

@item
Automatically re-evaluate a list of expressions and
display their results each time Edebug updates the display.

@item
Output trace info on function enter and exit.

@item
Stop when an error occurs.

@item

@item
Obtain rudimentary coverage testing and frequency counts.
@end itemize

The first three sections below should tell you enough about Edebug to
enable you to use it.

@menu
* Using Edebug::		Introduction to use of Edebug.
* Instrumenting::		You must instrument your code
				  in order to debug it with Edebug.

  While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
function or macro called by the list form after point, if is not already
instrumented.  This is possible only if Edebug knows where to find the
source for that function; for this reading, after loading Edebug,
@code{eval-region} records the position of every definition it
evaluates, even if not instrumenting it.  See also the @kbd{i} command
(@pxref{Jumping}), which steps into the call after instrumenting the
function.

  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.

Keyboard macros containing the commands in this section do not
completely work: exiting from Edebug, to resume the program, loses track
of the keyboard macro.  This is not easy to fix.  Also, defining or
executing a keyboard macro outside of Edebug does not affect commands
inside Edebug.  This is usually an advantage.  See also the
@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).

When you enter a new Edebug level, the initial execution mode comes
from the value of the variable @code{edebug-initial-mode}.
(@xref{Edebug Options}.)  By default, this specifies step mode.  Note
that you may reenter the same Edebug level several times if, for
example, an instrumented function is called several times from one
command.

@defopt edebug-sit-for-seconds
This option specifies how many seconds to wait between execution steps
in trace mode.  The default is 1 second.
@end defopt

@node Jumping
@subsection Jumping

@item f
Run the program for one expression
(@code{edebug-forward-sexp}).

@item o
Run the program until the end of the containing sexp.

@item i
Step into the function or macro called by the form after point.
@end table

The @kbd{h} command proceeds to the stop point at or after the current
location of point, using a temporary breakpoint.

The @kbd{f} command runs the program forward over one expression.  More
precisely, it sets a temporary breakpoint at the position that
@kbd{C-M-f} would reach, then executes in go mode so that the program
will stop at breakpoints.

With a prefix argument @var{n}, the temporary breakpoint is placed
@var{n} sexps beyond point.  If the containing list ends before @var{n}
more elements, then the place to stop is after the containing
expression.

You must check that the position @kbd{C-M-f} finds is a place that the
program will really get to.  In @code{cond}, for example, this may not
be true.

For flexibility, the @kbd{f} command does @code{forward-sexp} starting
at point, rather than at the stop point.  If you want to execute one
expression @emph{from the current stop point}, first type @kbd{w}, to
move point there, and then type @kbd{f}.

The @kbd{o} command continues ``out of'' an expression.  It places a
temporary breakpoint at the end of the sexp containing point.  If the
containing sexp is a function definition itself, @kbd{o} continues until
just before the last sexp in the definition.  If that is where you are

@code{unwind-protect} or @code{condition-case} forms may resume
debugging.

@item Q
Like @kbd{q}, but don't stop even for protected code
(@code{top-level-nonstop}).

@item r
Redisplay the most recently known expression result in the echo area
(@code{edebug-previous-result}).

Evaluate expression @var{exp} in the context outside of Edebug
(@code{edebug-eval-expression}).  That is, Edebug tries to minimize its
interference with the evaluation.

@item M-: @var{exp} @key{RET}
Evaluate expression @var{exp} in the context of Edebug itself.

@item C-x C-e
Evaluate the expression before point, in the context outside of Edebug
(@code{edebug-eval-last-sexp}).
@end table

@cindex lexical binding (Edebug)
  Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in
@file{cl.el} (version 2.03 or later): @code{lexical-let},
@code{macrolet}, and @code{symbol-macrolet}.

@node Eval List
@subsection Evaluation List Buffer

  You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to

expression in the buffer, followed by its current value.  It also
inserts comment lines so that each expression becomes its own group.
Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
the evaluation list is effectively unchanged.

  If an error occurs during an evaluation from the evaluation list, the
error message is displayed in a string as if it were the result.
Therefore, expressions that use variables not currently valid do not
interrupt your debugging.

  Here is an example of what the evaluation list window looks like after
several expressions have been added to it:

@smallexample

  If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.

  One way to cope with circular structure is to set @code{print-length}
or @code{print-level} to truncate the printing.  Edebug does this for
you; it binds @code{print-length} and @code{print-level} to 50 if they
were @code{nil}.  (Actually, the variables @code{edebug-print-length}
and @code{edebug-print-level} specify the values to use within Edebug.)
@xref{Output Variables}.

@defopt edebug-print-length
If non-@code{nil}, Edebug binds @code{print-length} to this value while
printing results.  The default value is @code{50}.
@end defopt

correctly; Edebug will tell you when you have tried enough different
conditions that each form has returned two different values.

  Coverage testing makes execution slower, so it is only done if
@code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
performed for all execution of an instrumented function, even if the
execution mode is Go-nonstop, and regardless of whether coverage testing
is enabled.

@kindex C-x X =
@findex edebug-temp-display-freq-count

@deffn Command edebug-display-freq-count
This command displays the frequency count data for each line of the
current definition.

The frequency counts appear as comment lines after each line of code,
and you can undo all insertions with one @code{undo} command.  The
counts appear under the @samp{(} before an expression or the @samp{)}
after an expression, or on the last character of a variable.  To
simplify the display, a count is not shown if it is equal to the
count of an earlier expression on the same line.

The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated.
In other words, it is not yet ``covered'' for coverage testing purposes.

program.

@itemize @bullet
@item
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
incremented once to reduce Edebug's impact on the stack.  You could,
however, still run out of stack space when using Edebug.

@item
The state of keyboard macro execution is saved and restored.  While
Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
unless @code{edebug-continue-kbd-macro} is non-@code{nil}.

The value of point in each displayed buffer is saved and restored if
@code{edebug-save-displayed-buffer-points} is non-@code{nil}.

@item
The variables @code{overlay-arrow-position} and
@code{overlay-arrow-string} are saved and restored.  So you can safely
invoke Edebug from the recursive edit elsewhere in the same buffer.

@item
@code{cursor-in-echo-area} is locally bound to @code{nil} so that
the cursor shows up in the window.

  (declare (debug (symbolp "from" form "to" form "do" &rest form)))
  ...)
@end smallexample

  The Edebug specification says which parts of a call to the macro are
forms to be evaluated.  For simple macros, the @var{specification}
often looks very similar to the formal argument list of the macro
definition, but specifications are much more general than macro
arguments.  @xref{Defining Macros}, for more explanation of
the @code{declare} form.

@item @code{0}
None of the arguments is instrumented.

@item a symbol
The symbol must have an Edebug specification which is used instead.
This indirection is repeated until another kind of specification is
found.  This allows you to inherit the specification from another macro.

@item a list
The elements of the list describe the types of the arguments of a
calling form.  The possible elements of a specification list are
described in the following sections.
@end table

@vindex edebug-eval-macro-args
If a macro has no Edebug specification, neither through a @code{debug}
declaration nor through a @code{def-edebug-spec} call, the variable
@code{edebug-eval-macro-args} comes into play.  If it is @code{nil},
the default, none of the arguments is instrumented for evaluation.
If it is non-@code{nil}, all arguments are instrumented.

@node Specification List
@subsubsection Specification List

@cindex Edebug specification list

and groups thus subdivide the specification list into a hierarchy of
levels.  Specification keywords apply only to the remainder of the
sublist or group they are contained in.

When a specification list involves alternatives or repetition, matching
it against an actual macro call may require backtracking.
@xref{Backtracking}, for more details.

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

@item form
A single evaluated expression, which is instrumented.

@item place
@findex edebug-unwrap
A place to store a value, as in the Common Lisp @code{setf} construct.

@item body
Short for @code{&rest form}.  See @code{&rest} below.

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.

Some suitable predicates include @code{symbolp}, @code{integerp},
@code{stringp}, @code{vectorp}, and @code{atom}.

@item [@var{elements}@dots{}]

the definition.  Use @code{def-body} for the highest level list of forms
within the definition.

@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

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.

When a syntax error is detected, it might not be reported until much
later after higher-level alternatives have been exhausted, and with the
point positioned further from the real error.  But if backtracking is
disabled when an error occurs, it can be reported immediately.  Note
that backtracking is also reenabled automatically in several situations;
it is reenabled when a new alternative is established by
@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
processing a sublist, group, or indirect specification.  The effect of
enabling or disabling backtracking is limited to the remainder of the
level currently being processed and lower levels.

Backtracking is disabled while matching any of the
form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
@code{def-body}).  These specifications will match any form so any error
must be in the form itself rather than at a higher level.

A @code{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 @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.

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

Edebug uses the following specifications for @code{defun} and
@code{defmacro} and the associated argument list and @code{interactive}
specifications.  It is necessary to handle interactive forms specially
since an expression argument is actually evaluated outside of the
function body.

@smallexample
(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
(def-edebug-spec defun
  (&define name lambda-list
           [&optional stringp]   ; @r{Match the doc string, if present.}
           [&optional ("interactive" interactive)]
           def-body))

@end smallexample

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

@smallexample
(def-edebug-spec ` (backquote-form))   ; @r{Alias just for clarity.}

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

@node Edebug Options
@subsection Edebug Options

  These options affect the behavior of Edebug:

@defopt edebug-setup-hook
Functions to call before Edebug is used.  Each time it is set to a new
value, Edebug will call those functions once and then
@code{edebug-setup-hook} is reset to @code{nil}.  You could use this to

@defopt edebug-save-displayed-buffer-points
If this is non-@code{nil}, Edebug saves and restores point in all
displayed buffers.

Saving and restoring point in other buffers is necessary if you are
debugging code that changes the point of a buffer which is displayed in
a non-selected window.  If Edebug or the user then selects the window,
point in that buffer will move to the window's value of point.

Saving and restoring point in all buffers is expensive, since it
requires selecting each window twice, so enable this only if you need

that is executing outside of Edebug.   Use this with caution since it is not
debugged.
@xref{Edebug Execution Modes}.
@end defopt

@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
@code{debug-on-error} was previously @code{nil}.  @xref{Trapping
Errors}.
@end defopt

103897:e52d10e14bc0

@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
@cindex Edebug debugging facility

  Edebug is a source-level debugger for Emacs Lisp programs, with which
you can:

@itemize @bullet
@item
Step through evaluation, stopping before and after each expression.

@item
Automatically re-evaluate a list of expressions and
display their results each time Edebug updates the display.

@item
Output trace information on function calls and returns.

@item
Stop when an error occurs.

@item

@item
Obtain rudimentary coverage testing and frequency counts.
@end itemize

The first three sections below should tell you enough about Edebug to
start using it.

@menu
* Using Edebug::		Introduction to use of Edebug.
* Instrumenting::		You must instrument your code
				  in order to debug it with Edebug.

  While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
function or macro called by the list form after point, if is not already
instrumented.  This is possible only if Edebug knows where to find the
source for that function; for this reason, after loading Edebug,
@code{eval-region} records the position of every definition it
evaluates, even if not instrumenting it.  See also the @kbd{i} command
(@pxref{Jumping}), which steps into the call after instrumenting the
function.

  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; for details, @pxref{Edebug and Macros}.

  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.

Keyboard macros containing the commands in this section do not
completely work: exiting from Edebug, to resume the program, loses track
of the keyboard macro.  This is not easy to fix.  Also, defining or
executing a keyboard macro outside of Edebug does not affect commands
inside Edebug.  This is usually an advantage.  See also the
@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}.

When you enter a new Edebug level, the initial execution mode comes
from the value of the variable @code{edebug-initial-mode}
(@pxref{Edebug Options}).  By default, this specifies step mode.  Note
that you may reenter the same Edebug level several times if, for
example, an instrumented function is called several times from one
command.

@defopt edebug-sit-for-seconds
This option specifies how many seconds to wait between execution steps
in trace mode or continue mode.  The default is 1 second.
@end defopt

@node Jumping
@subsection Jumping

@item f
Run the program for one expression
(@code{edebug-forward-sexp}).

@item o
Run the program until the end of the containing sexp (@code{edebug-step-out}).

@item i
Step into the function or macro called by the form after point.
@end table

The @kbd{h} command proceeds to the stop point at or after the current
location of point, using a temporary breakpoint.

The @kbd{f} command runs the program forward over one expression.  More
precisely, it sets a temporary breakpoint at the position that
@code{forward-sexp} would reach, then executes in go mode so that
the program will stop at breakpoints.

With a prefix argument @var{n}, the temporary breakpoint is placed
@var{n} sexps beyond point.  If the containing list ends before @var{n}
more elements, then the place to stop is after the containing
expression.

You must check that the position @code{forward-sexp} finds is a place
that the program will really get to.  In @code{cond}, for example,
this may not be true.

For flexibility, the @kbd{f} command does @code{forward-sexp} starting
at point, rather than at the stop point.  If you want to execute one
expression @emph{from the current stop point}, first type @kbd{w}
(@code{edebug-where}) to move point there, and then type @kbd{f}.

The @kbd{o} command continues ``out of'' an expression.  It places a
temporary breakpoint at the end of the sexp containing point.  If the
containing sexp is a function definition itself, @kbd{o} continues until
just before the last sexp in the definition.  If that is where you are

@code{unwind-protect} or @code{condition-case} forms may resume
debugging.

@item Q
Like @kbd{q}, but don't stop even for protected code
(@code{edebug-top-level-nonstop}).

@item r
Redisplay the most recently known expression result in the echo area
(@code{edebug-previous-result}).

Evaluate expression @var{exp} in the context outside of Edebug
(@code{edebug-eval-expression}).  That is, Edebug tries to minimize its
interference with the evaluation.

@item M-: @var{exp} @key{RET}
Evaluate expression @var{exp} in the context of Edebug itself
(@code{eval-expression}).

@item C-x C-e
Evaluate the expression before point, in the context outside of Edebug
(@code{edebug-eval-last-sexp}).
@end table

@cindex lexical binding (Edebug)
  Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in
@file{cl.el}: @code{lexical-let}, @code{macrolet}, and
@code{symbol-macrolet}.

@node Eval List
@subsection Evaluation List Buffer

  You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to

expression in the buffer, followed by its current value.  It also
inserts comment lines so that each expression becomes its own group.
Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
the evaluation list is effectively unchanged.

  If an error occurs during an evaluation from the evaluation list,
the error message is displayed in a string as if it were the result.
Therefore, expressions using variables that are not currently valid do
not interrupt your debugging.

  Here is an example of what the evaluation list window looks like after
several expressions have been added to it:

@smallexample

  If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.

  One way to cope with circular structure is to set @code{print-length}
or @code{print-level} to truncate the printing.  Edebug does this for
you; it binds @code{print-length} and @code{print-level} to the values
of the variables @code{edebug-print-length} and
@code{edebug-print-level} (so long as they have non-@code{nil}
values).  @xref{Output Variables}.

@defopt edebug-print-length
If non-@code{nil}, Edebug binds @code{print-length} to this value while
printing results.  The default value is @code{50}.
@end defopt

correctly; Edebug will tell you when you have tried enough different
conditions that each form has returned two different values.

  Coverage testing makes execution slower, so it is only done if
@code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
performed for all executions of an instrumented function, even if the
execution mode is Go-nonstop, and regardless of whether coverage testing
is enabled.

@kindex C-x X =
@findex edebug-temp-display-freq-count

@deffn Command edebug-display-freq-count
This command displays the frequency count data for each line of the
current definition.

It inserts frequency counts as comment lines after each line of code.
You can undo all insertions with one @code{undo} command.  The counts
appear under the @samp{(} before an expression or the @samp{)} after
an expression, or on the last character of a variable.  To simplify
the display, a count is not shown if it is equal to the count of an
earlier expression on the same line.

The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated.
In other words, it is not yet ``covered'' for coverage testing purposes.

program.

@itemize @bullet
@item
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
increased to reduce Edebug's impact on the stack.  You could, however,
still run out of stack space when using Edebug.

@item
The state of keyboard macro execution is saved and restored.  While
Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
unless @code{edebug-continue-kbd-macro} is non-@code{nil}.

The value of point in each displayed buffer is saved and restored if
@code{edebug-save-displayed-buffer-points} is non-@code{nil}.

@item
The variables @code{overlay-arrow-position} and
@code{overlay-arrow-string} are saved and restored, so you can safely
invoke Edebug from the recursive edit elsewhere in the same buffer.

@item
@code{cursor-in-echo-area} is locally bound to @code{nil} so that
the cursor shows up in the window.

  (declare (debug (symbolp "from" form "to" form "do" &rest form)))
  ...)
@end smallexample

  The Edebug specification says which parts of a call to the macro are
forms to be evaluated.  For simple macros, the specification
often looks very similar to the formal argument list of the macro
definition, but specifications are much more general than macro
arguments.  @xref{Defining Macros}, for more explanation of
the @code{declare} form.

@item @code{0}
None of the arguments is instrumented.

@item a symbol
The symbol must have an Edebug specification, which is used instead.
This indirection is repeated until another kind of specification is
found.  This allows you to inherit the specification from another macro.

@item a list
The elements of the list describe the types of the arguments of a
calling form.  The possible elements of a specification list are
described in the following sections.
@end table

If a macro has no Edebug specification, neither through a @code{debug}
declaration nor through a @code{def-edebug-spec} call, the variable
@code{edebug-eval-macro-args} comes into play.

@defopt edebug-eval-macro-args
This controls the way Edebug treats macro arguments with no explicit
Edebug specification.  If it is @code{nil} (the default), none of the
arguments is instrumented for evaluation.  Otherwise, all arguments
are instrumented.
@end defopt

@node Specification List
@subsubsection Specification List

@cindex Edebug specification list

and groups thus subdivide the specification list into a hierarchy of
levels.  Specification keywords apply only to the remainder of the
sublist or group they are contained in.

When a specification list involves alternatives or repetition, matching
it against an actual macro call may require backtracking.  For more
details, @pxref{Backtracking}.

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

@item form
A single evaluated expression, which is instrumented.

@item place
@c I can't see that this index entry is useful without any explanation.
@c @findex edebug-unwrap
A place to store a value, as in the Common Lisp @code{setf} construct.

@item body
Short for @code{&rest form}.  See @code{&rest} below.

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}, and the argument is not instrumented.

Some suitable predicates include @code{symbolp}, @code{integerp},
@code{stringp}, @code{vectorp}, and @code{atom}.

@item [@var{elements}@dots{}]

the definition.  Use @code{def-body} for the highest level list of forms
within the definition.

@item def-form
The argument is a single, highest-level form in a definition.  This is
like @code{def-body}, except it is used 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

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.

When a syntax error is detected, it might not be reported until much
later, after higher-level alternatives have been exhausted, and with the
point positioned further from the real error.  But if backtracking is
disabled when an error occurs, it can be reported immediately.  Note
that backtracking is also reenabled automatically in several situations;
when a new alternative is established by @code{&optional},
@code{&rest}, or @code{&or}, or at the start of processing a sublist,
group, or indirect specification.  The effect of enabling or disabling
backtracking is limited to the remainder of the level currently being
processed and lower levels.

Backtracking is disabled while matching any of the
form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
@code{def-body}).  These specifications will match any form so any error
must be in the form itself rather than at a higher level.

A @code{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 @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.

@c FIXME? The actual definition in edebug.el does not have a gate.
@example
(def-edebug-spec let
  ((&rest
    &or symbolp (gate symbolp &optional form))
   body))
@end example

Edebug uses the following specifications for @code{defun} and the
associated argument list and @code{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 @code{defmacro} is very similar to that for
@code{defun}, but allows for the @code{declare} statement.)

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

@end smallexample

The specification for backquote below illustrates how to match
dotted lists and use @code{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.)

@smallexample
(def-edebug-spec \` (backquote-form))   ; @r{Alias just for clarity.}

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

@node Edebug Options
@subsection Edebug Options

  These options affect the behavior of Edebug:
@c Previously defopt'd:
@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level
@c edebug-print-circle, edebug-eval-macro-args

@defopt edebug-setup-hook
Functions to call before Edebug is used.  Each time it is set to a new
value, Edebug will call those functions once and then
@code{edebug-setup-hook} is reset to @code{nil}.  You could use this to

@defopt edebug-save-displayed-buffer-points
If this is non-@code{nil}, Edebug saves and restores point in all
displayed buffers.

Saving and restoring point in other buffers is necessary if you are
debugging code that changes the point of a buffer that is displayed in
a non-selected window.  If Edebug or the user then selects the window,
point in that buffer will move to the window's value of point.

Saving and restoring point in all buffers is expensive, since it
requires selecting each window twice, so enable this only if you need

that is executing outside of Edebug.   Use this with caution since it is not
debugged.
@xref{Edebug Execution Modes}.
@end defopt

@c FIXME edebug-unwrap-results

@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
@code{debug-on-error} was previously @code{nil}.  @xref{Trapping
Errors}.
@end defopt