2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
4 @c 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software 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, Syntax Errors, Debugger, Debugging
15 @cindex Edebug debugging facility
17 Edebug is a source-level debugger for Emacs Lisp programs, with which
22 Step through evaluation, stopping before and after each expression.
25 Set conditional or unconditional breakpoints.
28 Stop when a specified condition is true (the global break event).
31 Trace slow or fast, stopping briefly at each stop point, or
35 Display expression results and evaluate expressions as if outside of
39 Automatically re-evaluate a list of expressions and
40 display their results each time Edebug updates the display.
43 Output trace information on function calls and returns.
46 Stop when an error occurs.
49 Display a backtrace, omitting Edebug's own frames.
52 Specify argument evaluation for macros and defining forms.
55 Obtain rudimentary coverage testing and frequency counts.
58 The first three sections below should tell you enough about Edebug to
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.
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}.
112 =>@point{}(if (< 0 n)
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
127 .(* n. .(fac .(1- n.).).).
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:
139 =>(if @point{}(< 0 n)
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.
153 @subsection Instrumenting for Edebug
155 In order to use Edebug to debug Lisp code, you must first
156 @dfn{instrument} the code. Instrumenting code inserts additional code
157 into it, to invoke Edebug at the proper places.
160 @findex eval-defun (Edebug)
161 When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
162 prefix argument on a function definition, it instruments the
163 definition before evaluating it. (This does not modify the source
164 code itself.) If the variable @code{edebug-all-defs} is
165 non-@code{nil}, that inverts the meaning of the prefix argument: in
166 this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
167 a prefix argument. The default value of @code{edebug-all-defs} is
168 @code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value
169 of the variable @code{edebug-all-defs}.
171 @findex eval-region @r{(Edebug)}
172 @findex eval-buffer @r{(Edebug)}
173 @findex eval-current-buffer @r{(Edebug)}
174 If @code{edebug-all-defs} is non-@code{nil}, then the commands
175 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
176 also instrument any definitions they evaluate. Similarly,
177 @code{edebug-all-forms} controls whether @code{eval-region} should
178 instrument @emph{any} form, even non-defining forms. This doesn't apply
179 to loading or evaluations in the minibuffer. The command @kbd{M-x
180 edebug-all-forms} toggles this option.
182 @findex edebug-eval-top-level-form
183 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
184 instrument any top-level form regardless of the values of
185 @code{edebug-all-defs} and @code{edebug-all-forms}.
187 While Edebug is active, the command @kbd{I}
188 (@code{edebug-instrument-callee}) instruments the definition of the
189 function or macro called by the list form after point, if it is not already
190 instrumented. This is possible only if Edebug knows where to find the
191 source for that function; for this reason, after loading Edebug,
192 @code{eval-region} records the position of every definition it
193 evaluates, even if not instrumenting it. See also the @kbd{i} command
194 (@pxref{Jumping}), which steps into the call after instrumenting the
197 Edebug knows how to instrument all the standard special forms,
198 @code{interactive} forms with an expression argument, anonymous lambda
199 expressions, and other defining forms. However, Edebug cannot determine
200 on its own what a user-defined macro will do with the arguments of a
201 macro call, so you must provide that information using Edebug
202 specifications; for details, @pxref{Edebug and Macros}.
204 When Edebug is about to instrument code for the first time in a
205 session, it runs the hook @code{edebug-setup-hook}, then sets it to
206 @code{nil}. You can use this to load Edebug specifications
207 associated with a package you are using, but only when you use Edebug.
209 @findex eval-expression @r{(Edebug)}
210 To remove instrumentation from a definition, simply re-evaluate its
211 definition in a way that does not instrument. There are two ways of
212 evaluating forms that never instrument them: from a file with
213 @code{load}, and from the minibuffer with @code{eval-expression}
216 If Edebug detects a syntax error while instrumenting, it leaves point
217 at the erroneous code and signals an @code{invalid-read-syntax} error.
219 @xref{Edebug Eval}, for other evaluation functions available
222 @node Edebug Execution Modes
223 @subsection Edebug Execution Modes
225 @cindex Edebug execution modes
226 Edebug supports several execution modes for running the program you are
227 debugging. We call these alternatives @dfn{Edebug execution modes}; do
228 not confuse them with major or minor modes. The current Edebug execution mode
229 determines how far Edebug continues execution before stopping---whether
230 it stops at each stop point, or continues to the next breakpoint, for
231 example---and how much Edebug displays the progress of the evaluation
234 Normally, you specify the Edebug execution mode by typing a command to
235 continue the program in a certain mode. Here is a table of these
236 commands; all except for @kbd{S} resume execution of the program, at
237 least for a certain distance.
241 Stop: don't execute any more of the program, but wait for more
242 Edebug commands (@code{edebug-stop}).
245 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
248 Next: stop at the next stop point encountered after an expression
249 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
253 Trace: pause (normally one second) at each Edebug stop point
254 (@code{edebug-trace-mode}).
257 Rapid trace: update the display at each stop point, but don't actually
258 pause (@code{edebug-Trace-fast-mode}).
261 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
264 Continue: pause one second at each breakpoint, and then continue
265 (@code{edebug-continue-mode}).
268 Rapid continue: move point to each breakpoint, but don't pause
269 (@code{edebug-Continue-fast-mode}).
272 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
273 can still stop the program by typing @kbd{S}, or any editing command.
276 In general, the execution modes earlier in the above list run the
277 program more slowly or stop sooner than the modes later in the list.
279 While executing or tracing, you can interrupt the execution by typing
280 any Edebug command. Edebug stops the program at the next stop point and
281 then executes the command you typed. For example, typing @kbd{t} during
282 execution switches to trace mode at the next stop point. You can use
283 @kbd{S} to stop execution without doing anything else.
285 If your function happens to read input, a character you type intending
286 to interrupt execution may be read by the function instead. You can
287 avoid such unintended results by paying attention to when your program
290 @cindex keyboard macros (Edebug)
291 Keyboard macros containing the commands in this section do not
292 completely work: exiting from Edebug, to resume the program, loses track
293 of the keyboard macro. This is not easy to fix. Also, defining or
294 executing a keyboard macro outside of Edebug does not affect commands
295 inside Edebug. This is usually an advantage. See also the
296 @code{edebug-continue-kbd-macro} option in @ref{Edebug Options}.
298 When you enter a new Edebug level, the initial execution mode comes
299 from the value of the variable @code{edebug-initial-mode}
300 (@pxref{Edebug Options}). By default, this specifies step mode. Note
301 that you may reenter the same Edebug level several times if, for
302 example, an instrumented function is called several times from one
305 @defopt edebug-sit-for-seconds
306 This option specifies how many seconds to wait between execution steps
307 in trace mode or continue mode. The default is 1 second.
313 The commands described in this section execute until they reach a
314 specified location. All except @kbd{i} make a temporary breakpoint to
315 establish the place to stop, then switch to go mode. Any other
316 breakpoint reached before the intended stop point will also stop
317 execution. @xref{Breakpoints}, for the details on breakpoints.
319 These commands may fail to work as expected in case of nonlocal exit,
320 as that can bypass the temporary breakpoint where you expected the
325 Proceed to the stop point near where point is (@code{edebug-goto-here}).
328 Run the program for one expression
329 (@code{edebug-forward-sexp}).
332 Run the program until the end of the containing sexp (@code{edebug-step-out}).
335 Step into the function or macro called by the form after point.
338 The @kbd{h} command proceeds to the stop point at or after the current
339 location of point, using a temporary breakpoint.
341 The @kbd{f} command runs the program forward over one expression. More
342 precisely, it sets a temporary breakpoint at the position that
343 @code{forward-sexp} would reach, then executes in go mode so that
344 the program will stop at breakpoints.
346 With a prefix argument @var{n}, the temporary breakpoint is placed
347 @var{n} sexps beyond point. If the containing list ends before @var{n}
348 more elements, then the place to stop is after the containing
351 You must check that the position @code{forward-sexp} finds is a place
352 that the program will really get to. In @code{cond}, for example,
353 this may not be true.
355 For flexibility, the @kbd{f} command does @code{forward-sexp} starting
356 at point, rather than at the stop point. If you want to execute one
357 expression @emph{from the current stop point}, first type @kbd{w}
358 (@code{edebug-where}) to move point there, and then type @kbd{f}.
360 The @kbd{o} command continues ``out of'' an expression. It places a
361 temporary breakpoint at the end of the sexp containing point. If the
362 containing sexp is a function definition itself, @kbd{o} continues until
363 just before the last sexp in the definition. If that is where you are
364 now, it returns from the function and then stops. In other words, this
365 command does not exit the currently executing function unless you are
366 positioned after the last sexp.
368 The @kbd{i} command steps into the function or macro called by the list
369 form after point, and stops at its first stop point. Note that the form
370 need not be the one about to be evaluated. But if the form is a
371 function call about to be evaluated, remember to use this command before
372 any of the arguments are evaluated, since otherwise it will be too late.
374 The @kbd{i} command instruments the function or macro it's supposed to
375 step into, if it isn't instrumented already. This is convenient, but keep
376 in mind that the function or macro remains instrumented unless you explicitly
377 arrange to deinstrument it.
380 @subsection Miscellaneous Edebug Commands
382 Some miscellaneous Edebug commands are described here.
386 Display the help message for Edebug (@code{edebug-help}).
389 Abort one level back to the previous command level
390 (@code{abort-recursive-edit}).
393 Return to the top level editor command loop (@code{top-level}). This
394 exits all recursive editing levels, including all levels of Edebug
395 activity. However, instrumented code protected with
396 @code{unwind-protect} or @code{condition-case} forms may resume
400 Like @kbd{q}, but don't stop even for protected code
401 (@code{edebug-top-level-nonstop}).
404 Redisplay the most recently known expression result in the echo area
405 (@code{edebug-previous-result}).
408 Display a backtrace, excluding Edebug's own functions for clarity
409 (@code{edebug-backtrace}).
411 You cannot use debugger commands in the backtrace buffer in Edebug as
412 you would in the standard debugger.
414 The backtrace buffer is killed automatically when you continue
418 You can invoke commands from Edebug that activate Edebug again
419 recursively. Whenever Edebug is active, you can quit to the top level
420 with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
421 display a backtrace of all the pending evaluations with @kbd{d}.
426 Edebug's step mode stops execution when the next stop point is reached.
427 There are three other ways to stop Edebug execution once it has started:
428 breakpoints, the global break condition, and source breakpoints.
431 * Breakpoints:: Breakpoints at stop points.
432 * Global Break Condition:: Breaking on an event.
433 * Source Breakpoints:: Embedding breakpoints in source code.
437 @subsubsection Edebug Breakpoints
439 @cindex breakpoints (Edebug)
440 While using Edebug, you can specify @dfn{breakpoints} in the program you
441 are testing: these are places where execution should stop. You can set a
442 breakpoint at any stop point, as defined in @ref{Using Edebug}. For
443 setting and unsetting breakpoints, the stop point that is affected is
444 the first one at or after point in the source code buffer. Here are the
445 Edebug commands for breakpoints:
449 Set a breakpoint at the stop point at or after point
450 (@code{edebug-set-breakpoint}). If you use a prefix argument, the
451 breakpoint is temporary---it turns off the first time it stops the
455 Unset the breakpoint (if any) at the stop point at or after
456 point (@code{edebug-unset-breakpoint}).
458 @item x @var{condition} @key{RET}
459 Set a conditional breakpoint which stops the program only if
460 evaluating @var{condition} produces a non-@code{nil} value
461 (@code{edebug-set-conditional-breakpoint}). With a prefix argument,
462 the breakpoint is temporary.
465 Move point to the next breakpoint in the current definition
466 (@code{edebug-next-breakpoint}).
469 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
470 with @kbd{u}. First move point to the Edebug stop point of your choice,
471 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
472 Unsetting a breakpoint where none has been set has no effect.
474 Re-evaluating or reinstrumenting a definition removes all of its
475 previous breakpoints.
477 A @dfn{conditional breakpoint} tests a condition each time the program
478 gets there. Any errors that occur as a result of evaluating the
479 condition are ignored, as if the result were @code{nil}. To set a
480 conditional breakpoint, use @kbd{x}, and specify the condition
481 expression in the minibuffer. Setting a conditional breakpoint at a
482 stop point that has a previously established conditional breakpoint puts
483 the previous condition expression in the minibuffer so you can edit it.
485 You can make a conditional or unconditional breakpoint
486 @dfn{temporary} by using a prefix argument with the command to set the
487 breakpoint. When a temporary breakpoint stops the program, it is
490 Edebug always stops or pauses at a breakpoint, except when the Edebug
491 mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
493 To find out where your breakpoints are, use the @kbd{B} command, which
494 moves point to the next breakpoint following point, within the same
495 function, or to the first breakpoint if there are no following
496 breakpoints. This command does not continue execution---it just moves
499 @node Global Break Condition
500 @subsubsection Global Break Condition
502 @cindex stopping on events
503 @cindex global break condition
504 A @dfn{global break condition} stops execution when a specified
505 condition is satisfied, no matter where that may occur. Edebug
506 evaluates the global break condition at every stop point; if it
507 evaluates to a non-@code{nil} value, then execution stops or pauses
508 depending on the execution mode, as if a breakpoint had been hit. If
509 evaluating the condition gets an error, execution does not stop.
511 @findex edebug-set-global-break-condition
512 The condition expression is stored in
513 @code{edebug-global-break-condition}. You can specify a new expression
514 using the @kbd{X} command from the source code buffer while Edebug is
515 active, or using @kbd{C-x X X} from any buffer at any time, as long as
516 Edebug is loaded (@code{edebug-set-global-break-condition}).
518 The global break condition is the simplest way to find where in your
519 code some event occurs, but it makes code run much more slowly. So you
520 should reset the condition to @code{nil} when not using it.
522 @node Source Breakpoints
523 @subsubsection Source Breakpoints
526 @cindex source breakpoints
527 All breakpoints in a definition are forgotten each time you
528 reinstrument it. If you wish to make a breakpoint that won't be
529 forgotten, you can write a @dfn{source breakpoint}, which is simply a
530 call to the function @code{edebug} in your source code. You can, of
531 course, make such a call conditional. For example, in the @code{fac}
532 function, you can insert the first line as shown below, to stop when the
533 argument reaches zero:
537 (if (= n 0) (edebug))
543 When the @code{fac} definition is instrumented and the function is
544 called, the call to @code{edebug} acts as a breakpoint. Depending on
545 the execution mode, Edebug stops or pauses there.
547 If no instrumented code is being executed when @code{edebug} is called,
548 that function calls @code{debug}.
549 @c This may not be a good idea anymore.
551 @node Trapping Errors
552 @subsection Trapping Errors
554 Emacs normally displays an error message when an error is signaled and
555 not handled with @code{condition-case}. While Edebug is active and
556 executing instrumented code, it normally responds to all unhandled
557 errors. You can customize this with the options @code{edebug-on-error}
558 and @code{edebug-on-quit}; see @ref{Edebug Options}.
560 When Edebug responds to an error, it shows the last stop point
561 encountered before the error. This may be the location of a call to a
562 function which was not instrumented, and within which the error actually
563 occurred. For an unbound variable error, the last known stop point
564 might be quite distant from the offending variable reference. In that
565 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
567 @c Edebug should be changed for the following: -- dan
568 If you change @code{debug-on-error} or @code{debug-on-quit} while
569 Edebug is active, these changes will be forgotten when Edebug becomes
570 inactive. Furthermore, during Edebug's recursive edit, these variables
571 are bound to the values they had outside of Edebug.
574 @subsection Edebug Views
576 These Edebug commands let you view aspects of the buffer and window
577 status as they were before entry to Edebug. The outside window
578 configuration is the collection of windows and contents that were in
579 effect outside of Edebug.
583 Switch to viewing the outside window configuration
584 (@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
587 Temporarily display the outside current buffer with point at its
588 outside position (@code{edebug-bounce-point}), pausing for one second
589 before returning to Edebug. With a prefix argument @var{n}, pause for
590 @var{n} seconds instead.
593 Move point back to the current stop point in the source code buffer
594 (@code{edebug-where}).
596 If you use this command in a different window displaying the same
597 buffer, that window will be used instead to display the current
598 definition in the future.
601 @c Its function is not simply to forget the saved configuration -- dan
602 Toggle whether Edebug saves and restores the outside window
603 configuration (@code{edebug-toggle-save-windows}).
605 With a prefix argument, @code{W} only toggles saving and restoring of
606 the selected window. To specify a window that is not displaying the
607 source code buffer, you must use @kbd{C-x X W} from the global keymap.
610 You can view the outside window configuration with @kbd{v} or just
611 bounce to the point in the current buffer with @kbd{p}, even if
612 it is not normally displayed.
614 After moving point, you may wish to jump back to the stop point.
615 You can do that with @kbd{w} from a source code buffer. You can jump
616 back to the stop point in the source code buffer from any buffer using
619 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
620 saved outside window configuration---so that even if you turn saving
621 back @emph{on}, the current window configuration remains unchanged when
622 you next exit Edebug (by continuing the program). However, the
623 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
624 conflict with the buffers you wish to see unless you have enough windows
628 @subsection Evaluation
630 While within Edebug, you can evaluate expressions ``as if'' Edebug
631 were not running. Edebug tries to be invisible to the expression's
632 evaluation and printing. Evaluation of expressions that cause side
633 effects will work as expected, except for changes to data that Edebug
634 explicitly saves and restores. @xref{The Outside Context}, for details
638 @item e @var{exp} @key{RET}
639 Evaluate expression @var{exp} in the context outside of Edebug
640 (@code{edebug-eval-expression}). That is, Edebug tries to minimize its
641 interference with the evaluation.
643 @item M-: @var{exp} @key{RET}
644 Evaluate expression @var{exp} in the context of Edebug itself
645 (@code{eval-expression}).
648 Evaluate the expression before point, in the context outside of Edebug
649 (@code{edebug-eval-last-sexp}).
652 @cindex lexical binding (Edebug)
653 Edebug supports evaluation of expressions containing references to
654 lexically bound symbols created by the following constructs in
655 @file{cl.el}: @code{lexical-let}, @code{macrolet}, and
656 @code{symbol-macrolet}.
659 @subsection Evaluation List Buffer
661 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
662 evaluate expressions interactively. You can also set up the
663 @dfn{evaluation list} of expressions to be evaluated automatically each
664 time Edebug updates the display.
668 Switch to the evaluation list buffer @samp{*edebug*}
669 (@code{edebug-visit-eval-list}).
672 In the @samp{*edebug*} buffer you can use the commands of Lisp
673 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
674 Manual}) as well as these special commands:
678 Evaluate the expression before point, in the outside context, and insert
679 the value in the buffer (@code{edebug-eval-print-last-sexp}).
682 Evaluate the expression before point, in the context outside of Edebug
683 (@code{edebug-eval-last-sexp}).
686 Build a new evaluation list from the contents of the buffer
687 (@code{edebug-update-eval-list}).
690 Delete the evaluation list group that point is in
691 (@code{edebug-delete-eval-item}).
694 Switch back to the source code buffer at the current stop point
695 (@code{edebug-where}).
698 You can evaluate expressions in the evaluation list window with
699 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
700 but they are evaluated in the context outside of Edebug.
702 The expressions you enter interactively (and their results) are lost
703 when you continue execution; but you can set up an @dfn{evaluation list}
704 consisting of expressions to be evaluated each time execution stops.
706 @cindex evaluation list group
707 To do this, write one or more @dfn{evaluation list groups} in the
708 evaluation list buffer. An evaluation list group consists of one or
709 more Lisp expressions. Groups are separated by comment lines.
711 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
712 evaluation list, scanning the buffer and using the first expression of
713 each group. (The idea is that the second expression of the group is the
714 value previously computed and displayed.)
716 Each entry to Edebug redisplays the evaluation list by inserting each
717 expression in the buffer, followed by its current value. It also
718 inserts comment lines so that each expression becomes its own group.
719 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
720 the evaluation list is effectively unchanged.
722 If an error occurs during an evaluation from the evaluation list,
723 the error message is displayed in a string as if it were the result.
724 Therefore, expressions using variables that are not currently valid do
725 not interrupt your debugging.
727 Here is an example of what the evaluation list window looks like after
728 several expressions have been added to it:
733 ;---------------------------------------------------------------
735 #<window 16 on *scratch*>
736 ;---------------------------------------------------------------
739 ;---------------------------------------------------------------
741 "Symbol's value as variable is void: bad-var"
742 ;---------------------------------------------------------------
745 ;---------------------------------------------------------------
748 ;---------------------------------------------------------------
751 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
752 delete the text for the group and update the evaluation list with
753 @kbd{C-c C-u}. To add a new expression to the evaluation list, insert
754 the expression at a suitable place, insert a new comment line, then type
755 @kbd{C-c C-u}. You need not insert dashes in the comment line---its
756 contents don't matter.
758 After selecting @samp{*edebug*}, you can return to the source code
759 buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
760 you continue execution, and recreated next time it is needed.
762 @node Printing in Edebug
763 @subsection Printing in Edebug
765 @cindex printing (Edebug)
766 @cindex printing circular structures
768 If an expression in your program produces a value containing circular
769 list structure, you may get an error when Edebug attempts to print it.
771 One way to cope with circular structure is to set @code{print-length}
772 or @code{print-level} to truncate the printing. Edebug does this for
773 you; it binds @code{print-length} and @code{print-level} to the values
774 of the variables @code{edebug-print-length} and
775 @code{edebug-print-level} (so long as they have non-@code{nil}
776 values). @xref{Output Variables}.
778 @defopt edebug-print-length
779 If non-@code{nil}, Edebug binds @code{print-length} to this value while
780 printing results. The default value is @code{50}.
783 @defopt edebug-print-level
784 If non-@code{nil}, Edebug binds @code{print-level} to this value while
785 printing results. The default value is @code{50}.
788 You can also print circular structures and structures that share
789 elements more informatively by binding @code{print-circle}
790 to a non-@code{nil} value.
792 Here is an example of code that creates a circular structure:
800 Custom printing prints this as @samp{Result: #1=(#1# y)}. The
801 @samp{#1=} notation labels the structure that follows it with the label
802 @samp{1}, and the @samp{#1#} notation references the previously labeled
803 structure. This notation is used for any shared elements of lists or
806 @defopt edebug-print-circle
807 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
808 printing results. The default value is @code{t}.
811 Other programs can also use custom printing; see @file{cust-print.el}
815 @subsection Trace Buffer
818 Edebug can record an execution trace, storing it in a buffer named
819 @samp{*edebug-trace*}. This is a log of function calls and returns,
820 showing the function names and their arguments and values. To enable
821 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
823 Making a trace buffer is not the same thing as using trace execution
824 mode (@pxref{Edebug Execution Modes}).
826 When trace recording is enabled, each function entry and exit adds
827 lines to the trace buffer. A function entry record consists of
828 @samp{::::@{}, followed by the function name and argument values. A
829 function exit record consists of @samp{::::@}}, followed by the function
830 name and result of the function.
832 The number of @samp{:}s in an entry shows its recursion depth. You
833 can use the braces in the trace buffer to find the matching beginning or
834 end of function calls.
836 @findex edebug-print-trace-before
837 @findex edebug-print-trace-after
838 You can customize trace recording for function entry and exit by
839 redefining the functions @code{edebug-print-trace-before} and
840 @code{edebug-print-trace-after}.
842 @defmac edebug-tracing string body@dots{}
843 This macro requests additional trace information around the execution
844 of the @var{body} forms. The argument @var{string} specifies text
845 to put in the trace buffer, after the @samp{@{} or @samp{@}}. All
846 the arguments are evaluated, and @code{edebug-tracing} returns the
847 value of the last form in @var{body}.
850 @defun edebug-trace format-string &rest format-args
851 This function inserts text in the trace buffer. It computes the text
852 with @code{(apply 'format @var{format-string} @var{format-args})}.
853 It also appends a newline to separate entries.
856 @code{edebug-tracing} and @code{edebug-trace} insert lines in the
857 trace buffer whenever they are called, even if Edebug is not active.
858 Adding text to the trace buffer also scrolls its window to show the last
861 @node Coverage Testing
862 @subsection Coverage Testing
864 @cindex coverage testing (Edebug)
865 @cindex frequency counts
866 @cindex performance analysis
867 Edebug provides rudimentary coverage testing and display of execution
870 Coverage testing works by comparing the result of each expression with
871 the previous result; each form in the program is considered ``covered''
872 if it has returned two different values since you began testing coverage
873 in the current Emacs session. Thus, to do coverage testing on your
874 program, execute it under various conditions and note whether it behaves
875 correctly; Edebug will tell you when you have tried enough different
876 conditions that each form has returned two different values.
878 Coverage testing makes execution slower, so it is only done if
879 @code{edebug-test-coverage} is non-@code{nil}. Frequency counting is
880 performed for all executions of an instrumented function, even if the
881 execution mode is Go-nonstop, and regardless of whether coverage testing
885 @findex edebug-temp-display-freq-count
886 Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
887 the coverage information and the frequency counts for a definition.
888 Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
889 information temporarily, only until you type another key.
891 @deffn Command edebug-display-freq-count
892 This command displays the frequency count data for each line of the
895 It inserts frequency counts as comment lines after each line of code.
896 You can undo all insertions with one @code{undo} command. The counts
897 appear under the @samp{(} before an expression or the @samp{)} after
898 an expression, or on the last character of a variable. To simplify
899 the display, a count is not shown if it is equal to the count of an
900 earlier expression on the same line.
902 The character @samp{=} following the count for an expression says that
903 the expression has returned the same value each time it was evaluated.
904 In other words, it is not yet ``covered'' for coverage testing purposes.
906 To clear the frequency count and coverage data for a definition,
907 simply reinstrument it with @code{eval-defun}.
910 For example, after evaluating @code{(fac 5)} with a source
911 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
912 the breakpoint is reached, the frequency data looks like this:
916 (if (= n 0) (edebug))
926 The comment lines show that @code{fac} was called 6 times. The
927 first @code{if} statement returned 5 times with the same result each
928 time; the same is true of the condition on the second @code{if}.
929 The recursive call of @code{fac} did not return at all.
932 @node The Outside Context
933 @subsection The Outside Context
935 Edebug tries to be transparent to the program you are debugging, but it
936 does not succeed completely. Edebug also tries to be transparent when
937 you evaluate expressions with @kbd{e} or with the evaluation list
938 buffer, by temporarily restoring the outside context. This section
939 explains precisely what context Edebug restores, and how Edebug fails to
940 be completely transparent.
943 * Checking Whether to Stop:: When Edebug decides what to do.
944 * Edebug Display Update:: When Edebug updates the display.
945 * Edebug Recursive Edit:: When Edebug stops execution.
948 @node Checking Whether to Stop
949 @subsubsection Checking Whether to Stop
951 Whenever Edebug is entered, it needs to save and restore certain data
952 before even deciding whether to make trace information or stop the
957 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
958 increased to reduce Edebug's impact on the stack. You could, however,
959 still run out of stack space when using Edebug.
962 The state of keyboard macro execution is saved and restored. While
963 Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
964 unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
968 @node Edebug Display Update
969 @subsubsection Edebug Display Update
971 @c This paragraph is not filled, because LaLiberte's conversion script
972 @c needs an xref to be on just one line.
973 When Edebug needs to display something (e.g., in trace mode), it saves
974 the current window configuration from ``outside'' Edebug
975 (@pxref{Window Configurations}). When you exit Edebug (by continuing
976 the program), it restores the previous window configuration.
978 Emacs redisplays only when it pauses. Usually, when you continue
979 execution, the program re-enters Edebug at a breakpoint or after
980 stepping, without pausing or reading input in between. In such cases,
981 Emacs never gets a chance to redisplay the ``outside'' configuration.
982 Consequently, what you see is the same window configuration as the last
983 time Edebug was active, with no interruption.
985 Entry to Edebug for displaying something also saves and restores the
986 following data (though some of them are deliberately not restored if an
987 error or quit signal occurs).
991 @cindex current buffer point and mark (Edebug)
992 Which buffer is current, and the positions of point and the mark in the
993 current buffer, are saved and restored.
996 @cindex window configuration (Edebug)
997 The outside window configuration is saved and restored if
998 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
1000 The window configuration is not restored on error or quit, but the
1001 outside selected window @emph{is} reselected even on error or quit in
1002 case a @code{save-excursion} is active. If the value of
1003 @code{edebug-save-windows} is a list, only the listed windows are saved
1006 The window start and horizontal scrolling of the source code buffer are
1007 not restored, however, so that the display remains coherent within Edebug.
1010 The value of point in each displayed buffer is saved and restored if
1011 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
1014 The variables @code{overlay-arrow-position} and
1015 @code{overlay-arrow-string} are saved and restored, so you can safely
1016 invoke Edebug from the recursive edit elsewhere in the same buffer.
1019 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
1020 the cursor shows up in the window.
1023 @node Edebug Recursive Edit
1024 @subsubsection Edebug Recursive Edit
1026 When Edebug is entered and actually reads commands from the user, it
1027 saves (and later restores) these additional data:
1031 The current match data. @xref{Match Data}.
1034 The variables @code{last-command}, @code{this-command},
1035 @code{last-input-event}, @code{last-command-event},
1036 @code{last-event-frame}, @code{last-nonmenu-event}, and
1037 @code{track-mouse}. Commands used within Edebug do not affect these
1038 variables outside of Edebug.
1040 Executing commands within Edebug can change the key sequence that
1041 would be returned by @code{this-command-keys}, and there is no way to
1042 reset the key sequence from Lisp.
1044 Edebug cannot save and restore the value of
1045 @code{unread-command-events}. Entering Edebug while this variable has a
1046 nontrivial value can interfere with execution of the program you are
1050 Complex commands executed while in Edebug are added to the variable
1051 @code{command-history}. In rare cases this can alter execution.
1054 Within Edebug, the recursion depth appears one deeper than the recursion
1055 depth outside Edebug. This is not true of the automatically updated
1056 evaluation list window.
1059 @code{standard-output} and @code{standard-input} are bound to @code{nil}
1060 by the @code{recursive-edit}, but Edebug temporarily restores them during
1064 The state of keyboard macro definition is saved and restored. While
1065 Edebug is active, @code{defining-kbd-macro} is bound to
1066 @code{edebug-continue-kbd-macro}.
1069 @node Edebug and Macros
1070 @subsection Edebug and Macros
1072 To make Edebug properly instrument expressions that call macros, some
1073 extra care is needed. This subsection explains the details.
1076 * Instrumenting Macro Calls:: The basic problem.
1077 * Specification List:: How to specify complex patterns of evaluation.
1078 * Backtracking:: What Edebug does when matching fails.
1079 * Specification Examples:: To help understand specifications.
1082 @node Instrumenting Macro Calls
1083 @subsubsection Instrumenting Macro Calls
1085 When Edebug instruments an expression that calls a Lisp macro, it needs
1086 additional information about the macro to do the job properly. This is
1087 because there is no a-priori way to tell which subexpressions of the
1088 macro call are forms to be evaluated. (Evaluation may occur explicitly
1089 in the macro body, or when the resulting expansion is evaluated, or any
1092 Therefore, you must define an Edebug specification for each macro
1093 that Edebug will encounter, to explain the format of calls to that
1094 macro. To do this, add a @code{debug} declaration to the macro
1095 definition. Here is a simple example that shows the specification for
1096 the @code{for} example macro (@pxref{Argument Evaluation}).
1099 (defmacro for (var from init to final do &rest body)
1100 "Execute a simple \"for\" loop.
1101 For example, (for i from 1 to 10 do (print i))."
1102 (declare (debug (symbolp "from" form "to" form "do" &rest form)))
1106 The Edebug specification says which parts of a call to the macro are
1107 forms to be evaluated. For simple macros, the specification
1108 often looks very similar to the formal argument list of the macro
1109 definition, but specifications are much more general than macro
1110 arguments. @xref{Defining Macros}, for more explanation of
1111 the @code{declare} form.
1113 You can also define an edebug specification for a macro separately
1114 from the macro definition with @code{def-edebug-spec}. Adding
1115 @code{debug} declarations is preferred, and more convenient, for macro
1116 definitions in Lisp, but @code{def-edebug-spec} makes it possible to
1117 define Edebug specifications for special forms implemented in C.
1119 @deffn Macro def-edebug-spec macro specification
1120 Specify which expressions of a call to macro @var{macro} are forms to be
1121 evaluated. @var{specification} should be the edebug specification.
1122 Neither argument is evaluated.
1124 The @var{macro} argument can actually be any symbol, not just a macro
1128 Here is a table of the possibilities for @var{specification} and how each
1129 directs processing of arguments.
1133 All arguments are instrumented for evaluation.
1136 None of the arguments is instrumented.
1139 The symbol must have an Edebug specification, which is used instead.
1140 This indirection is repeated until another kind of specification is
1141 found. This allows you to inherit the specification from another macro.
1144 The elements of the list describe the types of the arguments of a
1145 calling form. The possible elements of a specification list are
1146 described in the following sections.
1149 If a macro has no Edebug specification, neither through a @code{debug}
1150 declaration nor through a @code{def-edebug-spec} call, the variable
1151 @code{edebug-eval-macro-args} comes into play.
1153 @defopt edebug-eval-macro-args
1154 This controls the way Edebug treats macro arguments with no explicit
1155 Edebug specification. If it is @code{nil} (the default), none of the
1156 arguments is instrumented for evaluation. Otherwise, all arguments
1160 @node Specification List
1161 @subsubsection Specification List
1163 @cindex Edebug specification list
1164 A @dfn{specification list} is required for an Edebug specification if
1165 some arguments of a macro call are evaluated while others are not. Some
1166 elements in a specification list match one or more arguments, but others
1167 modify the processing of all following elements. The latter, called
1168 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
1169 as @code{&optional}).
1171 A specification list may contain sublists which match arguments that are
1172 themselves lists, or it may contain vectors used for grouping. Sublists
1173 and groups thus subdivide the specification list into a hierarchy of
1174 levels. Specification keywords apply only to the remainder of the
1175 sublist or group they are contained in.
1177 When a specification list involves alternatives or repetition, matching
1178 it against an actual macro call may require backtracking. For more
1179 details, @pxref{Backtracking}.
1181 Edebug specifications provide the power of regular expression matching,
1182 plus some context-free grammar constructs: the matching of sublists with
1183 balanced parentheses, recursive processing of forms, and recursion via
1184 indirect specifications.
1186 Here's a table of the possible elements of a specification list, with
1187 their meanings (see @ref{Specification Examples}, for the referenced
1192 A single unevaluated Lisp object, which is not instrumented.
1193 @c an "expression" is not necessarily intended for evaluation.
1196 A single evaluated expression, which is instrumented.
1199 @c I can't see that this index entry is useful without any explanation.
1200 @c @findex edebug-unwrap
1201 A place to store a value, as in the Common Lisp @code{setf} construct.
1204 Short for @code{&rest form}. See @code{&rest} below.
1207 A function form: either a quoted function symbol, a quoted lambda
1208 expression, or a form (that should evaluate to a function symbol or
1209 lambda expression). This is useful when an argument that's a lambda
1210 expression might be quoted with @code{quote} rather than
1211 @code{function}, since it instruments the body of the lambda expression
1215 A lambda expression with no quoting.
1218 @c @kindex &optional @r{(Edebug)}
1219 All following elements in the specification list are optional; as soon
1220 as one does not match, Edebug stops matching at this level.
1222 To make just a few elements optional followed by non-optional elements,
1223 use @code{[&optional @var{specs}@dots{}]}. To specify that several
1224 elements must all match or none, use @code{&optional
1225 [@var{specs}@dots{}]}. See the @code{defun} example.
1228 @c @kindex &rest @r{(Edebug)}
1229 All following elements in the specification list are repeated zero or
1230 more times. In the last repetition, however, it is not a problem if the
1231 expression runs out before matching all of the elements of the
1234 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
1235 To specify several elements that must all match on every repetition, use
1236 @code{&rest [@var{specs}@dots{}]}.
1239 @c @kindex &or @r{(Edebug)}
1240 Each of the following elements in the specification list is an
1241 alternative. One of the alternatives must match, or the @code{&or}
1242 specification fails.
1244 Each list element following @code{&or} is a single alternative. To
1245 group two or more list elements as a single alternative, enclose them in
1249 @c @kindex ¬ @r{(Edebug)}
1250 Each of the following elements is matched as alternatives as if by using
1251 @code{&or}, but if any of them match, the specification fails. If none
1252 of them match, nothing is matched, but the @code{¬} specification
1256 @c @kindex &define @r{(Edebug)}
1257 Indicates that the specification is for a defining form. The defining
1258 form itself is not instrumented (that is, Edebug does not stop before and
1259 after the defining form), but forms inside it typically will be
1260 instrumented. The @code{&define} keyword should be the first element in
1261 a list specification.
1264 This is successful when there are no more arguments to match at the
1265 current argument list level; otherwise it fails. See sublist
1266 specifications and the backquote example.
1269 @cindex preventing backtracking
1270 No argument is matched but backtracking through the gate is disabled
1271 while matching the remainder of the specifications at this level. This
1272 is primarily used to generate more specific syntax error messages. See
1273 @ref{Backtracking}, for more details. Also see the @code{let} example.
1275 @item @var{other-symbol}
1276 @cindex indirect specifications
1277 Any other symbol in a specification list may be a predicate or an
1278 indirect specification.
1280 If the symbol has an Edebug specification, this @dfn{indirect
1281 specification} should be either a list specification that is used in
1282 place of the symbol, or a function that is called to process the
1283 arguments. The specification may be defined with @code{def-edebug-spec}
1284 just as for macros. See the @code{defun} example.
1286 Otherwise, the symbol should be a predicate. The predicate is called
1287 with the argument and the specification fails if the predicate returns
1288 @code{nil}, and the argument is not instrumented.
1290 Some suitable predicates include @code{symbolp}, @code{integerp},
1291 @code{stringp}, @code{vectorp}, and @code{atom}.
1293 @item [@var{elements}@dots{}]
1294 @cindex [@dots{}] (Edebug)
1295 A vector of elements groups the elements into a single @dfn{group
1296 specification}. Its meaning has nothing to do with vectors.
1298 @item "@var{string}"
1299 The argument should be a symbol named @var{string}. This specification
1300 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
1301 of @var{symbol} is the @var{string}, but the string form is preferred.
1303 @item (vector @var{elements}@dots{})
1304 The argument should be a vector whose elements must match the
1305 @var{elements} in the specification. See the backquote example.
1307 @item (@var{elements}@dots{})
1308 Any other list is a @dfn{sublist specification} and the argument must be
1309 a list whose elements match the specification @var{elements}.
1311 @cindex dotted lists (Edebug)
1312 A sublist specification may be a dotted list and the corresponding list
1313 argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
1314 dotted list specification may be another sublist specification (via a
1315 grouping or an indirect specification, e.g., @code{(spec . [(more
1316 specs@dots{})])}) whose elements match the non-dotted list arguments.
1317 This is useful in recursive specifications such as in the backquote
1318 example. Also see the description of a @code{nil} specification
1319 above for terminating such recursion.
1321 Note that a sublist specification written as @code{(specs . nil)}
1322 is equivalent to @code{(specs)}, and @code{(specs .
1323 (sublist-elements@dots{}))} is equivalent to @code{(specs
1324 sublist-elements@dots{})}.
1327 @c Need to document extensions with &symbol and :symbol
1329 Here is a list of additional specifications that may appear only after
1330 @code{&define}. See the @code{defun} example.
1334 The argument, a symbol, is the name of the defining form.
1336 A defining form is not required to have a name field; and it may have
1337 multiple name fields.
1340 This construct does not actually match an argument. The element
1341 following @code{:name} should be a symbol; it is used as an additional
1342 name component for the definition. You can use this to add a unique,
1343 static component to the name of the definition. It may be used more
1347 The argument, a symbol, is the name of an argument of the defining form.
1348 However, lambda-list keywords (symbols starting with @samp{&})
1352 @cindex lambda-list (Edebug)
1353 This matches a lambda list---the argument list of a lambda expression.
1356 The argument is the body of code in a definition. This is like
1357 @code{body}, described above, but a definition body must be instrumented
1358 with a different Edebug call that looks up information associated with
1359 the definition. Use @code{def-body} for the highest level list of forms
1360 within the definition.
1363 The argument is a single, highest-level form in a definition. This is
1364 like @code{def-body}, except it is used to match a single form rather than
1365 a list of forms. As a special case, @code{def-form} also means that
1366 tracing information is not output when the form is executed. See the
1367 @code{interactive} example.
1371 @subsubsection Backtracking in Specifications
1373 @cindex backtracking
1374 @cindex syntax error (Edebug)
1375 If a specification fails to match at some point, this does not
1376 necessarily mean a syntax error will be signaled; instead,
1377 @dfn{backtracking} will take place until all alternatives have been
1378 exhausted. Eventually every element of the argument list must be
1379 matched by some element in the specification, and every required element
1380 in the specification must match some argument.
1382 When a syntax error is detected, it might not be reported until much
1383 later, after higher-level alternatives have been exhausted, and with the
1384 point positioned further from the real error. But if backtracking is
1385 disabled when an error occurs, it can be reported immediately. Note
1386 that backtracking is also reenabled automatically in several situations;
1387 when a new alternative is established by @code{&optional},
1388 @code{&rest}, or @code{&or}, or at the start of processing a sublist,
1389 group, or indirect specification. The effect of enabling or disabling
1390 backtracking is limited to the remainder of the level currently being
1391 processed and lower levels.
1393 Backtracking is disabled while matching any of the
1394 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
1395 @code{def-body}). These specifications will match any form so any error
1396 must be in the form itself rather than at a higher level.
1398 Backtracking is also disabled after successfully matching a quoted
1399 symbol or string specification, since this usually indicates a
1400 recognized construct. But if you have a set of alternative constructs that
1401 all begin with the same symbol, you can usually work around this
1402 constraint by factoring the symbol out of the alternatives, e.g.,
1403 @code{["foo" &or [first case] [second case] ...]}.
1405 Most needs are satisfied by these two ways that backtracking is
1406 automatically disabled, but occasionally it is useful to explicitly
1407 disable backtracking by using the @code{gate} specification. This is
1408 useful when you know that no higher alternatives could apply. See the
1409 example of the @code{let} specification.
1411 @node Specification Examples
1412 @subsubsection Specification Examples
1414 It may be easier to understand Edebug specifications by studying
1415 the examples provided here.
1417 A @code{let} special form has a sequence of bindings and a body. Each
1418 of the bindings is either a symbol or a sublist with a symbol and
1419 optional expression. In the specification below, notice the @code{gate}
1420 inside of the sublist to prevent backtracking once a sublist is found.
1422 @c FIXME? The actual definition in edebug.el does not have a gate.
1424 (def-edebug-spec let
1426 &or symbolp (gate symbolp &optional form))
1430 Edebug uses the following specifications for @code{defun} and the
1431 associated argument list and @code{interactive} specifications. It is
1432 necessary to handle interactive forms specially since an expression
1433 argument is actually evaluated outside of the function body. (The
1434 specification for @code{defmacro} is very similar to that for
1435 @code{defun}, but allows for the @code{declare} statement.)
1438 (def-edebug-spec defun
1439 (&define name lambda-list
1440 [&optional stringp] ; @r{Match the doc string, if present.}
1441 [&optional ("interactive" interactive)]
1444 (def-edebug-spec lambda-list
1446 [&optional ["&optional" arg &rest arg]]
1447 &optional ["&rest" arg]
1450 (def-edebug-spec interactive
1451 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
1454 The specification for backquote below illustrates how to match
1455 dotted lists and use @code{nil} to terminate recursion. It also
1456 illustrates how components of a vector may be matched. (The actual
1457 specification defined by Edebug is a little different, and does not
1458 support dotted lists because doing so causes very deep recursion that
1462 (def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.}
1464 (def-edebug-spec backquote-form
1465 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
1466 (backquote-form . [&or nil backquote-form])
1467 (vector &rest backquote-form)
1472 @node Edebug Options
1473 @subsection Edebug Options
1475 These options affect the behavior of Edebug:
1476 @c Previously defopt'd:
1477 @c edebug-sit-for-seconds, edebug-print-length, edebug-print-level
1478 @c edebug-print-circle, edebug-eval-macro-args
1480 @defopt edebug-setup-hook
1481 Functions to call before Edebug is used. Each time it is set to a new
1482 value, Edebug will call those functions once and then
1483 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to
1484 load up Edebug specifications associated with a package you are using
1485 but only when you also use Edebug.
1486 @xref{Instrumenting}.
1489 @defopt edebug-all-defs
1490 If this is non-@code{nil}, normal evaluation of defining forms such as
1491 @code{defun} and @code{defmacro} instruments them for Edebug. This
1492 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
1493 and @code{eval-current-buffer}.
1495 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
1496 option. @xref{Instrumenting}.
1499 @defopt edebug-all-forms
1500 If this is non-@code{nil}, the commands @code{eval-defun},
1501 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
1502 instrument all forms, even those that don't define anything.
1503 This doesn't apply to loading or evaluations in the minibuffer.
1505 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
1506 option. @xref{Instrumenting}.
1509 @defopt edebug-save-windows
1510 If this is non-@code{nil}, Edebug saves and restores the window
1511 configuration. That takes some time, so if your program does not care
1512 what happens to the window configurations, it is better to set this
1513 variable to @code{nil}.
1515 If the value is a list, only the listed windows are saved and
1518 You can use the @kbd{W} command in Edebug to change this variable
1519 interactively. @xref{Edebug Display Update}.
1522 @defopt edebug-save-displayed-buffer-points
1523 If this is non-@code{nil}, Edebug saves and restores point in all
1526 Saving and restoring point in other buffers is necessary if you are
1527 debugging code that changes the point of a buffer that is displayed in
1528 a non-selected window. If Edebug or the user then selects the window,
1529 point in that buffer will move to the window's value of point.
1531 Saving and restoring point in all buffers is expensive, since it
1532 requires selecting each window twice, so enable this only if you need
1533 it. @xref{Edebug Display Update}.
1536 @defopt edebug-initial-mode
1537 If this variable is non-@code{nil}, it specifies the initial execution
1538 mode for Edebug when it is first activated. Possible values are
1539 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
1540 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
1542 The default value is @code{step}.
1543 @xref{Edebug Execution Modes}.
1546 @defopt edebug-trace
1547 If this is non-@code{nil}, trace each function entry and exit.
1548 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
1549 function entry or exit per line, indented by the recursion level.
1551 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
1554 @defopt edebug-test-coverage
1555 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
1556 @xref{Coverage Testing}.
1559 @defopt edebug-continue-kbd-macro
1560 If non-@code{nil}, continue defining or executing any keyboard macro
1561 that is executing outside of Edebug. Use this with caution since it is not
1563 @xref{Edebug Execution Modes}.
1566 @c FIXME edebug-unwrap-results
1568 @defopt edebug-on-error
1569 Edebug binds @code{debug-on-error} to this value, if
1570 @code{debug-on-error} was previously @code{nil}. @xref{Trapping
1574 @defopt edebug-on-quit
1575 Edebug binds @code{debug-on-quit} to this value, if
1576 @code{debug-on-quit} was previously @code{nil}. @xref{Trapping
1580 If you change the values of @code{edebug-on-error} or
1581 @code{edebug-on-quit} while Edebug is active, their values won't be used
1582 until the @emph{next} time Edebug is invoked via a new command.
1583 @c Not necessarily a deeper command level.
1584 @c A new command is not precisely true, but that is close enough -- dan
1586 @defopt edebug-global-break-condition
1587 If non-@code{nil}, an expression to test for at every stop point. If
1588 the result is non-@code{nil}, then break. Errors are ignored.
1589 @xref{Global Break Condition}.
1593 arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd