"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/lispref/edebug.texi" (23 Apr 2018, 67324 Bytes) of package /linux/misc/emacs-26.1.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 latest Fossies "Diffs" side-by-side code changes report for "edebug.texi": 25.3_vs_26.1.

    1 @comment -*-texinfo-*-
    2 @c This is part of the GNU Emacs Lisp Reference Manual.
    3 @c Copyright (C) 1992-1994, 1998-1999, 2001-2018 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 @r{(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 @cindex edebug, failure to instrument
  213   If Edebug detects a syntax error while instrumenting, it leaves point
  214 at the erroneous code and signals an @code{invalid-read-syntax} error.
  215 @c FIXME?  I can't see that it "leaves point at the erroneous code".
  216 Example:
  218 @example
  219 @error{} Invalid read syntax: "Expected lambda expression"
  220 @end example
  222   One potential reason for such a failure to instrument is that some
  223 macro definitions are not yet known to Emacs.  To work around this,
  224 load the file which defines the function you are about to instrument.
  226 @findex eval-expression @r{(Edebug)}
  227   To remove instrumentation from a definition, simply re-evaluate its
  228 definition in a way that does not instrument.  There are two ways of
  229 evaluating forms that never instrument them: from a file with
  230 @code{load}, and from the minibuffer with @code{eval-expression}
  231 (@kbd{M-:}).
  233   @xref{Edebug Eval}, for other evaluation functions available
  234 inside of Edebug.
  236 @node Edebug Execution Modes
  237 @subsection Edebug Execution Modes
  239 @cindex Edebug execution modes
  240 Edebug supports several execution modes for running the program you are
  241 debugging.  We call these alternatives @dfn{Edebug execution modes}; do
  242 not confuse them with major or minor modes.  The current Edebug execution mode
  243 determines how far Edebug continues execution before stopping---whether
  244 it stops at each stop point, or continues to the next breakpoint, for
  245 example---and how much Edebug displays the progress of the evaluation
  246 before it stops.
  248 Normally, you specify the Edebug execution mode by typing a command to
  249 continue the program in a certain mode.  Here is a table of these
  250 commands; all except for @kbd{S} resume execution of the program, at
  251 least for a certain distance.
  253 @table @kbd
  254 @item S
  255 Stop: don't execute any more of the program, but wait for more
  256 Edebug commands (@code{edebug-stop}).
  257 @c FIXME Does not work. https://debbugs.gnu.org/9764
  259 @item @key{SPC}
  260 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
  262 @item n
  263 Next: stop at the next stop point encountered after an expression
  264 (@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
  265 @ref{Jumping}.
  267 @item t
  268 Trace: pause (normally one second) at each Edebug stop point
  269 (@code{edebug-trace-mode}).
  271 @item T
  272 Rapid trace: update the display at each stop point, but don't actually
  273 pause (@code{edebug-Trace-fast-mode}).
  275 @item g
  276 Go: run until the next breakpoint (@code{edebug-go-mode}).  @xref{Breakpoints}.
  278 @item c
  279 Continue: pause one second at each breakpoint, and then continue
  280 (@code{edebug-continue-mode}).
  282 @item C
  283 Rapid continue: move point to each breakpoint, but don't pause
  284 (@code{edebug-Continue-fast-mode}).
  286 @item G
  287 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}).  You
  288 can still stop the program by typing @kbd{S}, or any editing command.
  289 @end table
  291 In general, the execution modes earlier in the above list run the
  292 program more slowly or stop sooner than the modes later in the list.
  294 When you enter a new Edebug level, Edebug will normally stop at the
  295 first instrumented function it encounters.  If you prefer to stop only
  296 at a break point, or not at all (for example, when gathering coverage
  297 data), change the value of @code{edebug-initial-mode} from its default
  298 @code{step} to @code{go}, or @code{Go-nonstop}, or one of its other
  299 values (@pxref{Edebug Options}).  You can do this readily with
  300 @kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}):
  302 @deffn Command edebug-set-initial-mode
  303 @kindex C-x C-a C-m
  304 This command, bound to @kbd{C-x C-a C-m}, sets
  305 @code{edebug-initial-mode}.  It prompts you for a key to indicate the
  306 mode.  You should enter one of the eight keys listed above, which sets
  307 the corresponding mode.
  308 @end deffn
  310 Note that you may reenter the same Edebug level several times if, for
  311 example, an instrumented function is called several times from one
  312 command.
  314 While executing or tracing, you can interrupt the execution by typing
  315 any Edebug command.  Edebug stops the program at the next stop point and
  316 then executes the command you typed.  For example, typing @kbd{t} during
  317 execution switches to trace mode at the next stop point.  You can use
  318 @kbd{S} to stop execution without doing anything else.
  320 If your function happens to read input, a character you type intending
  321 to interrupt execution may be read by the function instead.  You can
  322 avoid such unintended results by paying attention to when your program
  323 wants input.
  325 @cindex keyboard macros (Edebug)
  326 Keyboard macros containing the commands in this section do not
  327 completely work: exiting from Edebug, to resume the program, loses track
  328 of the keyboard macro.  This is not easy to fix.  Also, defining or
  329 executing a keyboard macro outside of Edebug does not affect commands
  330 inside Edebug.  This is usually an advantage.  See also the
  331 @code{edebug-continue-kbd-macro} option in @ref{Edebug Options}.
  333 @defopt edebug-sit-for-seconds
  334 This option specifies how many seconds to wait between execution steps
  335 in trace mode or continue mode.  The default is 1 second.
  336 @end defopt
  338 @node Jumping
  339 @subsection Jumping
  341   The commands described in this section execute until they reach a
  342 specified location.  All except @kbd{i} make a temporary breakpoint to
  343 establish the place to stop, then switch to go mode.  Any other
  344 breakpoint reached before the intended stop point will also stop
  345 execution.  @xref{Breakpoints}, for the details on breakpoints.
  347   These commands may fail to work as expected in case of nonlocal exit,
  348 as that can bypass the temporary breakpoint where you expected the
  349 program to stop.
  351 @table @kbd
  352 @item h
  353 Proceed to the stop point near where point is (@code{edebug-goto-here}).
  355 @item f
  356 Run the program for one expression
  357 (@code{edebug-forward-sexp}).
  359 @item o
  360 Run the program until the end of the containing sexp (@code{edebug-step-out}).
  362 @item i
  363 Step into the function or macro called by the form after point
  364 (@code{edebug-step-in}).
  365 @end table
  367 The @kbd{h} command proceeds to the stop point at or after the current
  368 location of point, using a temporary breakpoint.
  370 The @kbd{f} command runs the program forward over one expression.  More
  371 precisely, it sets a temporary breakpoint at the position that
  372 @code{forward-sexp} would reach, then executes in go mode so that
  373 the program will stop at breakpoints.
  375 With a prefix argument @var{n}, the temporary breakpoint is placed
  376 @var{n} sexps beyond point.  If the containing list ends before @var{n}
  377 more elements, then the place to stop is after the containing
  378 expression.
  380 You must check that the position @code{forward-sexp} finds is a place
  381 that the program will really get to.  In @code{cond}, for example,
  382 this may not be true.
  384 For flexibility, the @kbd{f} command does @code{forward-sexp} starting
  385 at point, rather than at the stop point.  If you want to execute one
  386 expression @emph{from the current stop point}, first type @kbd{w}
  387 (@code{edebug-where}) to move point there, and then type @kbd{f}.
  389 The @kbd{o} command continues out of an expression.  It places a
  390 temporary breakpoint at the end of the sexp containing point.  If the
  391 containing sexp is a function definition itself, @kbd{o} continues until
  392 just before the last sexp in the definition.  If that is where you are
  393 now, it returns from the function and then stops.  In other words, this
  394 command does not exit the currently executing function unless you are
  395 positioned after the last sexp.
  397 Normally, the @kbd{h}, @kbd{f}, and @kbd{o} commands display ``Break''
  398 and pause for @code{edebug-sit-for-seconds} before showing the result
  399 of the form just evaluated.  You can avoid this pause by setting
  400 @code{edebug-sit-on-break} to @code{nil}.  @xref{Edebug Options}.
  402 The @kbd{i} command steps into the function or macro called by the list
  403 form after point, and stops at its first stop point.  Note that the form
  404 need not be the one about to be evaluated.  But if the form is a
  405 function call about to be evaluated, remember to use this command before
  406 any of the arguments are evaluated, since otherwise it will be too late.
  408 The @kbd{i} command instruments the function or macro it's supposed to
  409 step into, if it isn't instrumented already.  This is convenient, but keep
  410 in mind that the function or macro remains instrumented unless you explicitly
  411 arrange to deinstrument it.
  413 @node Edebug Misc
  414 @subsection Miscellaneous Edebug Commands
  416   Some miscellaneous Edebug commands are described here.
  418 @table @kbd
  419 @item ?
  420 Display the help message for Edebug (@code{edebug-help}).
  422 @item C-]
  423 Abort one level back to the previous command level
  424 (@code{abort-recursive-edit}).
  426 @item q
  427 Return to the top level editor command loop (@code{top-level}).  This
  428 exits all recursive editing levels, including all levels of Edebug
  429 activity.  However, instrumented code protected with
  430 @code{unwind-protect} or @code{condition-case} forms may resume
  431 debugging.
  433 @item Q
  434 Like @kbd{q}, but don't stop even for protected code
  435 (@code{edebug-top-level-nonstop}).
  437 @item r
  438 Redisplay the most recently known expression result in the echo area
  439 (@code{edebug-previous-result}).
  441 @item d
  442 Display a backtrace, excluding Edebug's own functions for clarity
  443 (@code{edebug-backtrace}).
  445 You cannot use debugger commands in the backtrace buffer in Edebug as
  446 you would in the standard debugger.
  448 The backtrace buffer is killed automatically when you continue
  449 execution.
  450 @end table
  452 You can invoke commands from Edebug that activate Edebug again
  453 recursively.  Whenever Edebug is active, you can quit to the top level
  454 with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
  455 display a backtrace of all the pending evaluations with @kbd{d}.
  457 @node Breaks
  458 @subsection Breaks
  460 Edebug's step mode stops execution when the next stop point is reached.
  461 There are three other ways to stop Edebug execution once it has started:
  462 breakpoints, the global break condition, and source breakpoints.
  464 @menu
  465 * Breakpoints::                 Breakpoints at stop points.
  466 * Global Break Condition::      Breaking on an event.
  467 * Source Breakpoints::          Embedding breakpoints in source code.
  468 @end menu
  470 @node Breakpoints
  471 @subsubsection Edebug Breakpoints
  473 @cindex breakpoints (Edebug)
  474 While using Edebug, you can specify @dfn{breakpoints} in the program you
  475 are testing: these are places where execution should stop.  You can set a
  476 breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
  477 setting and unsetting breakpoints, the stop point that is affected is
  478 the first one at or after point in the source code buffer.  Here are the
  479 Edebug commands for breakpoints:
  481 @table @kbd
  482 @item b
  483 Set a breakpoint at the stop point at or after point
  484 (@code{edebug-set-breakpoint}).  If you use a prefix argument, the
  485 breakpoint is temporary---it turns off the first time it stops the
  486 program.
  488 @item u
  489 Unset the breakpoint (if any) at the stop point at or after
  490 point (@code{edebug-unset-breakpoint}).
  492 @item x @var{condition} @key{RET}
  493 Set a conditional breakpoint which stops the program only if
  494 evaluating @var{condition} produces a non-@code{nil} value
  495 (@code{edebug-set-conditional-breakpoint}).  With a prefix argument,
  496 the breakpoint is temporary.
  498 @item B
  499 Move point to the next breakpoint in the current definition
  500 (@code{edebug-next-breakpoint}).
  501 @end table
  503 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
  504 with @kbd{u}.  First move point to the Edebug stop point of your choice,
  505 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
  506 Unsetting a breakpoint where none has been set has no effect.
  508 Re-evaluating or reinstrumenting a definition removes all of its
  509 previous breakpoints.
  511 A @dfn{conditional breakpoint} tests a condition each time the program
  512 gets there.  Any errors that occur as a result of evaluating the
  513 condition are ignored, as if the result were @code{nil}.  To set a
  514 conditional breakpoint, use @kbd{x}, and specify the condition
  515 expression in the minibuffer.  Setting a conditional breakpoint at a
  516 stop point that has a previously established conditional breakpoint puts
  517 the previous condition expression in the minibuffer so you can edit it.
  519 You can make a conditional or unconditional breakpoint
  520 @dfn{temporary} by using a prefix argument with the command to set the
  521 breakpoint.  When a temporary breakpoint stops the program, it is
  522 automatically unset.
  524 Edebug always stops or pauses at a breakpoint, except when the Edebug
  525 mode is Go-nonstop.  In that mode, it ignores breakpoints entirely.
  527 To find out where your breakpoints are, use the @kbd{B} command, which
  528 moves point to the next breakpoint following point, within the same
  529 function, or to the first breakpoint if there are no following
  530 breakpoints.  This command does not continue execution---it just moves
  531 point in the buffer.
  533 @node Global Break Condition
  534 @subsubsection Global Break Condition
  536 @cindex stopping on events
  537 @cindex global break condition
  538   A @dfn{global break condition} stops execution when a specified
  539 condition is satisfied, no matter where that may occur.  Edebug
  540 evaluates the global break condition at every stop point; if it
  541 evaluates to a non-@code{nil} value, then execution stops or pauses
  542 depending on the execution mode, as if a breakpoint had been hit.  If
  543 evaluating the condition gets an error, execution does not stop.
  545 @findex edebug-set-global-break-condition
  546   The condition expression is stored in
  547 @code{edebug-global-break-condition}.  You can specify a new expression
  548 using the @kbd{X} command from the source code buffer while Edebug is
  549 active, or using @kbd{C-x X X} from any buffer at any time, as long as
  550 Edebug is loaded (@code{edebug-set-global-break-condition}).
  552   The global break condition is the simplest way to find where in your
  553 code some event occurs, but it makes code run much more slowly.  So you
  554 should reset the condition to @code{nil} when not using it.
  556 @node Source Breakpoints
  557 @subsubsection Source Breakpoints
  559 @findex edebug
  560 @cindex source breakpoints
  561   All breakpoints in a definition are forgotten each time you
  562 reinstrument it.  If you wish to make a breakpoint that won't be
  563 forgotten, you can write a @dfn{source breakpoint}, which is simply a
  564 call to the function @code{edebug} in your source code.  You can, of
  565 course, make such a call conditional.  For example, in the @code{fac}
  566 function, you can insert the first line as shown below, to stop when the
  567 argument reaches zero:
  569 @example
  570 (defun fac (n)
  571   (if (= n 0) (edebug))
  572   (if (< 0 n)
  573       (* n (fac (1- n)))
  574     1))
  575 @end example
  577   When the @code{fac} definition is instrumented and the function is
  578 called, the call to @code{edebug} acts as a breakpoint.  Depending on
  579 the execution mode, Edebug stops or pauses there.
  581   If no instrumented code is being executed when @code{edebug} is called,
  582 that function calls @code{debug}.
  583 @c This may not be a good idea anymore.
  585 @node Trapping Errors
  586 @subsection Trapping Errors
  588   Emacs normally displays an error message when an error is signaled and
  589 not handled with @code{condition-case}.  While Edebug is active and
  590 executing instrumented code, it normally responds to all unhandled
  591 errors.  You can customize this with the options @code{edebug-on-error}
  592 and @code{edebug-on-quit}; see @ref{Edebug Options}.
  594   When Edebug responds to an error, it shows the last stop point
  595 encountered before the error.  This may be the location of a call to a
  596 function which was not instrumented, and within which the error actually
  597 occurred.  For an unbound variable error, the last known stop point
  598 might be quite distant from the offending variable reference.  In that
  599 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
  601 @c Edebug should be changed for the following: -- dan
  602   If you change @code{debug-on-error} or @code{debug-on-quit} while
  603 Edebug is active, these changes will be forgotten when Edebug becomes
  604 inactive.  Furthermore, during Edebug's recursive edit, these variables
  605 are bound to the values they had outside of Edebug.
  607 @node Edebug Views
  608 @subsection Edebug Views
  610   These Edebug commands let you view aspects of the buffer and window
  611 status as they were before entry to Edebug.  The outside window
  612 configuration is the collection of windows and contents that were in
  613 effect outside of Edebug.
  615 @table @kbd
  616 @item v
  617 Switch to viewing the outside window configuration
  618 (@code{edebug-view-outside}).  Type @kbd{C-x X w} to return to Edebug.
  620 @item p
  621 Temporarily display the outside current buffer with point at its
  622 outside position (@code{edebug-bounce-point}), pausing for one second
  623 before returning to Edebug.  With a prefix argument @var{n}, pause for
  624 @var{n} seconds instead.
  626 @item w
  627 Move point back to the current stop point in the source code buffer
  628 (@code{edebug-where}).
  630 If you use this command in a different window displaying the same
  631 buffer, that window will be used instead to display the current
  632 definition in the future.
  634 @item W
  635 @c Its function is not simply to forget the saved configuration -- dan
  636 Toggle whether Edebug saves and restores the outside window
  637 configuration (@code{edebug-toggle-save-windows}).
  639 With a prefix argument, @code{W} only toggles saving and restoring of
  640 the selected window.  To specify a window that is not displaying the
  641 source code buffer, you must use @kbd{C-x X W} from the global keymap.
  642 @end table
  644   You can view the outside window configuration with @kbd{v} or just
  645 bounce to the point in the current buffer with @kbd{p}, even if
  646 it is not normally displayed.
  648   After moving point, you may wish to jump back to the stop point.
  649 You can do that with @kbd{w} from a source code buffer.  You can jump
  650 back to the stop point in the source code buffer from any buffer using
  651 @kbd{C-x X w}.
  653   Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
  654 saved outside window configuration---so that even if you turn saving
  655 back @emph{on}, the current window configuration remains unchanged when
  656 you next exit Edebug (by continuing the program).  However, the
  657 automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may
  658 conflict with the buffers you wish to see unless you have enough windows
  659 open.
  661 @node Edebug Eval
  662 @subsection Evaluation
  664   While within Edebug, you can evaluate expressions as if Edebug
  665 were not running.  Edebug tries to be invisible to the expression's
  666 evaluation and printing.  Evaluation of expressions that cause side
  667 effects will work as expected, except for changes to data that Edebug
  668 explicitly saves and restores.  @xref{The Outside Context}, for details
  669 on this process.
  671 @table @kbd
  672 @item e @var{exp} @key{RET}
  673 Evaluate expression @var{exp} in the context outside of Edebug
  674 (@code{edebug-eval-expression}).  That is, Edebug tries to minimize its
  675 interference with the evaluation.
  677 @item M-: @var{exp} @key{RET}
  678 Evaluate expression @var{exp} in the context of Edebug itself
  679 (@code{eval-expression}).
  681 @item C-x C-e
  682 Evaluate the expression before point, in the context outside of Edebug
  683 (@code{edebug-eval-last-sexp}).
  684 @end table
  686 @cindex lexical binding (Edebug)
  687   Edebug supports evaluation of expressions containing references to
  688 lexically bound symbols created by the following constructs in
  689 @file{cl.el}: @code{lexical-let}, @code{macrolet}, and
  690 @code{symbol-macrolet}.
  691 @c FIXME?  What about lexical-binding = t?
  693 @node Eval List
  694 @subsection Evaluation List Buffer
  696   You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to
  697 evaluate expressions interactively.  You can also set up the
  698 @dfn{evaluation list} of expressions to be evaluated automatically each
  699 time Edebug updates the display.
  701 @table @kbd
  702 @item E
  703 Switch to the evaluation list buffer @file{*edebug*}
  704 (@code{edebug-visit-eval-list}).
  705 @end table
  707   In the @file{*edebug*} buffer you can use the commands of Lisp
  708 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
  709 Manual}) as well as these special commands:
  711 @table @kbd
  712 @item C-j
  713 Evaluate the expression before point, in the outside context, and insert
  714 the value in the buffer (@code{edebug-eval-print-last-sexp}).
  716 @item C-x C-e
  717 Evaluate the expression before point, in the context outside of Edebug
  718 (@code{edebug-eval-last-sexp}).
  720 @item C-c C-u
  721 Build a new evaluation list from the contents of the buffer
  722 (@code{edebug-update-eval-list}).
  724 @item C-c C-d
  725 Delete the evaluation list group that point is in
  726 (@code{edebug-delete-eval-item}).
  728 @item C-c C-w
  729 Switch back to the source code buffer at the current stop point
  730 (@code{edebug-where}).
  731 @end table
  733   You can evaluate expressions in the evaluation list window with
  734 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*};
  735 but they are evaluated in the context outside of Edebug.
  737   The expressions you enter interactively (and their results) are lost
  738 when you continue execution; but you can set up an @dfn{evaluation list}
  739 consisting of expressions to be evaluated each time execution stops.
  741 @cindex evaluation list group
  742   To do this, write one or more @dfn{evaluation list groups} in the
  743 evaluation list buffer.  An evaluation list group consists of one or
  744 more Lisp expressions.  Groups are separated by comment lines.
  746   The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
  747 evaluation list, scanning the buffer and using the first expression of
  748 each group.  (The idea is that the second expression of the group is the
  749 value previously computed and displayed.)
  751   Each entry to Edebug redisplays the evaluation list by inserting each
  752 expression in the buffer, followed by its current value.  It also
  753 inserts comment lines so that each expression becomes its own group.
  754 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
  755 the evaluation list is effectively unchanged.
  757   If an error occurs during an evaluation from the evaluation list,
  758 the error message is displayed in a string as if it were the result.
  759 Therefore, expressions using variables that are not currently valid do
  760 not interrupt your debugging.
  762   Here is an example of what the evaluation list window looks like after
  763 several expressions have been added to it:
  765 @smallexample
  766 (current-buffer)
  767 #<buffer *scratch*>
  768 ;---------------------------------------------------------------
  769 (selected-window)
  770 #<window 16 on *scratch*>
  771 ;---------------------------------------------------------------
  772 (point)
  773 196
  774 ;---------------------------------------------------------------
  775 bad-var
  776 "Symbol's value as variable is void: bad-var"
  777 ;---------------------------------------------------------------
  778 (recursion-depth)
  779 0
  780 ;---------------------------------------------------------------
  781 this-command
  782 eval-last-sexp
  783 ;---------------------------------------------------------------
  784 @end smallexample
  786 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
  787 delete the text for the group and update the evaluation list with
  788 @kbd{C-c C-u}.  To add a new expression to the evaluation list, insert
  789 the expression at a suitable place, insert a new comment line, then type
  790 @kbd{C-c C-u}.  You need not insert dashes in the comment line---its
  791 contents don't matter.
  793 After selecting @file{*edebug*}, you can return to the source code
  794 buffer with @kbd{C-c C-w}.  The @file{*edebug*} buffer is killed when
  795 you continue execution, and recreated next time it is needed.
  797 @node Printing in Edebug
  798 @subsection Printing in Edebug
  800 @cindex printing (Edebug)
  801 @cindex printing circular structures
  802 @pindex cust-print
  803   If an expression in your program produces a value containing circular
  804 list structure, you may get an error when Edebug attempts to print it.
  806   One way to cope with circular structure is to set @code{print-length}
  807 or @code{print-level} to truncate the printing.  Edebug does this for
  808 you; it binds @code{print-length} and @code{print-level} to the values
  809 of the variables @code{edebug-print-length} and
  810 @code{edebug-print-level} (so long as they have non-@code{nil}
  811 values).  @xref{Output Variables}.
  813 @defopt edebug-print-length
  814 If non-@code{nil}, Edebug binds @code{print-length} to this value while
  815 printing results.  The default value is @code{50}.
  816 @end defopt
  818 @defopt edebug-print-level
  819 If non-@code{nil}, Edebug binds @code{print-level} to this value while
  820 printing results.  The default value is @code{50}.
  821 @end defopt
  823   You can also print circular structures and structures that share
  824 elements more informatively by binding @code{print-circle}
  825 to a non-@code{nil} value.
  827   Here is an example of code that creates a circular structure:
  829 @example
  830 (setq a '(x y))
  831 (setcar a a)
  832 @end example
  834 @noindent
  835 Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
  836 @samp{#1=} notation labels the structure that follows it with the label
  837 @samp{1}, and the @samp{#1#} notation references the previously labeled
  838 structure.  This notation is used for any shared elements of lists or
  839 vectors.
  841 @defopt edebug-print-circle
  842 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
  843 printing results.  The default value is @code{t}.
  844 @end defopt
  846   Other programs can also use custom printing; see @file{cust-print.el}
  847 for details.
  849 @node Trace Buffer
  850 @subsection Trace Buffer
  851 @cindex trace buffer
  853   Edebug can record an execution trace, storing it in a buffer named
  854 @file{*edebug-trace*}.  This is a log of function calls and returns,
  855 showing the function names and their arguments and values.  To enable
  856 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
  858   Making a trace buffer is not the same thing as using trace execution
  859 mode (@pxref{Edebug Execution Modes}).
  861   When trace recording is enabled, each function entry and exit adds
  862 lines to the trace buffer.  A function entry record consists of
  863 @samp{::::@{}, followed by the function name and argument values.  A
  864 function exit record consists of @samp{::::@}}, followed by the function
  865 name and result of the function.
  867   The number of @samp{:}s in an entry shows its recursion depth.  You
  868 can use the braces in the trace buffer to find the matching beginning or
  869 end of function calls.
  871 @findex edebug-print-trace-before
  872 @findex edebug-print-trace-after
  873   You can customize trace recording for function entry and exit by
  874 redefining the functions @code{edebug-print-trace-before} and
  875 @code{edebug-print-trace-after}.
  877 @defmac edebug-tracing string body@dots{}
  878 This macro requests additional trace information around the execution
  879 of the @var{body} forms.  The argument @var{string} specifies text
  880 to put in the trace buffer, after the @samp{@{} or @samp{@}}.  All
  881 the arguments are evaluated, and @code{edebug-tracing} returns the
  882 value of the last form in @var{body}.
  883 @end defmac
  885 @defun edebug-trace format-string &rest format-args
  886 This function inserts text in the trace buffer.  It computes the text
  887 with @code{(apply 'format @var{format-string} @var{format-args})}.
  888 It also appends a newline to separate entries.
  889 @end defun
  891   @code{edebug-tracing} and @code{edebug-trace} insert lines in the
  892 trace buffer whenever they are called, even if Edebug is not active.
  893 Adding text to the trace buffer also scrolls its window to show the last
  894 lines inserted.
  896 @node Coverage Testing
  897 @subsection Coverage Testing
  899 @cindex coverage testing (Edebug)
  900 @cindex frequency counts
  901 @cindex performance analysis (Edebug)
  902   Edebug provides rudimentary coverage testing and display of execution
  903 frequency.
  905   Coverage testing works by comparing the result of each expression with
  906 the previous result; each form in the program is considered covered
  907 if it has returned two different values since you began testing coverage
  908 in the current Emacs session.  Thus, to do coverage testing on your
  909 program, execute it under various conditions and note whether it behaves
  910 correctly; Edebug will tell you when you have tried enough different
  911 conditions that each form has returned two different values.
  913   Coverage testing makes execution slower, so it is only done if
  914 @code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
  915 performed for all executions of an instrumented function, even if the
  916 execution mode is Go-nonstop, and regardless of whether coverage testing
  917 is enabled.
  919 @kindex C-x X =
  920 @findex edebug-temp-display-freq-count
  921   Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
  922 the coverage information and the frequency counts for a definition.
  923 Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
  924 information temporarily, only until you type another key.
  926 @deffn Command edebug-display-freq-count
  927 This command displays the frequency count data for each line of the
  928 current definition.
  930 It inserts frequency counts as comment lines after each line of code.
  931 You can undo all insertions with one @code{undo} command.  The counts
  932 appear under the @samp{(} before an expression or the @samp{)} after
  933 an expression, or on the last character of a variable.  To simplify
  934 the display, a count is not shown if it is equal to the count of an
  935 earlier expression on the same line.
  937 The character @samp{=} following the count for an expression says that
  938 the expression has returned the same value each time it was evaluated.
  939 In other words, it is not yet covered for coverage testing purposes.
  941 To clear the frequency count and coverage data for a definition,
  942 simply reinstrument it with @code{eval-defun}.
  943 @end deffn
  945 For example, after evaluating @code{(fac 5)} with a source
  946 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
  947 the breakpoint is reached, the frequency data looks like this:
  949 @example
  950 (defun fac (n)
  951   (if (= n 0) (edebug))
  952 ;#6           1      = =5
  953   (if (< 0 n)
  954 ;#5         =
  955       (* n (fac (1- n)))
  956 ;#    5               0
  957     1))
  958 ;#   0
  959 @end example
  961 The comment lines show that @code{fac} was called 6 times.  The
  962 first @code{if} statement returned 5 times with the same result each
  963 time; the same is true of the condition on the second @code{if}.
  964 The recursive call of @code{fac} did not return at all.
  967 @node The Outside Context
  968 @subsection The Outside Context
  970 Edebug tries to be transparent to the program you are debugging, but it
  971 does not succeed completely.  Edebug also tries to be transparent when
  972 you evaluate expressions with @kbd{e} or with the evaluation list
  973 buffer, by temporarily restoring the outside context.  This section
  974 explains precisely what context Edebug restores, and how Edebug fails to
  975 be completely transparent.
  977 @menu
  978 * Checking Whether to Stop::    When Edebug decides what to do.
  979 * Edebug Display Update::       When Edebug updates the display.
  980 * Edebug Recursive Edit::       When Edebug stops execution.
  981 @end menu
  983 @node Checking Whether to Stop
  984 @subsubsection Checking Whether to Stop
  986 Whenever Edebug is entered, it needs to save and restore certain data
  987 before even deciding whether to make trace information or stop the
  988 program.
  990 @itemize @bullet
  991 @item
  992 @vindex edebug-max-depth
  993 @code{max-lisp-eval-depth} (@pxref{Eval}) and @code{max-specpdl-size}
  994 (@pxref{Local Variables}) are both increased to reduce Edebug's impact
  995 on the stack.  You could, however, still run out of stack space when
  996 using Edebug.  You can also enlarge the value of
  997 @code{edebug-max-depth} if Edebug reaches the limit of recursion depth
  998 instrumenting code that contains very large quoted lists.
 1000 @item
 1001 The state of keyboard macro execution is saved and restored.  While
 1002 Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
 1003 unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
 1004 @end itemize
 1007 @node Edebug Display Update
 1008 @subsubsection Edebug Display Update
 1010 @c This paragraph is not filled, because LaLiberte's conversion script
 1011 @c needs an xref to be on just one line.
 1012 When Edebug needs to display something (e.g., in trace mode), it saves
 1013 the current window configuration from outside Edebug
 1014 (@pxref{Window Configurations}).  When you exit Edebug, it restores
 1015 the previous window configuration.
 1017 Emacs redisplays only when it pauses.  Usually, when you continue
 1018 execution, the program re-enters Edebug at a breakpoint or after
 1019 stepping, without pausing or reading input in between.  In such cases,
 1020 Emacs never gets a chance to redisplay the outside configuration.
 1021 Consequently, what you see is the same window configuration as the last
 1022 time Edebug was active, with no interruption.
 1024 Entry to Edebug for displaying something also saves and restores the
 1025 following data (though some of them are deliberately not restored if an
 1026 error or quit signal occurs).
 1028 @itemize @bullet
 1029 @item
 1030 @cindex current buffer point and mark (Edebug)
 1031 Which buffer is current, and the positions of point and the mark in the
 1032 current buffer, are saved and restored.
 1034 @item
 1035 @cindex window configuration (Edebug)
 1036 The outside window configuration is saved and restored if
 1037 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
 1039 The window configuration is not restored on error or quit, but the
 1040 outside selected window @emph{is} reselected even on error or quit in
 1041 case a @code{save-excursion} is active.  If the value of
 1042 @code{edebug-save-windows} is a list, only the listed windows are saved
 1043 and restored.
 1045 The window start and horizontal scrolling of the source code buffer are
 1046 not restored, however, so that the display remains coherent within Edebug.
 1048 @item
 1049 The value of point in each displayed buffer is saved and restored if
 1050 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
 1052 @item
 1053 The variables @code{overlay-arrow-position} and
 1054 @code{overlay-arrow-string} are saved and restored, so you can safely
 1055 invoke Edebug from the recursive edit elsewhere in the same buffer.
 1057 @item
 1058 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
 1059 the cursor shows up in the window.
 1060 @end itemize
 1062 @node Edebug Recursive Edit
 1063 @subsubsection Edebug Recursive Edit
 1065 When Edebug is entered and actually reads commands from the user, it
 1066 saves (and later restores) these additional data:
 1068 @itemize @bullet
 1069 @item
 1070 The current match data.  @xref{Match Data}.
 1072 @item
 1073 The variables @code{last-command}, @code{this-command},
 1074 @code{last-command-event}, @code{last-input-event},
 1075 @code{last-event-frame}, @code{last-nonmenu-event}, and
 1076 @code{track-mouse}.  Commands in Edebug do not affect these variables
 1077 outside of Edebug.
 1079 Executing commands within Edebug can change the key sequence that
 1080 would be returned by @code{this-command-keys}, and there is no way to
 1081 reset the key sequence from Lisp.
 1083 Edebug cannot save and restore the value of
 1084 @code{unread-command-events}.  Entering Edebug while this variable has a
 1085 nontrivial value can interfere with execution of the program you are
 1086 debugging.
 1088 @item
 1089 Complex commands executed while in Edebug are added to the variable
 1090 @code{command-history}.  In rare cases this can alter execution.
 1092 @item
 1093 Within Edebug, the recursion depth appears one deeper than the recursion
 1094 depth outside Edebug.  This is not true of the automatically updated
 1095 evaluation list window.
 1097 @item
 1098 @code{standard-output} and @code{standard-input} are bound to @code{nil}
 1099 by the @code{recursive-edit}, but Edebug temporarily restores them during
 1100 evaluations.
 1102 @item
 1103 The state of keyboard macro definition is saved and restored.  While
 1104 Edebug is active, @code{defining-kbd-macro} is bound to
 1105 @code{edebug-continue-kbd-macro}.
 1106 @end itemize
 1108 @node Edebug and Macros
 1109 @subsection Edebug and Macros
 1111 To make Edebug properly instrument expressions that call macros, some
 1112 extra care is needed.  This subsection explains the details.
 1114 @menu
 1115 * Instrumenting Macro Calls::   The basic problem.
 1116 * Specification List::          How to specify complex patterns of evaluation.
 1117 * Backtracking::                What Edebug does when matching fails.
 1118 * Specification Examples::      To help understand specifications.
 1119 @end menu
 1121 @node Instrumenting Macro Calls
 1122 @subsubsection Instrumenting Macro Calls
 1124   When Edebug instruments an expression that calls a Lisp macro, it needs
 1125 additional information about the macro to do the job properly.  This is
 1126 because there is no a-priori way to tell which subexpressions of the
 1127 macro call are forms to be evaluated.  (Evaluation may occur explicitly
 1128 in the macro body, or when the resulting expansion is evaluated, or any
 1129 time later.)
 1131   Therefore, you must define an Edebug specification for each macro
 1132 that Edebug will encounter, to explain the format of calls to that
 1133 macro.  To do this, add a @code{debug} declaration to the macro
 1134 definition.  Here is a simple example that shows the specification for
 1135 the @code{for} example macro (@pxref{Argument Evaluation}).
 1137 @smallexample
 1138 (defmacro for (var from init to final do &rest body)
 1139   "Execute a simple \"for\" loop.
 1140 For example, (for i from 1 to 10 do (print i))."
 1141   (declare (debug (symbolp "from" form "to" form "do" &rest form)))
 1142   ...)
 1143 @end smallexample
 1145   The Edebug specification says which parts of a call to the macro are
 1146 forms to be evaluated.  For simple macros, the specification
 1147 often looks very similar to the formal argument list of the macro
 1148 definition, but specifications are much more general than macro
 1149 arguments.  @xref{Defining Macros}, for more explanation of
 1150 the @code{declare} form.
 1152 @c See, e.g., https://debbugs.gnu.org/10577
 1153 @c FIXME  Maybe there should be an Edebug option to get it to
 1154 @c automatically load the entire source file containing the function
 1155 @c being instrumented.  That would avoid this.
 1156   Take care to ensure that the specifications are known to Edebug when
 1157 you instrument code.  If you are instrumenting a function which uses a
 1158 macro defined in another file, you may first need to either evaluate
 1159 the @code{require} forms in the file containing your function, or
 1160 explicitly load the file containing the macro.  If the definition of a
 1161 macro is wrapped by @code{eval-when-compile}, you may need to evaluate
 1162 it.
 1164   You can also define an edebug specification for a macro separately
 1165 from the macro definition with @code{def-edebug-spec}.  Adding
 1166 @code{debug} declarations is preferred, and more convenient, for macro
 1167 definitions in Lisp, but @code{def-edebug-spec} makes it possible to
 1168 define Edebug specifications for special forms implemented in C.
 1170 @defmac def-edebug-spec macro specification
 1171 Specify which expressions of a call to macro @var{macro} are forms to be
 1172 evaluated.  @var{specification} should be the edebug specification.
 1173 Neither argument is evaluated.
 1175 The @var{macro} argument can actually be any symbol, not just a macro
 1176 name.
 1177 @end defmac
 1179 Here is a table of the possibilities for @var{specification} and how each
 1180 directs processing of arguments.
 1182 @table @asis
 1183 @item @code{t}
 1184 All arguments are instrumented for evaluation.
 1186 @item @code{0}
 1187 None of the arguments is instrumented.
 1189 @item a symbol
 1190 The symbol must have an Edebug specification, which is used instead.
 1191 This indirection is repeated until another kind of specification is
 1192 found.  This allows you to inherit the specification from another macro.
 1194 @item a list
 1195 The elements of the list describe the types of the arguments of a
 1196 calling form.  The possible elements of a specification list are
 1197 described in the following sections.
 1198 @end table
 1200 If a macro has no Edebug specification, neither through a @code{debug}
 1201 declaration nor through a @code{def-edebug-spec} call, the variable
 1202 @code{edebug-eval-macro-args} comes into play.
 1204 @defopt edebug-eval-macro-args
 1205 This controls the way Edebug treats macro arguments with no explicit
 1206 Edebug specification.  If it is @code{nil} (the default), none of the
 1207 arguments is instrumented for evaluation.  Otherwise, all arguments
 1208 are instrumented.
 1209 @end defopt
 1211 @node Specification List
 1212 @subsubsection Specification List
 1214 @cindex Edebug specification list
 1215 A @dfn{specification list} is required for an Edebug specification if
 1216 some arguments of a macro call are evaluated while others are not.  Some
 1217 elements in a specification list match one or more arguments, but others
 1218 modify the processing of all following elements.  The latter, called
 1219 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
 1220 as @code{&optional}).
 1222 A specification list may contain sublists, which match arguments that are
 1223 themselves lists, or it may contain vectors used for grouping.  Sublists
 1224 and groups thus subdivide the specification list into a hierarchy of
 1225 levels.  Specification keywords apply only to the remainder of the
 1226 sublist or group they are contained in.
 1228 When a specification list involves alternatives or repetition, matching
 1229 it against an actual macro call may require backtracking.  For more
 1230 details, @pxref{Backtracking}.
 1232 Edebug specifications provide the power of regular expression matching,
 1233 plus some context-free grammar constructs: the matching of sublists with
 1234 balanced parentheses, recursive processing of forms, and recursion via
 1235 indirect specifications.
 1237 Here's a table of the possible elements of a specification list, with
 1238 their meanings (see @ref{Specification Examples}, for the referenced
 1239 examples):
 1241 @table @code
 1242 @item sexp
 1243 A single unevaluated Lisp object, which is not instrumented.
 1244 @c an "expression" is not necessarily intended for evaluation.
 1246 @item form
 1247 A single evaluated expression, which is instrumented.  If your macro
 1248 wraps the expression with @code{lambda} before it is evaluated, use
 1249 @code{def-form} instead.  See @code{def-form} below.
 1251 @item place
 1252 A generalized variable.  @xref{Generalized Variables}.
 1254 @item body
 1255 Short for @code{&rest form}.  See @code{&rest} below.  If your macro
 1256 wraps its body of code with @code{lambda} before it is evaluated, use
 1257 @code{def-body} instead.  See @code{def-body} below.
 1259 @item function-form
 1260 A function form: either a quoted function symbol, a quoted lambda
 1261 expression, or a form (that should evaluate to a function symbol or
 1262 lambda expression).  This is useful when an argument that's a lambda
 1263 expression might be quoted with @code{quote} rather than
 1264 @code{function}, since it instruments the body of the lambda expression
 1265 either way.
 1267 @item lambda-expr
 1268 A lambda expression with no quoting.
 1270 @item &optional
 1271 @c @kindex &optional @r{(Edebug)}
 1272 All following elements in the specification list are optional; as soon
 1273 as one does not match, Edebug stops matching at this level.
 1275 To make just a few elements optional, followed by non-optional elements,
 1276 use @code{[&optional @var{specs}@dots{}]}.  To specify that several
 1277 elements must all match or none, use @code{&optional
 1278 [@var{specs}@dots{}]}.  See the @code{defun} example.
 1280 @item &rest
 1281 @c @kindex &rest @r{(Edebug)}
 1282 All following elements in the specification list are repeated zero or
 1283 more times.  In the last repetition, however, it is not a problem if the
 1284 expression runs out before matching all of the elements of the
 1285 specification list.
 1287 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
 1288 To specify several elements that must all match on every repetition, use
 1289 @code{&rest [@var{specs}@dots{}]}.
 1291 @item &or
 1292 @c @kindex &or @r{(Edebug)}
 1293 Each of the following elements in the specification list is an
 1294 alternative.  One of the alternatives must match, or the @code{&or}
 1295 specification fails.
 1297 Each list element following @code{&or} is a single alternative.  To
 1298 group two or more list elements as a single alternative, enclose them in
 1299 @code{[@dots{}]}.
 1301 @item &not
 1302 @c @kindex &not @r{(Edebug)}
 1303 Each of the following elements is matched as alternatives as if by using
 1304 @code{&or}, but if any of them match, the specification fails.  If none
 1305 of them match, nothing is matched, but the @code{&not} specification
 1306 succeeds.
 1308 @c FIXME &key?
 1310 @item &define
 1311 @c @kindex &define @r{(Edebug)}
 1313 Indicates that the specification is for a defining form.  Edebug's
 1314 definition of a defining form is a form containing one or more code
 1315 forms which are saved and executed later, after the execution of the
 1316 defining form.
 1318 The defining form itself is not instrumented (that is, Edebug does not
 1319 stop before and after the defining form), but forms inside it
 1320 typically will be instrumented.  The @code{&define} keyword should be
 1321 the first element in a list specification.
 1323 @item nil
 1324 This is successful when there are no more arguments to match at the
 1325 current argument list level; otherwise it fails.  See sublist
 1326 specifications and the backquote example.
 1328 @item gate
 1329 @cindex preventing backtracking
 1330 No argument is matched but backtracking through the gate is disabled
 1331 while matching the remainder of the specifications at this level.  This
 1332 is primarily used to generate more specific syntax error messages.  See
 1333 @ref{Backtracking}, for more details.  Also see the @code{let} example.
 1335 @item @var{other-symbol}
 1336 @cindex indirect specifications
 1337 Any other symbol in a specification list may be a predicate or an
 1338 indirect specification.
 1340 If the symbol has an Edebug specification, this @dfn{indirect
 1341 specification} should be either a list specification that is used in
 1342 place of the symbol, or a function that is called to process the
 1343 arguments.  The specification may be defined with @code{def-edebug-spec}
 1344 just as for macros.  See the @code{defun} example.
 1346 Otherwise, the symbol should be a predicate.  The predicate is called
 1347 with the argument, and if the predicate returns @code{nil}, the
 1348 specification fails and the argument is not instrumented.
 1350 Some suitable predicates include @code{symbolp}, @code{integerp},
 1351 @code{stringp}, @code{vectorp}, and @code{atom}.
 1353 @item [@var{elements}@dots{}]
 1354 @cindex [@dots{}] (Edebug)
 1355 A vector of elements groups the elements into a single @dfn{group
 1356 specification}.  Its meaning has nothing to do with vectors.
 1358 @item "@var{string}"
 1359 The argument should be a symbol named @var{string}.  This specification
 1360 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
 1361 of @var{symbol} is the @var{string}, but the string form is preferred.
 1363 @item (vector @var{elements}@dots{})
 1364 The argument should be a vector whose elements must match the
 1365 @var{elements} in the specification.  See the backquote example.
 1367 @item (@var{elements}@dots{})
 1368 Any other list is a @dfn{sublist specification} and the argument must be
 1369 a list whose elements match the specification @var{elements}.
 1371 @cindex dotted lists (Edebug)
 1372 A sublist specification may be a dotted list and the corresponding list
 1373 argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
 1374 dotted list specification may be another sublist specification (via a
 1375 grouping or an indirect specification, e.g., @code{(spec .  [(more
 1376 specs@dots{})])}) whose elements match the non-dotted list arguments.
 1377 This is useful in recursive specifications such as in the backquote
 1378 example.  Also see the description of a @code{nil} specification
 1379 above for terminating such recursion.
 1381 Note that a sublist specification written as @code{(specs .  nil)}
 1382 is equivalent to @code{(specs)}, and @code{(specs .
 1383 (sublist-elements@dots{}))} is equivalent to @code{(specs
 1384 sublist-elements@dots{})}.
 1385 @end table
 1387 @c Need to document extensions with &symbol and :symbol
 1389 Here is a list of additional specifications that may appear only after
 1390 @code{&define}.  See the @code{defun} example.
 1392 @table @code
 1393 @item name
 1394 The argument, a symbol, is the name of the defining form.
 1396 A defining form is not required to have a name field; and it may have
 1397 multiple name fields.
 1399 @item :name
 1400 This construct does not actually match an argument.  The element
 1401 following @code{:name} should be a symbol; it is used as an additional
 1402 name component for the definition.  You can use this to add a unique,
 1403 static component to the name of the definition.  It may be used more
 1404 than once.
 1406 @item arg
 1407 The argument, a symbol, is the name of an argument of the defining form.
 1408 However, lambda-list keywords (symbols starting with @samp{&})
 1409 are not allowed.
 1411 @item lambda-list
 1412 @cindex lambda-list (Edebug)
 1413 This matches a lambda list---the argument list of a lambda expression.
 1415 @item def-body
 1416 The argument is the body of code in a definition.  This is like
 1417 @code{body}, described above, but a definition body must be instrumented
 1418 with a different Edebug call that looks up information associated with
 1419 the definition.  Use @code{def-body} for the highest level list of forms
 1420 within the definition.
 1422 @item def-form
 1423 The argument is a single, highest-level form in a definition.  This is
 1424 like @code{def-body}, except it is used to match a single form rather than
 1425 a list of forms.  As a special case, @code{def-form} also means that
 1426 tracing information is not output when the form is executed.  See the
 1427 @code{interactive} example.
 1428 @end table
 1430 @node Backtracking
 1431 @subsubsection Backtracking in Specifications
 1433 @cindex backtracking
 1434 @cindex syntax error (Edebug)
 1435 If a specification fails to match at some point, this does not
 1436 necessarily mean a syntax error will be signaled; instead,
 1437 @dfn{backtracking} will take place until all alternatives have been
 1438 exhausted.  Eventually every element of the argument list must be
 1439 matched by some element in the specification, and every required element
 1440 in the specification must match some argument.
 1442 When a syntax error is detected, it might not be reported until much
 1443 later, after higher-level alternatives have been exhausted, and with the
 1444 point positioned further from the real error.  But if backtracking is
 1445 disabled when an error occurs, it can be reported immediately.  Note
 1446 that backtracking is also reenabled automatically in several situations;
 1447 when a new alternative is established by @code{&optional},
 1448 @code{&rest}, or @code{&or}, or at the start of processing a sublist,
 1449 group, or indirect specification.  The effect of enabling or disabling
 1450 backtracking is limited to the remainder of the level currently being
 1451 processed and lower levels.
 1453 Backtracking is disabled while matching any of the
 1454 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
 1455 @code{def-body}).  These specifications will match any form so any error
 1456 must be in the form itself rather than at a higher level.
 1458 Backtracking is also disabled after successfully matching a quoted
 1459 symbol or string specification, since this usually indicates a
 1460 recognized construct.  But if you have a set of alternative constructs that
 1461 all begin with the same symbol, you can usually work around this
 1462 constraint by factoring the symbol out of the alternatives, e.g.,
 1463 @code{["foo" &or [first case] [second case] ...]}.
 1465 Most needs are satisfied by these two ways that backtracking is
 1466 automatically disabled, but occasionally it is useful to explicitly
 1467 disable backtracking by using the @code{gate} specification.  This is
 1468 useful when you know that no higher alternatives could apply.  See the
 1469 example of the @code{let} specification.
 1471 @node Specification Examples
 1472 @subsubsection Specification Examples
 1474 It may be easier to understand Edebug specifications by studying
 1475 the examples provided here.
 1477 A @code{let} special form has a sequence of bindings and a body.  Each
 1478 of the bindings is either a symbol or a sublist with a symbol and
 1479 optional expression.  In the specification below, notice the @code{gate}
 1480 inside of the sublist to prevent backtracking once a sublist is found.
 1482 @ignore
 1483 @c FIXME?  The actual definition in edebug.el looks like this (and always
 1484 @c has AFAICS).  In fact, nothing in edebug.el uses gate.  So maybe
 1485 @c this is just an example for illustration?
 1486 (def-edebug-spec let
 1487   ((&rest
 1488     &or (symbolp &optional form) symbolp)
 1489    body))
 1490 @end ignore
 1491 @example
 1492 (def-edebug-spec let
 1493   ((&rest
 1494     &or symbolp (gate symbolp &optional form))
 1495    body))
 1496 @end example
 1498 Edebug uses the following specifications for @code{defun} and the
 1499 associated argument list and @code{interactive} specifications.  It is
 1500 necessary to handle interactive forms specially since an expression
 1501 argument is actually evaluated outside of the function body.  (The
 1502 specification for @code{defmacro} is very similar to that for
 1503 @code{defun}, but allows for the @code{declare} statement.)
 1505 @smallexample
 1506 (def-edebug-spec defun
 1507   (&define name lambda-list
 1508            [&optional stringp]   ; @r{Match the doc string, if present.}
 1509            [&optional ("interactive" interactive)]
 1510            def-body))
 1512 (def-edebug-spec lambda-list
 1513   (([&rest arg]
 1514     [&optional ["&optional" arg &rest arg]]
 1515     &optional ["&rest" arg]
 1516     )))
 1518 (def-edebug-spec interactive
 1519   (&optional &or stringp def-form))    ; @r{Notice: @code{def-form}}
 1520 @end smallexample
 1522 The specification for backquote below illustrates how to match
 1523 dotted lists and use @code{nil} to terminate recursion.  It also
 1524 illustrates how components of a vector may be matched.  (The actual
 1525 specification defined by Edebug is a little different, and does not
 1526 support dotted lists because doing so causes very deep recursion that
 1527 could fail.)
 1529 @smallexample
 1530 (def-edebug-spec \` (backquote-form))   ; @r{Alias just for clarity.}
 1532 (def-edebug-spec backquote-form
 1533   (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
 1534        (backquote-form . [&or nil backquote-form])
 1535        (vector &rest backquote-form)
 1536        sexp))
 1537 @end smallexample
 1540 @node Edebug Options
 1541 @subsection Edebug Options
 1543   These options affect the behavior of Edebug:
 1544 @c Previously defopt'd:
 1545 @c edebug-sit-for-seconds, edebug-print-length, edebug-print-level
 1546 @c edebug-print-circle, edebug-eval-macro-args
 1548 @defopt edebug-setup-hook
 1549 Functions to call before Edebug is used.  Each time it is set to a new
 1550 value, Edebug will call those functions once and then
 1551 reset @code{edebug-setup-hook} to @code{nil}.  You could use this to
 1552 load up Edebug specifications associated with a package you are using,
 1553 but only when you also use Edebug.
 1554 @xref{Instrumenting}.
 1555 @end defopt
 1557 @defopt edebug-all-defs
 1558 If this is non-@code{nil}, normal evaluation of defining forms such as
 1559 @code{defun} and @code{defmacro} instruments them for Edebug.  This
 1560 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
 1561 and @code{eval-current-buffer}.
 1563 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
 1564 option.  @xref{Instrumenting}.
 1565 @end defopt
 1567 @defopt edebug-all-forms
 1568 If this is non-@code{nil}, the commands @code{eval-defun},
 1569 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
 1570 instrument all forms, even those that don't define anything.
 1571 This doesn't apply to loading or evaluations in the minibuffer.
 1573 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
 1574 option.  @xref{Instrumenting}.
 1575 @end defopt
 1577 @defopt edebug-eval-macro-args
 1578 When this is non-@code{nil}, all macro arguments will be instrumented
 1579 in the generated code.  For any macro, an @code{edebug-form-spec}
 1580 overrides this option.  So to specify exceptions for macros that have
 1581 some arguments evaluated and some not, use @code{def-edebug-spec} to
 1582 specify an @code{edebug-form-spec}.
 1583 @end defopt
 1585 @defopt edebug-save-windows
 1586 If this is non-@code{nil}, Edebug saves and restores the window
 1587 configuration.  That takes some time, so if your program does not care
 1588 what happens to the window configurations, it is better to set this
 1589 variable to @code{nil}.
 1591 If the value is a list, only the listed windows are saved and
 1592 restored.
 1594 You can use the @kbd{W} command in Edebug to change this variable
 1595 interactively.  @xref{Edebug Display Update}.
 1596 @end defopt
 1598 @defopt edebug-save-displayed-buffer-points
 1599 If this is non-@code{nil}, Edebug saves and restores point in all
 1600 displayed buffers.
 1602 Saving and restoring point in other buffers is necessary if you are
 1603 debugging code that changes the point of a buffer that is displayed in
 1604 a non-selected window.  If Edebug or the user then selects the window,
 1605 point in that buffer will move to the window's value of point.
 1607 Saving and restoring point in all buffers is expensive, since it
 1608 requires selecting each window twice, so enable this only if you need
 1609 it.  @xref{Edebug Display Update}.
 1610 @end defopt
 1612 @defopt edebug-initial-mode
 1613 If this variable is non-@code{nil}, it specifies the initial execution
 1614 mode for Edebug when it is first activated.  Possible values are
 1615 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
 1616 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
 1618 The default value is @code{step}.  This variable can be set
 1619 interactively with @kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}).
 1620 @xref{Edebug Execution Modes}.
 1621 @end defopt
 1623 @defopt edebug-trace
 1624 If this is non-@code{nil}, trace each function entry and exit.
 1625 Tracing output is displayed in a buffer named @file{*edebug-trace*}, one
 1626 function entry or exit per line, indented by the recursion level.
 1628 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
 1629 @end defopt
 1631 @defopt edebug-test-coverage
 1632 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
 1633 @xref{Coverage Testing}.
 1634 @end defopt
 1636 @defopt edebug-continue-kbd-macro
 1637 If non-@code{nil}, continue defining or executing any keyboard macro
 1638 that is executing outside of Edebug.   Use this with caution since it is not
 1639 debugged.
 1640 @xref{Edebug Execution Modes}.
 1641 @end defopt
 1643 @defopt edebug-print-length
 1644 If non-@code{nil}, the default value of @code{print-length} for
 1645 printing results in Edebug.  @xref{Output Variables}.
 1646 @end defopt
 1648 @defopt edebug-print-level
 1649 If non-@code{nil}, the default value of @code{print-level} for
 1650 printing results in Edebug.  @xref{Output Variables}.
 1651 @end defopt
 1653 @defopt edebug-print-circle
 1654 If non-@code{nil}, the default value of @code{print-circle} for
 1655 printing results in Edebug.  @xref{Output Variables}.
 1656 @end defopt
 1658 @defopt edebug-unwrap-results
 1659 If non-@code{nil}, Edebug tries to remove any of its own
 1660 instrumentation when showing the results of expressions.  This is
 1661 relevant when debugging macros where the results of expressions are
 1662 themselves instrumented expressions.  As a very artificial example,
 1663 suppose that the example function @code{fac} has been instrumented,
 1664 and consider a macro of the form:
 1666 @c FIXME find a less silly example.
 1667 @smallexample
 1668 (defmacro test () "Edebug example."
 1669   (if (symbol-function 'fac)
 1670       @dots{}))
 1671 @end smallexample
 1673 If you instrument the @code{test} macro and step through it, then by
 1674 default the result of the @code{symbol-function} call has numerous
 1675 @code{edebug-after} and @code{edebug-before} forms, which can make it
 1676 difficult to see the actual result.  If
 1677 @code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
 1678 these forms from the result.
 1679 @end defopt
 1681 @defopt edebug-on-error
 1682 Edebug binds @code{debug-on-error} to this value, if
 1683 @code{debug-on-error} was previously @code{nil}.  @xref{Trapping
 1684 Errors}.
 1685 @end defopt
 1687 @defopt edebug-on-quit
 1688 Edebug binds @code{debug-on-quit} to this value, if
 1689 @code{debug-on-quit} was previously @code{nil}.  @xref{Trapping
 1690 Errors}.
 1691 @end defopt
 1693   If you change the values of @code{edebug-on-error} or
 1694 @code{edebug-on-quit} while Edebug is active, their values won't be used
 1695 until the @emph{next} time Edebug is invoked via a new command.
 1696 @c Not necessarily a deeper command level.
 1697 @c A new command is not precisely true, but that is close enough -- dan
 1699 @defopt edebug-global-break-condition
 1700 If non-@code{nil}, an expression to test for at every stop point.  If
 1701 the result is non-@code{nil}, then break.  Errors are ignored.
 1702 @xref{Global Break Condition}.
 1703 @end defopt
 1705 @defopt edebug-sit-for-seconds
 1706 Number of seconds to pause when a breakpoint is reached and the execution
 1707 mode is trace or continue.  @xref{Edebug Execution Modes}.
 1708 @end defopt
 1710 @defopt edebug-sit-on-break
 1711 Whether or not to pause for @code{edebug-sit-for-seconds} on reaching
 1712 a breakpoint.  Set to @code{nil} to prevent the pause, non-@code{nil}
 1713 to allow it.
 1714 @end defopt