"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/lispref/edebug.texi" (14 Apr 2017, 64681 Bytes) of package /linux/misc/emacs-25.3.tar.xz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "edebug.texi": 25.1_vs_25.2.

    1 @comment -*-texinfo-*-
    2 @c This is part of the GNU Emacs Lisp Reference Manual.
    3 @c Copyright (C) 1992-1994, 1998-1999, 2001-2017 Free Software
    4 @c Foundation, Inc.
    5 @c See the file elisp.texi for copying conditions.
    7 @c This file can also be used by an independent Edebug User
    8 @c Manual in which case the Edebug node below should be used
    9 @c with the following links to the Bugs section and to the top level:
   11 @c , Bugs and Todo List, Top, Top
   13 @node Edebug
   14 @section Edebug
   15 @cindex Edebug debugging facility
   17   Edebug is a source-level debugger for Emacs Lisp programs, with which
   18 you can:
   20 @itemize @bullet
   21 @item
   22 Step through evaluation, stopping before and after each expression.
   24 @item
   25 Set conditional or unconditional breakpoints.
   27 @item
   28 Stop when a specified condition is true (the global break event).
   30 @item
   31 Trace slow or fast, stopping briefly at each stop point, or
   32 at each breakpoint.
   34 @item
   35 Display expression results and evaluate expressions as if outside of
   36 Edebug.
   38 @item
   39 Automatically re-evaluate a list of expressions and
   40 display their results each time Edebug updates the display.
   42 @item
   43 Output trace information on function calls and returns.
   45 @item
   46 Stop when an error occurs.
   48 @item
   49 Display a backtrace, omitting Edebug's own frames.
   51 @item
   52 Specify argument evaluation for macros and defining forms.
   54 @item
   55 Obtain rudimentary coverage testing and frequency counts.
   56 @end itemize
   58 The first three sections below should tell you enough about Edebug to
   59 start using it.
   61 @menu
   62 * Using Edebug::                Introduction to use of Edebug.
   63 * Instrumenting::               You must instrument your code
   64                                   in order to debug it with Edebug.
   65 * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
   66 * Jumping::                     Commands to jump to a specified place.
   67 * Misc: Edebug Misc.            Miscellaneous commands.
   68 * Breaks::                      Setting breakpoints to make the program stop.
   69 * Trapping Errors::             Trapping errors with Edebug.
   70 * Views: Edebug Views.          Views inside and outside of Edebug.
   71 * Eval: Edebug Eval.            Evaluating expressions within Edebug.
   72 * Eval List::                   Expressions whose values are displayed
   73                                   each time you enter Edebug.
   74 * Printing in Edebug::          Customization of printing.
   75 * Trace Buffer::                How to produce trace output in a buffer.
   76 * Coverage Testing::            How to test evaluation coverage.
   77 * The Outside Context::         Data that Edebug saves and restores.
   78 * Edebug and Macros::           Specifying how to handle macro calls.
   79 * Options: Edebug Options.      Option variables for customizing Edebug.
   80 @end menu
   82 @node Using Edebug
   83 @subsection Using Edebug
   85   To debug a Lisp program with Edebug, you must first @dfn{instrument}
   86 the Lisp code that you want to debug.  A simple way to do this is to
   87 first move point into the definition of a function or macro and then do
   88 @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument).  See
   89 @ref{Instrumenting}, for alternative ways to instrument code.
   91   Once a function is instrumented, any call to the function activates
   92 Edebug.  Depending on which Edebug execution mode you have selected,
   93 activating Edebug may stop execution and let you step through the
   94 function, or it may update the display and continue execution while
   95 checking for debugging commands.  The default execution mode is step,
   96 which stops execution.  @xref{Edebug Execution Modes}.
   98   Within Edebug, you normally view an Emacs buffer showing the source of
   99 the Lisp code you are debugging.  This is referred to as the @dfn{source
  100 code buffer}, and it is temporarily read-only.
  102   An arrow in the left fringe indicates the line where the function is
  103 executing.  Point initially shows where within the line the function is
  104 executing, but this ceases to be true if you move point yourself.
  106   If you instrument the definition of @code{fac} (shown below) and then
  107 execute @code{(fac 3)}, here is what you would normally see.  Point is
  108 at the open-parenthesis before @code{if}.
  110 @example
  111 (defun fac (n)
  112 =>@point{}(if (< 0 n)
  113       (* n (fac (1- n)))
  114     1))
  115 @end example
  117 @cindex stop points
  118 The places within a function where Edebug can stop execution are called
  119 @dfn{stop points}.  These occur both before and after each subexpression
  120 that is a list, and also after each variable reference.
  121 Here we use periods to show the stop points in the function
  122 @code{fac}:
  124 @example
  125 (defun fac (n)
  126   .(if .(< 0 n.).
  127       .(* n. .(fac .(1- n.).).).
  128     1).)
  129 @end example
  131 The special commands of Edebug are available in the source code buffer
  132 in addition to the commands of Emacs Lisp mode.  For example, you can
  133 type the Edebug command @key{SPC} to execute until the next stop point.
  134 If you type @key{SPC} once after entry to @code{fac}, here is the
  135 display you will see:
  137 @example
  138 (defun fac (n)
  139 =>(if @point{}(< 0 n)
  140       (* n (fac (1- n)))
  141     1))
  142 @end example
  144 When Edebug stops execution after an expression, it displays the
  145 expression's value in the echo area.
  147 Other frequently used commands are @kbd{b} to set a breakpoint at a stop
  148 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
  149 exit Edebug and return to the top-level command loop.  Type @kbd{?} to
  150 display a list of all Edebug commands.
  152 @node Instrumenting
  153 @subsection Instrumenting for Edebug
  154 @cindex instrumenting for Edebug
  156   In order to use Edebug to debug Lisp code, you must first
  157 @dfn{instrument} the code.  Instrumenting code inserts additional code
  158 into it, to invoke Edebug at the proper places.
  160 @kindex C-M-x
  161 @findex eval-defun (Edebug)
  162   When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
  163 prefix argument on a function definition, it instruments the
  164 definition before evaluating it.  (This does not modify the source
  165 code itself.)  If the variable @code{edebug-all-defs} is
  166 non-@code{nil}, that inverts the meaning of the prefix argument: in
  167 this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
  168 a prefix argument.  The default value of @code{edebug-all-defs} is
  169 @code{nil}.  The command @kbd{M-x edebug-all-defs} toggles the value
  170 of the variable @code{edebug-all-defs}.
  172 @findex eval-region @r{(Edebug)}
  173 @findex eval-buffer @r{(Edebug)}
  174 @findex eval-current-buffer @r{(Edebug)}
  175   If @code{edebug-all-defs} is non-@code{nil}, then the commands
  176 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
  177 also instrument any definitions they evaluate.  Similarly,
  178 @code{edebug-all-forms} controls whether @code{eval-region} should
  179 instrument @emph{any} form, even non-defining forms.  This doesn't apply
  180 to loading or evaluations in the minibuffer.  The command @kbd{M-x
  181 edebug-all-forms} toggles this option.
  183 @findex edebug-eval-top-level-form
  184 @findex edebug-defun
  185   Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
  186 instrument any top-level form regardless of the values of
  187 @code{edebug-all-defs} and @code{edebug-all-forms}.
  188 @code{edebug-defun} is an alias for @code{edebug-eval-top-level-form}.
  190   While Edebug is active, the command @kbd{I}
  191 (@code{edebug-instrument-callee}) instruments the definition of the
  192 function or macro called by the list form after point, if it is not already
  193 instrumented.  This is possible only if Edebug knows where to find the
  194 source for that function; for this reason, after loading Edebug,
  195 @code{eval-region} records the position of every definition it
  196 evaluates, even if not instrumenting it.  See also the @kbd{i} command
  197 (@pxref{Jumping}), which steps into the call after instrumenting the
  198 function.
  200   Edebug knows how to instrument all the standard special forms,
  201 @code{interactive} forms with an expression argument, anonymous lambda
  202 expressions, and other defining forms.  However, Edebug cannot determine
  203 on its own what a user-defined macro will do with the arguments of a
  204 macro call, so you must provide that information using Edebug
  205 specifications; for details, @pxref{Edebug and Macros}.
  207   When Edebug is about to instrument code for the first time in a
  208 session, it runs the hook @code{edebug-setup-hook}, then sets it to
  209 @code{nil}.  You can use this to load Edebug specifications
  210 associated with a package you are using, but only when you use Edebug.
  212 @findex eval-expression @r{(Edebug)}
  213   To remove instrumentation from a definition, simply re-evaluate its
  214 definition in a way that does not instrument.  There are two ways of
  215 evaluating forms that never instrument them: from a file with
  216 @code{load}, and from the minibuffer with @code{eval-expression}
  217 (@kbd{M-:}).
  219   If Edebug detects a syntax error while instrumenting, it leaves point
  220 at the erroneous code and signals an @code{invalid-read-syntax} error.
  221 @c FIXME?  I can't see that it "leaves point at the erroneous code".
  223   @xref{Edebug Eval}, for other evaluation functions available
  224 inside of Edebug.
  226 @node Edebug Execution Modes
  227 @subsection Edebug Execution Modes
  229 @cindex Edebug execution modes
  230 Edebug supports several execution modes for running the program you are
  231 debugging.  We call these alternatives @dfn{Edebug execution modes}; do
  232 not confuse them with major or minor modes.  The current Edebug execution mode
  233 determines how far Edebug continues execution before stopping---whether
  234 it stops at each stop point, or continues to the next breakpoint, for
  235 example---and how much Edebug displays the progress of the evaluation
  236 before it stops.
  238 Normally, you specify the Edebug execution mode by typing a command to
  239 continue the program in a certain mode.  Here is a table of these
  240 commands; all except for @kbd{S} resume execution of the program, at
  241 least for a certain distance.
  243 @table @kbd
  244 @item S
  245 Stop: don't execute any more of the program, but wait for more
  246 Edebug commands (@code{edebug-stop}).
  247 @c FIXME Does not work. http://debbugs.gnu.org/9764
  249 @item @key{SPC}
  250 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
  252 @item n
  253 Next: stop at the next stop point encountered after an expression
  254 (@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
  255 @ref{Jumping}.
  257 @item t
  258 Trace: pause (normally one second) at each Edebug stop point
  259 (@code{edebug-trace-mode}).
  261 @item T
  262 Rapid trace: update the display at each stop point, but don't actually
  263 pause (@code{edebug-Trace-fast-mode}).
  265 @item g
  266 Go: run until the next breakpoint (@code{edebug-go-mode}).  @xref{Breakpoints}.
  268 @item c
  269 Continue: pause one second at each breakpoint, and then continue
  270 (@code{edebug-continue-mode}).
  272 @item C
  273 Rapid continue: move point to each breakpoint, but don't pause
  274 (@code{edebug-Continue-fast-mode}).
  276 @item G
  277 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}).  You
  278 can still stop the program by typing @kbd{S}, or any editing command.
  279 @end table
  281 In general, the execution modes earlier in the above list run the
  282 program more slowly or stop sooner than the modes later in the list.
  284 When you enter a new Edebug level, Edebug will normally stop at the
  285 first instrumented function it encounters.  If you prefer to stop only
  286 at a break point, or not at all (for example, when gathering coverage
  287 data), change the value of @code{edebug-initial-mode} from its default
  288 @code{step} to @code{go}, or @code{Go-nonstop}, or one of its other
  289 values (@pxref{Edebug Options}).  You can do this readily with
  290 @kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}):
  292 @deffn Command edebug-set-initial-mode
  293 @kindex C-x C-a C-m
  294 This command, bound to @kbd{C-x C-a C-m}, sets
  295 @code{edebug-initial-mode}.  It prompts you for a key to indicate the
  296 mode.  You should enter one of the eight keys listed above, which sets
  297 the corresponding mode.
  298 @end deffn
  300 Note that you may reenter the same Edebug level several times if, for
  301 example, an instrumented function is called several times from one
  302 command.
  304 While executing or tracing, you can interrupt the execution by typing
  305 any Edebug command.  Edebug stops the program at the next stop point and
  306 then executes the command you typed.  For example, typing @kbd{t} during
  307 execution switches to trace mode at the next stop point.  You can use
  308 @kbd{S} to stop execution without doing anything else.
  310 If your function happens to read input, a character you type intending
  311 to interrupt execution may be read by the function instead.  You can
  312 avoid such unintended results by paying attention to when your program
  313 wants input.
  315 @cindex keyboard macros (Edebug)
  316 Keyboard macros containing the commands in this section do not
  317 completely work: exiting from Edebug, to resume the program, loses track
  318 of the keyboard macro.  This is not easy to fix.  Also, defining or
  319 executing a keyboard macro outside of Edebug does not affect commands
  320 inside Edebug.  This is usually an advantage.  See also the
  321 @code{edebug-continue-kbd-macro} option in @ref{Edebug Options}.
  323 @defopt edebug-sit-for-seconds
  324 This option specifies how many seconds to wait between execution steps
  325 in trace mode or continue mode.  The default is 1 second.
  326 @end defopt
  328 @node Jumping
  329 @subsection Jumping
  331   The commands described in this section execute until they reach a
  332 specified location.  All except @kbd{i} make a temporary breakpoint to
  333 establish the place to stop, then switch to go mode.  Any other
  334 breakpoint reached before the intended stop point will also stop
  335 execution.  @xref{Breakpoints}, for the details on breakpoints.
  337   These commands may fail to work as expected in case of nonlocal exit,
  338 as that can bypass the temporary breakpoint where you expected the
  339 program to stop.
  341 @table @kbd
  342 @item h
  343 Proceed to the stop point near where point is (@code{edebug-goto-here}).
  345 @item f
  346 Run the program for one expression
  347 (@code{edebug-forward-sexp}).
  349 @item o
  350 Run the program until the end of the containing sexp (@code{edebug-step-out}).
  352 @item i
  353 Step into the function or macro called by the form after point
  354 (@code{edebug-step-in}).
  355 @end table
  357 The @kbd{h} command proceeds to the stop point at or after the current
  358 location of point, using a temporary breakpoint.
  360 The @kbd{f} command runs the program forward over one expression.  More
  361 precisely, it sets a temporary breakpoint at the position that
  362 @code{forward-sexp} would reach, then executes in go mode so that
  363 the program will stop at breakpoints.
  365 With a prefix argument @var{n}, the temporary breakpoint is placed
  366 @var{n} sexps beyond point.  If the containing list ends before @var{n}
  367 more elements, then the place to stop is after the containing
  368 expression.
  370 You must check that the position @code{forward-sexp} finds is a place
  371 that the program will really get to.  In @code{cond}, for example,
  372 this may not be true.
  374 For flexibility, the @kbd{f} command does @code{forward-sexp} starting
  375 at point, rather than at the stop point.  If you want to execute one
  376 expression @emph{from the current stop point}, first type @kbd{w}
  377 (@code{edebug-where}) to move point there, and then type @kbd{f}.
  379 The @kbd{o} command continues out of an expression.  It places a
  380 temporary breakpoint at the end of the sexp containing point.  If the
  381 containing sexp is a function definition itself, @kbd{o} continues until
  382 just before the last sexp in the definition.  If that is where you are
  383 now, it returns from the function and then stops.  In other words, this
  384 command does not exit the currently executing function unless you are
  385 positioned after the last sexp.
  387 The @kbd{i} command steps into the function or macro called by the list
  388 form after point, and stops at its first stop point.  Note that the form
  389 need not be the one about to be evaluated.  But if the form is a
  390 function call about to be evaluated, remember to use this command before
  391 any of the arguments are evaluated, since otherwise it will be too late.
  393 The @kbd{i} command instruments the function or macro it's supposed to
  394 step into, if it isn't instrumented already.  This is convenient, but keep
  395 in mind that the function or macro remains instrumented unless you explicitly
  396 arrange to deinstrument it.
  398 @node Edebug Misc
  399 @subsection Miscellaneous Edebug Commands
  401   Some miscellaneous Edebug commands are described here.
  403 @table @kbd
  404 @item ?
  405 Display the help message for Edebug (@code{edebug-help}).
  407 @item C-]
  408 Abort one level back to the previous command level
  409 (@code{abort-recursive-edit}).
  411 @item q
  412 Return to the top level editor command loop (@code{top-level}).  This
  413 exits all recursive editing levels, including all levels of Edebug
  414 activity.  However, instrumented code protected with
  415 @code{unwind-protect} or @code{condition-case} forms may resume
  416 debugging.
  418 @item Q
  419 Like @kbd{q}, but don't stop even for protected code
  420 (@code{edebug-top-level-nonstop}).
  422 @item r
  423 Redisplay the most recently known expression result in the echo area
  424 (@code{edebug-previous-result}).
  426 @item d
  427 Display a backtrace, excluding Edebug's own functions for clarity
  428 (@code{edebug-backtrace}).
  430 You cannot use debugger commands in the backtrace buffer in Edebug as
  431 you would in the standard debugger.
  433 The backtrace buffer is killed automatically when you continue
  434 execution.
  435 @end table
  437 You can invoke commands from Edebug that activate Edebug again
  438 recursively.  Whenever Edebug is active, you can quit to the top level
  439 with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
  440 display a backtrace of all the pending evaluations with @kbd{d}.
  442 @node Breaks
  443 @subsection Breaks
  445 Edebug's step mode stops execution when the next stop point is reached.
  446 There are three other ways to stop Edebug execution once it has started:
  447 breakpoints, the global break condition, and source breakpoints.
  449 @menu
  450 * Breakpoints::                 Breakpoints at stop points.
  451 * Global Break Condition::      Breaking on an event.
  452 * Source Breakpoints::          Embedding breakpoints in source code.
  453 @end menu
  455 @node Breakpoints
  456 @subsubsection Edebug Breakpoints
  458 @cindex breakpoints (Edebug)
  459 While using Edebug, you can specify @dfn{breakpoints} in the program you
  460 are testing: these are places where execution should stop.  You can set a
  461 breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
  462 setting and unsetting breakpoints, the stop point that is affected is
  463 the first one at or after point in the source code buffer.  Here are the
  464 Edebug commands for breakpoints:
  466 @table @kbd
  467 @item b
  468 Set a breakpoint at the stop point at or after point
  469 (@code{edebug-set-breakpoint}).  If you use a prefix argument, the
  470 breakpoint is temporary---it turns off the first time it stops the
  471 program.
  473 @item u
  474 Unset the breakpoint (if any) at the stop point at or after
  475 point (@code{edebug-unset-breakpoint}).
  477 @item x @var{condition} @key{RET}
  478 Set a conditional breakpoint which stops the program only if
  479 evaluating @var{condition} produces a non-@code{nil} value
  480 (@code{edebug-set-conditional-breakpoint}).  With a prefix argument,
  481 the breakpoint is temporary.
  483 @item B
  484 Move point to the next breakpoint in the current definition
  485 (@code{edebug-next-breakpoint}).
  486 @end table
  488 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
  489 with @kbd{u}.  First move point to the Edebug stop point of your choice,
  490 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
  491 Unsetting a breakpoint where none has been set has no effect.
  493 Re-evaluating or reinstrumenting a definition removes all of its
  494 previous breakpoints.
  496 A @dfn{conditional breakpoint} tests a condition each time the program
  497 gets there.  Any errors that occur as a result of evaluating the
  498 condition are ignored, as if the result were @code{nil}.  To set a
  499 conditional breakpoint, use @kbd{x}, and specify the condition
  500 expression in the minibuffer.  Setting a conditional breakpoint at a
  501 stop point that has a previously established conditional breakpoint puts
  502 the previous condition expression in the minibuffer so you can edit it.
  504 You can make a conditional or unconditional breakpoint
  505 @dfn{temporary} by using a prefix argument with the command to set the
  506 breakpoint.  When a temporary breakpoint stops the program, it is
  507 automatically unset.
  509 Edebug always stops or pauses at a breakpoint, except when the Edebug
  510 mode is Go-nonstop.  In that mode, it ignores breakpoints entirely.
  512 To find out where your breakpoints are, use the @kbd{B} command, which
  513 moves point to the next breakpoint following point, within the same
  514 function, or to the first breakpoint if there are no following
  515 breakpoints.  This command does not continue execution---it just moves
  516 point in the buffer.
  518 @node Global Break Condition
  519 @subsubsection Global Break Condition
  521 @cindex stopping on events
  522 @cindex global break condition
  523   A @dfn{global break condition} stops execution when a specified
  524 condition is satisfied, no matter where that may occur.  Edebug
  525 evaluates the global break condition at every stop point; if it
  526 evaluates to a non-@code{nil} value, then execution stops or pauses
  527 depending on the execution mode, as if a breakpoint had been hit.  If
  528 evaluating the condition gets an error, execution does not stop.
  530 @findex edebug-set-global-break-condition
  531   The condition expression is stored in
  532 @code{edebug-global-break-condition}.  You can specify a new expression
  533 using the @kbd{X} command from the source code buffer while Edebug is
  534 active, or using @kbd{C-x X X} from any buffer at any time, as long as
  535 Edebug is loaded (@code{edebug-set-global-break-condition}).
  537   The global break condition is the simplest way to find where in your
  538 code some event occurs, but it makes code run much more slowly.  So you
  539 should reset the condition to @code{nil} when not using it.
  541 @node Source Breakpoints
  542 @subsubsection Source Breakpoints
  544 @findex edebug
  545 @cindex source breakpoints
  546   All breakpoints in a definition are forgotten each time you
  547 reinstrument it.  If you wish to make a breakpoint that won't be
  548 forgotten, you can write a @dfn{source breakpoint}, which is simply a
  549 call to the function @code{edebug} in your source code.  You can, of
  550 course, make such a call conditional.  For example, in the @code{fac}
  551 function, you can insert the first line as shown below, to stop when the
  552 argument reaches zero:
  554 @example
  555 (defun fac (n)
  556   (if (= n 0) (edebug))
  557   (if (< 0 n)
  558       (* n (fac (1- n)))
  559     1))
  560 @end example
  562   When the @code{fac} definition is instrumented and the function is
  563 called, the call to @code{edebug} acts as a breakpoint.  Depending on
  564 the execution mode, Edebug stops or pauses there.
  566   If no instrumented code is being executed when @code{edebug} is called,
  567 that function calls @code{debug}.
  568 @c This may not be a good idea anymore.
  570 @node Trapping Errors
  571 @subsection Trapping Errors
  573   Emacs normally displays an error message when an error is signaled and
  574 not handled with @code{condition-case}.  While Edebug is active and
  575 executing instrumented code, it normally responds to all unhandled
  576 errors.  You can customize this with the options @code{edebug-on-error}
  577 and @code{edebug-on-quit}; see @ref{Edebug Options}.
  579   When Edebug responds to an error, it shows the last stop point
  580 encountered before the error.  This may be the location of a call to a
  581 function which was not instrumented, and within which the error actually
  582 occurred.  For an unbound variable error, the last known stop point
  583 might be quite distant from the offending variable reference.  In that
  584 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
  586 @c Edebug should be changed for the following: -- dan
  587   If you change @code{debug-on-error} or @code{debug-on-quit} while
  588 Edebug is active, these changes will be forgotten when Edebug becomes
  589 inactive.  Furthermore, during Edebug's recursive edit, these variables
  590 are bound to the values they had outside of Edebug.
  592 @node Edebug Views
  593 @subsection Edebug Views
  595   These Edebug commands let you view aspects of the buffer and window
  596 status as they were before entry to Edebug.  The outside window
  597 configuration is the collection of windows and contents that were in
  598 effect outside of Edebug.
  600 @table @kbd
  601 @item v
  602 Switch to viewing the outside window configuration
  603 (@code{edebug-view-outside}).  Type @kbd{C-x X w} to return to Edebug.
  605 @item p
  606 Temporarily display the outside current buffer with point at its
  607 outside position (@code{edebug-bounce-point}), pausing for one second
  608 before returning to Edebug.  With a prefix argument @var{n}, pause for
  609 @var{n} seconds instead.
  611 @item w
  612 Move point back to the current stop point in the source code buffer
  613 (@code{edebug-where}).
  615 If you use this command in a different window displaying the same
  616 buffer, that window will be used instead to display the current
  617 definition in the future.
  619 @item W
  620 @c Its function is not simply to forget the saved configuration -- dan
  621 Toggle whether Edebug saves and restores the outside window
  622 configuration (@code{edebug-toggle-save-windows}).
  624 With a prefix argument, @code{W} only toggles saving and restoring of
  625 the selected window.  To specify a window that is not displaying the
  626 source code buffer, you must use @kbd{C-x X W} from the global keymap.
  627 @end table
  629   You can view the outside window configuration with @kbd{v} or just
  630 bounce to the point in the current buffer with @kbd{p}, even if
  631 it is not normally displayed.
  633   After moving point, you may wish to jump back to the stop point.
  634 You can do that with @kbd{w} from a source code buffer.  You can jump
  635 back to the stop point in the source code buffer from any buffer using
  636 @kbd{C-x X w}.
  638   Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
  639 saved outside window configuration---so that even if you turn saving
  640 back @emph{on}, the current window configuration remains unchanged when
  641 you next exit Edebug (by continuing the program).  However, the
  642 automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may
  643 conflict with the buffers you wish to see unless you have enough windows
  644 open.
  646 @node Edebug Eval
  647 @subsection Evaluation
  649   While within Edebug, you can evaluate expressions as if Edebug
  650 were not running.  Edebug tries to be invisible to the expression's
  651 evaluation and printing.  Evaluation of expressions that cause side
  652 effects will work as expected, except for changes to data that Edebug
  653 explicitly saves and restores.  @xref{The Outside Context}, for details
  654 on this process.
  656 @table @kbd
  657 @item e @var{exp} @key{RET}
  658 Evaluate expression @var{exp} in the context outside of Edebug
  659 (@code{edebug-eval-expression}).  That is, Edebug tries to minimize its
  660 interference with the evaluation.
  662 @item M-: @var{exp} @key{RET}
  663 Evaluate expression @var{exp} in the context of Edebug itself
  664 (@code{eval-expression}).
  666 @item C-x C-e
  667 Evaluate the expression before point, in the context outside of Edebug
  668 (@code{edebug-eval-last-sexp}).
  669 @end table
  671 @cindex lexical binding (Edebug)
  672   Edebug supports evaluation of expressions containing references to
  673 lexically bound symbols created by the following constructs in
  674 @file{cl.el}: @code{lexical-let}, @code{macrolet}, and
  675 @code{symbol-macrolet}.
  676 @c FIXME?  What about lexical-binding = t?
  678 @node Eval List
  679 @subsection Evaluation List Buffer
  681   You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to
  682 evaluate expressions interactively.  You can also set up the
  683 @dfn{evaluation list} of expressions to be evaluated automatically each
  684 time Edebug updates the display.
  686 @table @kbd
  687 @item E
  688 Switch to the evaluation list buffer @file{*edebug*}
  689 (@code{edebug-visit-eval-list}).
  690 @end table
  692   In the @file{*edebug*} buffer you can use the commands of Lisp
  693 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
  694 Manual}) as well as these special commands:
  696 @table @kbd
  697 @item C-j
  698 Evaluate the expression before point, in the outside context, and insert
  699 the value in the buffer (@code{edebug-eval-print-last-sexp}).
  701 @item C-x C-e
  702 Evaluate the expression before point, in the context outside of Edebug
  703 (@code{edebug-eval-last-sexp}).
  705 @item C-c C-u
  706 Build a new evaluation list from the contents of the buffer
  707 (@code{edebug-update-eval-list}).
  709 @item C-c C-d
  710 Delete the evaluation list group that point is in
  711 (@code{edebug-delete-eval-item}).
  713 @item C-c C-w
  714 Switch back to the source code buffer at the current stop point
  715 (@code{edebug-where}).
  716 @end table
  718   You can evaluate expressions in the evaluation list window with
  719 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*};
  720 but they are evaluated in the context outside of Edebug.
  722   The expressions you enter interactively (and their results) are lost
  723 when you continue execution; but you can set up an @dfn{evaluation list}
  724 consisting of expressions to be evaluated each time execution stops.
  726 @cindex evaluation list group
  727   To do this, write one or more @dfn{evaluation list groups} in the
  728 evaluation list buffer.  An evaluation list group consists of one or
  729 more Lisp expressions.  Groups are separated by comment lines.
  731   The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
  732 evaluation list, scanning the buffer and using the first expression of
  733 each group.  (The idea is that the second expression of the group is the
  734 value previously computed and displayed.)
  736   Each entry to Edebug redisplays the evaluation list by inserting each
  737 expression in the buffer, followed by its current value.  It also
  738 inserts comment lines so that each expression becomes its own group.
  739 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
  740 the evaluation list is effectively unchanged.
  742   If an error occurs during an evaluation from the evaluation list,
  743 the error message is displayed in a string as if it were the result.
  744 Therefore, expressions using variables that are not currently valid do
  745 not interrupt your debugging.
  747   Here is an example of what the evaluation list window looks like after
  748 several expressions have been added to it:
  750 @smallexample
  751 (current-buffer)
  752 #<buffer *scratch*>
  753 ;---------------------------------------------------------------
  754 (selected-window)
  755 #<window 16 on *scratch*>
  756 ;---------------------------------------------------------------
  757 (point)
  758 196
  759 ;---------------------------------------------------------------
  760 bad-var
  761 "Symbol's value as variable is void: bad-var"
  762 ;---------------------------------------------------------------
  763 (recursion-depth)
  764 0
  765 ;---------------------------------------------------------------
  766 this-command
  767 eval-last-sexp
  768 ;---------------------------------------------------------------
  769 @end smallexample
  771 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
  772 delete the text for the group and update the evaluation list with
  773 @kbd{C-c C-u}.  To add a new expression to the evaluation list, insert
  774 the expression at a suitable place, insert a new comment line, then type
  775 @kbd{C-c C-u}.  You need not insert dashes in the comment line---its
  776 contents don't matter.
  778 After selecting @file{*edebug*}, you can return to the source code
  779 buffer with @kbd{C-c C-w}.  The @file{*edebug*} buffer is killed when
  780 you continue execution, and recreated next time it is needed.
  782 @node Printing in Edebug
  783 @subsection Printing in Edebug
  785 @cindex printing (Edebug)
  786 @cindex printing circular structures
  787 @pindex cust-print
  788   If an expression in your program produces a value containing circular
  789 list structure, you may get an error when Edebug attempts to print it.
  791   One way to cope with circular structure is to set @code{print-length}
  792 or @code{print-level} to truncate the printing.  Edebug does this for
  793 you; it binds @code{print-length} and @code{print-level} to the values
  794 of the variables @code{edebug-print-length} and
  795 @code{edebug-print-level} (so long as they have non-@code{nil}
  796 values).  @xref{Output Variables}.
  798 @defopt edebug-print-length
  799 If non-@code{nil}, Edebug binds @code{print-length} to this value while
  800 printing results.  The default value is @code{50}.
  801 @end defopt
  803 @defopt edebug-print-level
  804 If non-@code{nil}, Edebug binds @code{print-level} to this value while
  805 printing results.  The default value is @code{50}.
  806 @end defopt
  808   You can also print circular structures and structures that share
  809 elements more informatively by binding @code{print-circle}
  810 to a non-@code{nil} value.
  812   Here is an example of code that creates a circular structure:
  814 @example
  815 (setq a '(x y))
  816 (setcar a a)
  817 @end example
  819 @noindent
  820 Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
  821 @samp{#1=} notation labels the structure that follows it with the label
  822 @samp{1}, and the @samp{#1#} notation references the previously labeled
  823 structure.  This notation is used for any shared elements of lists or
  824 vectors.
  826 @defopt edebug-print-circle
  827 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
  828 printing results.  The default value is @code{t}.
  829 @end defopt
  831   Other programs can also use custom printing; see @file{cust-print.el}
  832 for details.
  834 @node Trace Buffer
  835 @subsection Trace Buffer
  836 @cindex trace buffer
  838   Edebug can record an execution trace, storing it in a buffer named
  839 @file{*edebug-trace*}.  This is a log of function calls and returns,
  840 showing the function names and their arguments and values.  To enable
  841 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
  843   Making a trace buffer is not the same thing as using trace execution
  844 mode (@pxref{Edebug Execution Modes}).
  846   When trace recording is enabled, each function entry and exit adds
  847 lines to the trace buffer.  A function entry record consists of
  848 @samp{::::@{}, followed by the function name and argument values.  A
  849 function exit record consists of @samp{::::@}}, followed by the function
  850 name and result of the function.
  852   The number of @samp{:}s in an entry shows its recursion depth.  You
  853 can use the braces in the trace buffer to find the matching beginning or
  854 end of function calls.
  856 @findex edebug-print-trace-before
  857 @findex edebug-print-trace-after
  858   You can customize trace recording for function entry and exit by
  859 redefining the functions @code{edebug-print-trace-before} and
  860 @code{edebug-print-trace-after}.
  862 @defmac edebug-tracing string body@dots{}
  863 This macro requests additional trace information around the execution
  864 of the @var{body} forms.  The argument @var{string} specifies text
  865 to put in the trace buffer, after the @samp{@{} or @samp{@}}.  All
  866 the arguments are evaluated, and @code{edebug-tracing} returns the
  867 value of the last form in @var{body}.
  868 @end defmac
  870 @defun edebug-trace format-string &rest format-args
  871 This function inserts text in the trace buffer.  It computes the text
  872 with @code{(apply 'format @var{format-string} @var{format-args})}.
  873 It also appends a newline to separate entries.
  874 @end defun
  876   @code{edebug-tracing} and @code{edebug-trace} insert lines in the
  877 trace buffer whenever they are called, even if Edebug is not active.
  878 Adding text to the trace buffer also scrolls its window to show the last
  879 lines inserted.
  881 @node Coverage Testing
  882 @subsection Coverage Testing
  884 @cindex coverage testing (Edebug)
  885 @cindex frequency counts
  886 @cindex performance analysis
  887   Edebug provides rudimentary coverage testing and display of execution
  888 frequency.
  890   Coverage testing works by comparing the result of each expression with
  891 the previous result; each form in the program is considered covered
  892 if it has returned two different values since you began testing coverage
  893 in the current Emacs session.  Thus, to do coverage testing on your
  894 program, execute it under various conditions and note whether it behaves
  895 correctly; Edebug will tell you when you have tried enough different
  896 conditions that each form has returned two different values.
  898   Coverage testing makes execution slower, so it is only done if
  899 @code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
  900 performed for all executions of an instrumented function, even if the
  901 execution mode is Go-nonstop, and regardless of whether coverage testing
  902 is enabled.
  904 @kindex C-x X =
  905 @findex edebug-temp-display-freq-count
  906   Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
  907 the coverage information and the frequency counts for a definition.
  908 Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
  909 information temporarily, only until you type another key.
  911 @deffn Command edebug-display-freq-count
  912 This command displays the frequency count data for each line of the
  913 current definition.
  915 It inserts frequency counts as comment lines after each line of code.
  916 You can undo all insertions with one @code{undo} command.  The counts
  917 appear under the @samp{(} before an expression or the @samp{)} after
  918 an expression, or on the last character of a variable.  To simplify
  919 the display, a count is not shown if it is equal to the count of an
  920 earlier expression on the same line.
  922 The character @samp{=} following the count for an expression says that
  923 the expression has returned the same value each time it was evaluated.
  924 In other words, it is not yet covered for coverage testing purposes.
  926 To clear the frequency count and coverage data for a definition,
  927 simply reinstrument it with @code{eval-defun}.
  928 @end deffn
  930 For example, after evaluating @code{(fac 5)} with a source
  931 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
  932 the breakpoint is reached, the frequency data looks like this:
  934 @example
  935 (defun fac (n)
  936   (if (= n 0) (edebug))
  937 ;#6           1      = =5
  938   (if (< 0 n)
  939 ;#5         =
  940       (* n (fac (1- n)))
  941 ;#    5               0
  942     1))
  943 ;#   0
  944 @end example
  946 The comment lines show that @code{fac} was called 6 times.  The
  947 first @code{if} statement returned 5 times with the same result each
  948 time; the same is true of the condition on the second @code{if}.
  949 The recursive call of @code{fac} did not return at all.
  952 @node The Outside Context
  953 @subsection The Outside Context
  955 Edebug tries to be transparent to the program you are debugging, but it
  956 does not succeed completely.  Edebug also tries to be transparent when
  957 you evaluate expressions with @kbd{e} or with the evaluation list
  958 buffer, by temporarily restoring the outside context.  This section
  959 explains precisely what context Edebug restores, and how Edebug fails to
  960 be completely transparent.
  962 @menu
  963 * Checking Whether to Stop::    When Edebug decides what to do.
  964 * Edebug Display Update::       When Edebug updates the display.
  965 * Edebug Recursive Edit::       When Edebug stops execution.
  966 @end menu
  968 @node Checking Whether to Stop
  969 @subsubsection Checking Whether to Stop
  971 Whenever Edebug is entered, it needs to save and restore certain data
  972 before even deciding whether to make trace information or stop the
  973 program.
  975 @itemize @bullet
  976 @item
  977 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
  978 increased to reduce Edebug's impact on the stack.  You could, however,
  979 still run out of stack space when using Edebug.
  981 @item
  982 The state of keyboard macro execution is saved and restored.  While
  983 Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
  984 unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
  985 @end itemize
  988 @node Edebug Display Update
  989 @subsubsection Edebug Display Update
  991 @c This paragraph is not filled, because LaLiberte's conversion script
  992 @c needs an xref to be on just one line.
  993 When Edebug needs to display something (e.g., in trace mode), it saves
  994 the current window configuration from outside Edebug
  995 (@pxref{Window Configurations}).  When you exit Edebug, it restores
  996 the previous window configuration.
  998 Emacs redisplays only when it pauses.  Usually, when you continue
  999 execution, the program re-enters Edebug at a breakpoint or after
 1000 stepping, without pausing or reading input in between.  In such cases,
 1001 Emacs never gets a chance to redisplay the outside configuration.
 1002 Consequently, what you see is the same window configuration as the last
 1003 time Edebug was active, with no interruption.
 1005 Entry to Edebug for displaying something also saves and restores the
 1006 following data (though some of them are deliberately not restored if an
 1007 error or quit signal occurs).
 1009 @itemize @bullet
 1010 @item
 1011 @cindex current buffer point and mark (Edebug)
 1012 Which buffer is current, and the positions of point and the mark in the
 1013 current buffer, are saved and restored.
 1015 @item
 1016 @cindex window configuration (Edebug)
 1017 The outside window configuration is saved and restored if
 1018 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
 1020 The window configuration is not restored on error or quit, but the
 1021 outside selected window @emph{is} reselected even on error or quit in
 1022 case a @code{save-excursion} is active.  If the value of
 1023 @code{edebug-save-windows} is a list, only the listed windows are saved
 1024 and restored.
 1026 The window start and horizontal scrolling of the source code buffer are
 1027 not restored, however, so that the display remains coherent within Edebug.
 1029 @item
 1030 The value of point in each displayed buffer is saved and restored if
 1031 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
 1033 @item
 1034 The variables @code{overlay-arrow-position} and
 1035 @code{overlay-arrow-string} are saved and restored, so you can safely
 1036 invoke Edebug from the recursive edit elsewhere in the same buffer.
 1038 @item
 1039 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
 1040 the cursor shows up in the window.
 1041 @end itemize
 1043 @node Edebug Recursive Edit
 1044 @subsubsection Edebug Recursive Edit
 1046 When Edebug is entered and actually reads commands from the user, it
 1047 saves (and later restores) these additional data:
 1049 @itemize @bullet
 1050 @item
 1051 The current match data.  @xref{Match Data}.
 1053 @item
 1054 The variables @code{last-command}, @code{this-command},
 1055 @code{last-command-event}, @code{last-input-event},
 1056 @code{last-event-frame}, @code{last-nonmenu-event}, and
 1057 @code{track-mouse}.  Commands in Edebug do not affect these variables
 1058 outside of Edebug.
 1060 Executing commands within Edebug can change the key sequence that
 1061 would be returned by @code{this-command-keys}, and there is no way to
 1062 reset the key sequence from Lisp.
 1064 Edebug cannot save and restore the value of
 1065 @code{unread-command-events}.  Entering Edebug while this variable has a
 1066 nontrivial value can interfere with execution of the program you are
 1067 debugging.
 1069 @item
 1070 Complex commands executed while in Edebug are added to the variable
 1071 @code{command-history}.  In rare cases this can alter execution.
 1073 @item
 1074 Within Edebug, the recursion depth appears one deeper than the recursion
 1075 depth outside Edebug.  This is not true of the automatically updated
 1076 evaluation list window.
 1078 @item
 1079 @code{standard-output} and @code{standard-input} are bound to @code{nil}
 1080 by the @code{recursive-edit}, but Edebug temporarily restores them during
 1081 evaluations.
 1083 @item
 1084 The state of keyboard macro definition is saved and restored.  While
 1085 Edebug is active, @code{defining-kbd-macro} is bound to
 1086 @code{edebug-continue-kbd-macro}.
 1087 @end itemize
 1089 @node Edebug and Macros
 1090 @subsection Edebug and Macros
 1092 To make Edebug properly instrument expressions that call macros, some
 1093 extra care is needed.  This subsection explains the details.
 1095 @menu
 1096 * Instrumenting Macro Calls::   The basic problem.
 1097 * Specification List::          How to specify complex patterns of evaluation.
 1098 * Backtracking::                What Edebug does when matching fails.
 1099 * Specification Examples::      To help understand specifications.
 1100 @end menu
 1102 @node Instrumenting Macro Calls
 1103 @subsubsection Instrumenting Macro Calls
 1105   When Edebug instruments an expression that calls a Lisp macro, it needs
 1106 additional information about the macro to do the job properly.  This is
 1107 because there is no a-priori way to tell which subexpressions of the
 1108 macro call are forms to be evaluated.  (Evaluation may occur explicitly
 1109 in the macro body, or when the resulting expansion is evaluated, or any
 1110 time later.)
 1112   Therefore, you must define an Edebug specification for each macro
 1113 that Edebug will encounter, to explain the format of calls to that
 1114 macro.  To do this, add a @code{debug} declaration to the macro
 1115 definition.  Here is a simple example that shows the specification for
 1116 the @code{for} example macro (@pxref{Argument Evaluation}).
 1118 @smallexample
 1119 (defmacro for (var from init to final do &rest body)
 1120   "Execute a simple \"for\" loop.
 1121 For example, (for i from 1 to 10 do (print i))."
 1122   (declare (debug (symbolp "from" form "to" form "do" &rest form)))
 1123   ...)
 1124 @end smallexample
 1126   The Edebug specification says which parts of a call to the macro are
 1127 forms to be evaluated.  For simple macros, the specification
 1128 often looks very similar to the formal argument list of the macro
 1129 definition, but specifications are much more general than macro
 1130 arguments.  @xref{Defining Macros}, for more explanation of
 1131 the @code{declare} form.
 1133 @c See, e.g., http://debbugs.gnu.org/10577
 1134 @c FIXME  Maybe there should be an Edebug option to get it to
 1135 @c automatically load the entire source file containing the function
 1136 @c being instrumented.  That would avoid this.
 1137   Take care to ensure that the specifications are known to Edebug when
 1138 you instrument code.  If you are instrumenting a function from a file
 1139 that uses @code{eval-when-compile} to require another file containing
 1140 macro definitions, you may need to explicitly load that file.
 1142   You can also define an edebug specification for a macro separately
 1143 from the macro definition with @code{def-edebug-spec}.  Adding
 1144 @code{debug} declarations is preferred, and more convenient, for macro
 1145 definitions in Lisp, but @code{def-edebug-spec} makes it possible to
 1146 define Edebug specifications for special forms implemented in C.
 1148 @defmac def-edebug-spec macro specification
 1149 Specify which expressions of a call to macro @var{macro} are forms to be
 1150 evaluated.  @var{specification} should be the edebug specification.
 1151 Neither argument is evaluated.
 1153 The @var{macro} argument can actually be any symbol, not just a macro
 1154 name.
 1155 @end defmac
 1157 Here is a table of the possibilities for @var{specification} and how each
 1158 directs processing of arguments.
 1160 @table @asis
 1161 @item @code{t}
 1162 All arguments are instrumented for evaluation.
 1164 @item @code{0}
 1165 None of the arguments is instrumented.
 1167 @item a symbol
 1168 The symbol must have an Edebug specification, which is used instead.
 1169 This indirection is repeated until another kind of specification is
 1170 found.  This allows you to inherit the specification from another macro.
 1172 @item a list
 1173 The elements of the list describe the types of the arguments of a
 1174 calling form.  The possible elements of a specification list are
 1175 described in the following sections.
 1176 @end table
 1178 If a macro has no Edebug specification, neither through a @code{debug}
 1179 declaration nor through a @code{def-edebug-spec} call, the variable
 1180 @code{edebug-eval-macro-args} comes into play.
 1182 @defopt edebug-eval-macro-args
 1183 This controls the way Edebug treats macro arguments with no explicit
 1184 Edebug specification.  If it is @code{nil} (the default), none of the
 1185 arguments is instrumented for evaluation.  Otherwise, all arguments
 1186 are instrumented.
 1187 @end defopt
 1189 @node Specification List
 1190 @subsubsection Specification List
 1192 @cindex Edebug specification list
 1193 A @dfn{specification list} is required for an Edebug specification if
 1194 some arguments of a macro call are evaluated while others are not.  Some
 1195 elements in a specification list match one or more arguments, but others
 1196 modify the processing of all following elements.  The latter, called
 1197 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
 1198 as @code{&optional}).
 1200 A specification list may contain sublists, which match arguments that are
 1201 themselves lists, or it may contain vectors used for grouping.  Sublists
 1202 and groups thus subdivide the specification list into a hierarchy of
 1203 levels.  Specification keywords apply only to the remainder of the
 1204 sublist or group they are contained in.
 1206 When a specification list involves alternatives or repetition, matching
 1207 it against an actual macro call may require backtracking.  For more
 1208 details, @pxref{Backtracking}.
 1210 Edebug specifications provide the power of regular expression matching,
 1211 plus some context-free grammar constructs: the matching of sublists with
 1212 balanced parentheses, recursive processing of forms, and recursion via
 1213 indirect specifications.
 1215 Here's a table of the possible elements of a specification list, with
 1216 their meanings (see @ref{Specification Examples}, for the referenced
 1217 examples):
 1219 @table @code
 1220 @item sexp
 1221 A single unevaluated Lisp object, which is not instrumented.
 1222 @c an "expression" is not necessarily intended for evaluation.
 1224 @item form
 1225 A single evaluated expression, which is instrumented.
 1227 @item place
 1228 A generalized variable.  @xref{Generalized Variables}.
 1230 @item body
 1231 Short for @code{&rest form}.  See @code{&rest} below.
 1233 @item function-form
 1234 A function form: either a quoted function symbol, a quoted lambda
 1235 expression, or a form (that should evaluate to a function symbol or
 1236 lambda expression).  This is useful when an argument that's a lambda
 1237 expression might be quoted with @code{quote} rather than
 1238 @code{function}, since it instruments the body of the lambda expression
 1239 either way.
 1241 @item lambda-expr
 1242 A lambda expression with no quoting.
 1244 @item &optional
 1245 @c @kindex &optional @r{(Edebug)}
 1246 All following elements in the specification list are optional; as soon
 1247 as one does not match, Edebug stops matching at this level.
 1249 To make just a few elements optional, followed by non-optional elements,
 1250 use @code{[&optional @var{specs}@dots{}]}.  To specify that several
 1251 elements must all match or none, use @code{&optional
 1252 [@var{specs}@dots{}]}.  See the @code{defun} example.
 1254 @item &rest
 1255 @c @kindex &rest @r{(Edebug)}
 1256 All following elements in the specification list are repeated zero or
 1257 more times.  In the last repetition, however, it is not a problem if the
 1258 expression runs out before matching all of the elements of the
 1259 specification list.
 1261 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
 1262 To specify several elements that must all match on every repetition, use
 1263 @code{&rest [@var{specs}@dots{}]}.
 1265 @item &or
 1266 @c @kindex &or @r{(Edebug)}
 1267 Each of the following elements in the specification list is an
 1268 alternative.  One of the alternatives must match, or the @code{&or}
 1269 specification fails.
 1271 Each list element following @code{&or} is a single alternative.  To
 1272 group two or more list elements as a single alternative, enclose them in
 1273 @code{[@dots{}]}.
 1275 @item &not
 1276 @c @kindex &not @r{(Edebug)}
 1277 Each of the following elements is matched as alternatives as if by using
 1278 @code{&or}, but if any of them match, the specification fails.  If none
 1279 of them match, nothing is matched, but the @code{&not} specification
 1280 succeeds.
 1282 @c FIXME &key?
 1284 @item &define
 1285 @c @kindex &define @r{(Edebug)}
 1286 Indicates that the specification is for a defining form.  The defining
 1287 form itself is not instrumented (that is, Edebug does not stop before and
 1288 after the defining form), but forms inside it typically will be
 1289 instrumented.  The @code{&define} keyword should be the first element in
 1290 a list specification.
 1292 @item nil
 1293 This is successful when there are no more arguments to match at the
 1294 current argument list level; otherwise it fails.  See sublist
 1295 specifications and the backquote example.
 1297 @item gate
 1298 @cindex preventing backtracking
 1299 No argument is matched but backtracking through the gate is disabled
 1300 while matching the remainder of the specifications at this level.  This
 1301 is primarily used to generate more specific syntax error messages.  See
 1302 @ref{Backtracking}, for more details.  Also see the @code{let} example.
 1304 @item @var{other-symbol}
 1305 @cindex indirect specifications
 1306 Any other symbol in a specification list may be a predicate or an
 1307 indirect specification.
 1309 If the symbol has an Edebug specification, this @dfn{indirect
 1310 specification} should be either a list specification that is used in
 1311 place of the symbol, or a function that is called to process the
 1312 arguments.  The specification may be defined with @code{def-edebug-spec}
 1313 just as for macros.  See the @code{defun} example.
 1315 Otherwise, the symbol should be a predicate.  The predicate is called
 1316 with the argument, and if the predicate returns @code{nil}, the
 1317 specification fails and the argument is not instrumented.
 1319 Some suitable predicates include @code{symbolp}, @code{integerp},
 1320 @code{stringp}, @code{vectorp}, and @code{atom}.
 1322 @item [@var{elements}@dots{}]
 1323 @cindex [@dots{}] (Edebug)
 1324 A vector of elements groups the elements into a single @dfn{group
 1325 specification}.  Its meaning has nothing to do with vectors.
 1327 @item "@var{string}"
 1328 The argument should be a symbol named @var{string}.  This specification
 1329 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
 1330 of @var{symbol} is the @var{string}, but the string form is preferred.
 1332 @item (vector @var{elements}@dots{})
 1333 The argument should be a vector whose elements must match the
 1334 @var{elements} in the specification.  See the backquote example.
 1336 @item (@var{elements}@dots{})
 1337 Any other list is a @dfn{sublist specification} and the argument must be
 1338 a list whose elements match the specification @var{elements}.
 1340 @cindex dotted lists (Edebug)
 1341 A sublist specification may be a dotted list and the corresponding list
 1342 argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
 1343 dotted list specification may be another sublist specification (via a
 1344 grouping or an indirect specification, e.g., @code{(spec .  [(more
 1345 specs@dots{})])}) whose elements match the non-dotted list arguments.
 1346 This is useful in recursive specifications such as in the backquote
 1347 example.  Also see the description of a @code{nil} specification
 1348 above for terminating such recursion.
 1350 Note that a sublist specification written as @code{(specs .  nil)}
 1351 is equivalent to @code{(specs)}, and @code{(specs .
 1352 (sublist-elements@dots{}))} is equivalent to @code{(specs
 1353 sublist-elements@dots{})}.
 1354 @end table
 1356 @c Need to document extensions with &symbol and :symbol
 1358 Here is a list of additional specifications that may appear only after
 1359 @code{&define}.  See the @code{defun} example.
 1361 @table @code
 1362 @item name
 1363 The argument, a symbol, is the name of the defining form.
 1365 A defining form is not required to have a name field; and it may have
 1366 multiple name fields.
 1368 @item :name
 1369 This construct does not actually match an argument.  The element
 1370 following @code{:name} should be a symbol; it is used as an additional
 1371 name component for the definition.  You can use this to add a unique,
 1372 static component to the name of the definition.  It may be used more
 1373 than once.
 1375 @item arg
 1376 The argument, a symbol, is the name of an argument of the defining form.
 1377 However, lambda-list keywords (symbols starting with @samp{&})
 1378 are not allowed.
 1380 @item lambda-list
 1381 @cindex lambda-list (Edebug)
 1382 This matches a lambda list---the argument list of a lambda expression.
 1384 @item def-body
 1385 The argument is the body of code in a definition.  This is like
 1386 @code{body}, described above, but a definition body must be instrumented
 1387 with a different Edebug call that looks up information associated with
 1388 the definition.  Use @code{def-body} for the highest level list of forms
 1389 within the definition.
 1391 @item def-form
 1392 The argument is a single, highest-level form in a definition.  This is
 1393 like @code{def-body}, except it is used to match a single form rather than
 1394 a list of forms.  As a special case, @code{def-form} also means that
 1395 tracing information is not output when the form is executed.  See the
 1396 @code{interactive} example.
 1397 @end table
 1399 @node Backtracking
 1400 @subsubsection Backtracking in Specifications
 1402 @cindex backtracking
 1403 @cindex syntax error (Edebug)
 1404 If a specification fails to match at some point, this does not
 1405 necessarily mean a syntax error will be signaled; instead,
 1406 @dfn{backtracking} will take place until all alternatives have been
 1407 exhausted.  Eventually every element of the argument list must be
 1408 matched by some element in the specification, and every required element
 1409 in the specification must match some argument.
 1411 When a syntax error is detected, it might not be reported until much
 1412 later, after higher-level alternatives have been exhausted, and with the
 1413 point positioned further from the real error.  But if backtracking is
 1414 disabled when an error occurs, it can be reported immediately.  Note
 1415 that backtracking is also reenabled automatically in several situations;
 1416 when a new alternative is established by @code{&optional},
 1417 @code{&rest}, or @code{&or}, or at the start of processing a sublist,
 1418 group, or indirect specification.  The effect of enabling or disabling
 1419 backtracking is limited to the remainder of the level currently being
 1420 processed and lower levels.
 1422 Backtracking is disabled while matching any of the
 1423 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
 1424 @code{def-body}).  These specifications will match any form so any error
 1425 must be in the form itself rather than at a higher level.
 1427 Backtracking is also disabled after successfully matching a quoted
 1428 symbol or string specification, since this usually indicates a
 1429 recognized construct.  But if you have a set of alternative constructs that
 1430 all begin with the same symbol, you can usually work around this
 1431 constraint by factoring the symbol out of the alternatives, e.g.,
 1432 @code{["foo" &or [first case] [second case] ...]}.
 1434 Most needs are satisfied by these two ways that backtracking is
 1435 automatically disabled, but occasionally it is useful to explicitly
 1436 disable backtracking by using the @code{gate} specification.  This is
 1437 useful when you know that no higher alternatives could apply.  See the
 1438 example of the @code{let} specification.
 1440 @node Specification Examples
 1441 @subsubsection Specification Examples
 1443 It may be easier to understand Edebug specifications by studying
 1444 the examples provided here.
 1446 A @code{let} special form has a sequence of bindings and a body.  Each
 1447 of the bindings is either a symbol or a sublist with a symbol and
 1448 optional expression.  In the specification below, notice the @code{gate}
 1449 inside of the sublist to prevent backtracking once a sublist is found.
 1451 @ignore
 1452 @c FIXME?  The actual definition in edebug.el looks like this (and always
 1453 @c has AFAICS).  In fact, nothing in edebug.el uses gate.  So maybe
 1454 @c this is just an example for illustration?
 1455 (def-edebug-spec let
 1456   ((&rest
 1457     &or (symbolp &optional form) symbolp)
 1458    body))
 1459 @end ignore
 1460 @example
 1461 (def-edebug-spec let
 1462   ((&rest
 1463     &or symbolp (gate symbolp &optional form))
 1464    body))
 1465 @end example
 1467 Edebug uses the following specifications for @code{defun} and the
 1468 associated argument list and @code{interactive} specifications.  It is
 1469 necessary to handle interactive forms specially since an expression
 1470 argument is actually evaluated outside of the function body.  (The
 1471 specification for @code{defmacro} is very similar to that for
 1472 @code{defun}, but allows for the @code{declare} statement.)
 1474 @smallexample
 1475 (def-edebug-spec defun
 1476   (&define name lambda-list
 1477            [&optional stringp]   ; @r{Match the doc string, if present.}
 1478            [&optional ("interactive" interactive)]
 1479            def-body))
 1481 (def-edebug-spec lambda-list
 1482   (([&rest arg]
 1483     [&optional ["&optional" arg &rest arg]]
 1484     &optional ["&rest" arg]
 1485     )))
 1487 (def-edebug-spec interactive
 1488   (&optional &or stringp def-form))    ; @r{Notice: @code{def-form}}
 1489 @end smallexample
 1491 The specification for backquote below illustrates how to match
 1492 dotted lists and use @code{nil} to terminate recursion.  It also
 1493 illustrates how components of a vector may be matched.  (The actual
 1494 specification defined by Edebug is a little different, and does not
 1495 support dotted lists because doing so causes very deep recursion that
 1496 could fail.)
 1498 @smallexample
 1499 (def-edebug-spec \` (backquote-form))   ; @r{Alias just for clarity.}
 1501 (def-edebug-spec backquote-form
 1502   (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
 1503        (backquote-form . [&or nil backquote-form])
 1504        (vector &rest backquote-form)
 1505        sexp))
 1506 @end smallexample
 1509 @node Edebug Options
 1510 @subsection Edebug Options
 1512   These options affect the behavior of Edebug:
 1513 @c Previously defopt'd:
 1514 @c edebug-sit-for-seconds, edebug-print-length, edebug-print-level
 1515 @c edebug-print-circle, edebug-eval-macro-args
 1517 @defopt edebug-setup-hook
 1518 Functions to call before Edebug is used.  Each time it is set to a new
 1519 value, Edebug will call those functions once and then
 1520 reset @code{edebug-setup-hook} to @code{nil}.  You could use this to
 1521 load up Edebug specifications associated with a package you are using,
 1522 but only when you also use Edebug.
 1523 @xref{Instrumenting}.
 1524 @end defopt
 1526 @defopt edebug-all-defs
 1527 If this is non-@code{nil}, normal evaluation of defining forms such as
 1528 @code{defun} and @code{defmacro} instruments them for Edebug.  This
 1529 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
 1530 and @code{eval-current-buffer}.
 1532 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
 1533 option.  @xref{Instrumenting}.
 1534 @end defopt
 1536 @defopt edebug-all-forms
 1537 If this is non-@code{nil}, the commands @code{eval-defun},
 1538 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
 1539 instrument all forms, even those that don't define anything.
 1540 This doesn't apply to loading or evaluations in the minibuffer.
 1542 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
 1543 option.  @xref{Instrumenting}.
 1544 @end defopt
 1546 @defopt edebug-save-windows
 1547 If this is non-@code{nil}, Edebug saves and restores the window
 1548 configuration.  That takes some time, so if your program does not care
 1549 what happens to the window configurations, it is better to set this
 1550 variable to @code{nil}.
 1552 If the value is a list, only the listed windows are saved and
 1553 restored.
 1555 You can use the @kbd{W} command in Edebug to change this variable
 1556 interactively.  @xref{Edebug Display Update}.
 1557 @end defopt
 1559 @defopt edebug-save-displayed-buffer-points
 1560 If this is non-@code{nil}, Edebug saves and restores point in all
 1561 displayed buffers.
 1563 Saving and restoring point in other buffers is necessary if you are
 1564 debugging code that changes the point of a buffer that is displayed in
 1565 a non-selected window.  If Edebug or the user then selects the window,
 1566 point in that buffer will move to the window's value of point.
 1568 Saving and restoring point in all buffers is expensive, since it
 1569 requires selecting each window twice, so enable this only if you need
 1570 it.  @xref{Edebug Display Update}.
 1571 @end defopt
 1573 @defopt edebug-initial-mode
 1574 If this variable is non-@code{nil}, it specifies the initial execution
 1575 mode for Edebug when it is first activated.  Possible values are
 1576 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
 1577 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
 1579 The default value is @code{step}.  This variable can be set
 1580 interactively with @kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}).
 1581 @xref{Edebug Execution Modes}.
 1582 @end defopt
 1584 @defopt edebug-trace
 1585 If this is non-@code{nil}, trace each function entry and exit.
 1586 Tracing output is displayed in a buffer named @file{*edebug-trace*}, one
 1587 function entry or exit per line, indented by the recursion level.
 1589 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
 1590 @end defopt
 1592 @defopt edebug-test-coverage
 1593 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
 1594 @xref{Coverage Testing}.
 1595 @end defopt
 1597 @defopt edebug-continue-kbd-macro
 1598 If non-@code{nil}, continue defining or executing any keyboard macro
 1599 that is executing outside of Edebug.   Use this with caution since it is not
 1600 debugged.
 1601 @xref{Edebug Execution Modes}.
 1602 @end defopt
 1604 @defopt edebug-unwrap-results
 1605 If non-@code{nil}, Edebug tries to remove any of its own
 1606 instrumentation when showing the results of expressions.  This is
 1607 relevant when debugging macros where the results of expressions are
 1608 themselves instrumented expressions.  As a very artificial example,
 1609 suppose that the example function @code{fac} has been instrumented,
 1610 and consider a macro of the form:
 1612 @c FIXME find a less silly example.
 1613 @smallexample
 1614 (defmacro test () "Edebug example."
 1615   (if (symbol-function 'fac)
 1616       @dots{}))
 1617 @end smallexample
 1619 If you instrument the @code{test} macro and step through it, then by
 1620 default the result of the @code{symbol-function} call has numerous
 1621 @code{edebug-after} and @code{edebug-before} forms, which can make it
 1622 difficult to see the actual result.  If
 1623 @code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
 1624 these forms from the result.
 1625 @end defopt
 1627 @defopt edebug-on-error
 1628 Edebug binds @code{debug-on-error} to this value, if
 1629 @code{debug-on-error} was previously @code{nil}.  @xref{Trapping
 1630 Errors}.
 1631 @end defopt
 1633 @defopt edebug-on-quit
 1634 Edebug binds @code{debug-on-quit} to this value, if
 1635 @code{debug-on-quit} was previously @code{nil}.  @xref{Trapping
 1636 Errors}.
 1637 @end defopt
 1639   If you change the values of @code{edebug-on-error} or
 1640 @code{edebug-on-quit} while Edebug is active, their values won't be used
 1641 until the @emph{next} time Edebug is invoked via a new command.
 1642 @c Not necessarily a deeper command level.
 1643 @c A new command is not precisely true, but that is close enough -- dan
 1645 @defopt edebug-global-break-condition
 1646 If non-@code{nil}, an expression to test for at every stop point.  If
 1647 the result is non-@code{nil}, then break.  Errors are ignored.
 1648 @xref{Global Break Condition}.
 1649 @end defopt