3 @node Edebug, , Compilation Errors, Top
8 Edebug is a source-level debugger for SXEmacs and XEmacs Lisp programs
9 that provides the following features:
13 Step through evaluation, stopping before and after each expression.
16 Set conditional or unconditional breakpoints, install embedded
17 breakpoints, or a global break event.
20 Trace slow or fast stopping briefly at each stop point, or
24 Display expression results and evaluate expressions as if outside of
25 Edebug. Interface with the custom printing package
26 for printing circular structures.
29 Automatically reevaluate a list of expressions and
30 display their results each time Edebug updates the display.
33 Output trace info on function enter and exit.
36 Errors stop before the source causing the error.
39 Display backtrace without Edebug calls.
42 Allow specification of argument evaluation for macros and defining forms.
45 Provide rudimentary coverage testing and display of frequency counts.
49 The first three sections should tell you enough about Edebug to enable
53 * Using Edebug:: Introduction to use of Edebug.
54 * Instrumenting:: You must first instrument code.
55 * Edebug Execution Modes:: Execution modes, stopping more or less often.
56 * Jumping:: Commands to jump to a specified place.
57 * Edebug Misc:: Miscellaneous commands.
58 * Breakpoints:: Setting breakpoints to make the program stop.
59 * Trapping Errors:: trapping errors with Edebug.
60 * Edebug Views:: Views inside and outside of Edebug.
61 * Edebug Eval:: Evaluating expressions within Edebug.
62 * Eval List:: Automatic expression evaluation.
63 * Reading in Edebug:: Customization of reading.
64 * Printing in Edebug:: Customization of printing.
65 * Tracing:: How to produce tracing output.
66 * Coverage Testing:: How to test evaluation coverage.
67 * The Outside Context:: Data that Edebug saves and restores.
68 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
69 * Edebug Options:: Option variables for customizing Edebug.
74 @subsection Using Edebug
76 To debug a SXEmacs Lisp program with Edebug, you must first
77 @dfn{instrument} the Lisp code that you want to debug. If you want to
78 just try it now, load @file{edebug.el}, move point into a definition and
79 do @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument).
80 See @ref{Instrumenting} for alternative ways to instrument code.
82 Once a function is instrumented, any call to the function activates
83 Edebug. Activating Edebug may stop execution and let you step through
84 the function, or it may update the display and continue execution while
85 checking for debugging commands, depending on the selected Edebug
86 execution mode. The initial execution mode is @code{step}, by default,
87 which does stop execution. @xref{Edebug Execution Modes}.
89 Within Edebug, you normally view an SXEmacs buffer showing the source
90 of the Lisp function you are debugging. This is referred to as the
91 @dfn{source code buffer}---but note that it is not always the same
92 buffer depending on which function is currently being executed.
94 An arrow at the left margin indicates the line where the function is
95 executing. Point initially shows where within the line the function is
96 executing, but you can move point yourself.
98 If you instrument the definition of @code{fac} (shown below) and then
99 execute @code{(fac 3)}, here is what you normally see. Point is at the
100 open-parenthesis before @code{if}.
104 =>@point{}(if (< 0 n)
110 The places within a function where Edebug can stop execution are called
111 @dfn{stop points}. These occur both before and after each subexpression
112 that is a list, and also after each variable reference.
113 Here we show with periods the stop points found in the function
119 .(* n. .(fac (1- n.).).).
123 While the source code buffer is selected, the special commands of Edebug
124 are available in it, in addition to the commands of SXEmacs Lisp mode.
125 The buffer is temporarily made read-only, however. For example, you
126 can type the Edebug command @key{SPC} to execute until the next stop
127 point. If you type @key{SPC} once after entry to @code{fac}, here is
128 the display you will see:
132 =>(if @point{}(< 0 n)
137 When Edebug stops execution after an expression, it displays the
138 expression's value in the echo area.
140 Other frequently used commands are @kbd{b} to set a breakpoint at a stop
141 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
142 exit to the top-level command loop. Type @kbd{?} to display a list of
147 @subsection Instrumenting for Edebug
149 In order to use Edebug to debug Lisp code, you must first
150 @dfn{instrument} the code. Instrumenting a form inserts additional code
151 into it which invokes Edebug at the proper places. Furthermore, if
152 Edebug detects a syntax error while instrumenting, point is left at the
153 erroneous code and an @code{invalid-read-syntax} error is signaled.
156 @findex eval-defun (Edebug)
157 @findex edebug-all-defs
158 Once you have loaded Edebug, the command @kbd{C-M-x}
159 (@code{eval-defun}) is redefined so that when invoked with a prefix
160 argument on a definition, it instruments the definition before
161 evaluating it. The source code itself is not modified. If the
162 variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
163 meaning of the prefix argument: then @kbd{C-M-x} instruments the
164 definition @emph{unless} it has a prefix argument. The default value of
165 @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x
166 edebug-all-defs} toggles the value of the variable
167 @code{edebug-all-defs}.
169 @findex edebug-all-forms
170 @findex eval-region (Edebug)
171 @findex eval-current-buffer (Edebug)
172 If @code{edebug-all-defs} is non-@code{nil}, then the commands
173 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
174 also instrument any definitions they evaluate. Similarly,
175 @code{edebug-all-forms} controls whether @code{eval-region} should
176 instrument @emph{any} form, even non-defining forms. This doesn't apply
177 to loading or evaluations in the minibuffer. The command @kbd{M-x
178 edebug-all-forms} toggles this option.
180 @findex edebug-eval-top-level-form
181 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
182 instrument any top-level form regardless of the value of
183 @code{edebug-all-defs} or @code{edebug-all-forms}.
185 Just before Edebug instruments any code, it calls any functions in the
186 variable @code{edebug-setup-hook} and resets its value to @code{nil}.
187 You could use this to load up Edebug specifications associated with a
188 package you are using but only when you also use Edebug. For example,
189 @file{my-specs.el} may be loaded automatically when you use
190 @code{my-package} with Edebug by including the following code in
191 @file{my-package.el}.
194 (add-hook 'edebug-setup-hook
195 (function (lambda () (require 'my-specs))))
198 While Edebug is active, the command @kbd{I}
199 (@code{edebug-instrument-callee}) instruments the definition of the
200 function or macro called by the list form after point, if is not already
201 instrumented. If the location of the definition is not known to Edebug,
202 this command cannot be used. After loading Edebug, @code{eval-region}
203 records the position of every definition it evaluates, even if not
204 instrumenting it. Also see the command @kbd{i} (@ref{Jumping}) which
205 steps into the callee.
207 @cindex special forms (Edebug)
208 @cindex interactive commands (Edebug)
209 @cindex anonymous lambda expressions (Edebug)
210 @cindex Common Lisp (Edebug)
211 @pindex cl.el (Edebug)
213 Edebug knows how to instrument all the standard special forms, an
214 interactive form with an expression argument, anonymous lambda
215 expressions, and other defining forms. Specifications for macros
216 defined by @file{cl.el} (version 2.03) are provided in
217 @file{cl-specs.el}. Edebug cannot know what a user-defined macro will
218 do with the arguments of a macro call so you must tell it. See
219 @ref{Instrumenting Macro Calls} for the details.
221 @findex eval-expression (Edebug)
222 Note that a couple ways remain to evaluate expressions without
223 instrumenting them. Loading a file via the @code{load} subroutine does
224 not instrument expressions for Edebug. Evaluations in the minibuffer
225 via @code{eval-expression} (@kbd{M-ESC}) are not instrumented.
227 To remove instrumentation from a definition, simply reevaluate it with
228 one of the non-instrumenting commands, or reload the file.
230 See @ref{Edebug Eval} for other evaluation functions available
234 @node Edebug Execution Modes
235 @subsection Edebug Execution Modes
237 @cindex Edebug execution modes
238 Edebug supports several execution modes for running the program you are
239 debugging. We call these alternatives @dfn{Edebug execution modes}; do
240 not confuse them with major or minor modes. The current Edebug
241 execution mode determines how Edebug displays the progress of the
242 evaluation, whether it stops at each stop point, or continues to the
243 next breakpoint, for example.
245 Normally, you specify the Edebug execution mode by typing a command
246 to continue the program in a certain mode. Here is a table of these
247 commands. All except for @kbd{S} resume execution of the program, at
248 least for a certain distance.
252 Stop: don't execute any more of the program for now, just wait for more
253 Edebug commands (@code{edebug-stop}).
256 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
259 Next: stop at the next stop point encountered after an expression
260 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
264 Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
267 Rapid trace: update at each stop point, but don't actually
268 pause (@code{edebug-Trace-fast-mode}).
271 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
274 Continue: pause for one second at each breakpoint, but don't stop
275 (@code{edebug-continue-mode}).
278 Rapid continue: update at each breakpoint, but don't actually pause
279 (@code{edebug-Continue-fast-mode}).
282 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
283 can still stop the program by hitting any key.
286 In general, the execution modes earlier in the above list run the
287 program more slowly or stop sooner.
289 When you enter a new Edebug level, the initial execution mode comes from
290 the value of the variable @code{edebug-initial-mode}. By default, this
291 specifies @code{step} mode. Note that you may reenter the same Edebug
292 level several times if, for example, an instrumented function is called
293 several times from one command.
295 While executing or tracing, you can interrupt the execution by typing
296 any Edebug command. Edebug stops the program at the next stop point and
297 then executes the command that you typed. For example, typing @kbd{t}
298 during execution switches to trace mode at the next stop point. You can
299 use @kbd{S} to stop execution without doing anything else.
301 If your function happens to read input, a character you hit intending to
302 interrupt execution may be read by the function instead. You can avoid
303 such unintended results by paying attention to when your program wants
306 @cindex keyboard macros (Edebug)
307 Keyboard macros containing Edebug commands do not work; when you exit
308 from Edebug, to resume the program, whether you are defining or
309 executing a keyboard macro is forgotten. Also, defining or executing a
310 keyboard macro outside of Edebug does not affect the command loop inside
311 Edebug. This is usually an advantage. But see
312 @code{edebug-continue-kbd-macro}.
318 Commands described here let you jump to a specified location.
319 All, except @kbd{i}, use temporary breakpoints to establish the stop
320 point and then switch to @code{go} mode. Any other breakpoint reached
321 before the intended stop point will also stop execution. See
322 @ref{Breakpoints} for the details on breakpoints.
326 Run the program forward over one expression
327 (@code{edebug-forward-sexp}). More precisely, set a temporary
328 breakpoint at the position that @kbd{C-M-f} would reach, then execute in
329 @code{go} mode so that the program will stop at breakpoints.
331 With a prefix argument @var{n}, the temporary breakpoint is placed
332 @var{n} sexps beyond point. If the containing list ends before @var{n}
333 more elements, then the place to stop is after the containing
336 Be careful that the position @kbd{C-M-f} finds is a place that the
337 program will really get to; this may not be true in a
338 @code{cond}, for example.
340 This command does @code{forward-sexp} starting at point rather than the
341 stop point. If you want to execute one expression from the current stop
342 point, type @kbd{w} first, to move point there.
345 Continue ``out of'' an expression (@code{edebug-step-out}). It places a
346 temporary breakpoint at the end of the sexp containing point.
348 If the containing sexp is a function definition itself, it continues
349 until just before the last sexp in the definition. If that is where you
350 are now, it returns from the function and then stops. In other words,
351 this command does not exit the currently executing function unless you
352 are positioned after the last sexp.
355 Step into the function or macro after point after first ensuring that it
356 is instrumented. It does this by calling @code{edebug-on-entry} and
357 then switching to @code{go} mode.
359 Although the automatic instrumentation is convenient, it is not
360 later automatically uninstrumented.
363 Proceed to the stop point near where point is using a temporary
364 breakpoint (@code{edebug-goto-here}).
368 All the commands in this section may fail to work as expected in case
369 of nonlocal exit, because a nonlocal exit can bypass the temporary
370 breakpoint where you expected the program to stop.
374 @subsection Miscellaneous
376 Some miscellaneous commands are described here.
380 Display the help message for Edebug (@code{edebug-help}).
383 Abort one level back to the previous command level
384 (@code{abort-recursive-edit}).
387 Return to the top level editor command loop (@code{top-level}). This
388 exits all recursive editing levels, including all levels of Edebug
389 activity. However, instrumented code protected with
390 @code{unwind-protect} or @code{condition-case} forms may resume
394 Like @kbd{q} but don't stop even for protected code
395 (@code{top-level-nonstop}).
398 Redisplay the most recently known expression result in the echo area
399 (@code{edebug-previous-result}).
402 Display a backtrace, excluding Edebug's own functions for clarity
403 (@code{edebug-backtrace}).
405 You cannot use debugger commands in the backtrace buffer in Edebug as
406 you would in the standard debugger.
408 The backtrace buffer is killed automatically when you continue
412 From the Edebug recursive edit, you may invoke commands that activate
413 Edebug again recursively. Any time Edebug is active, you can quit to
414 the top level with @kbd{q} or abort one recursive edit level with
415 @kbd{C-]}. You can display a backtrace of all the
416 pending evaluations with @kbd{d}.
420 @subsection Breakpoints
423 There are three more ways to stop execution once it has started:
424 breakpoints, the global break condition, and embedded breakpoints.
426 While using Edebug, you can specify @dfn{breakpoints} in the program you
427 are testing: points where execution should stop. You can set a
428 breakpoint at any stop point, as defined in @ref{Using Edebug}. For
429 setting and unsetting breakpoints, the stop point that is affected is
430 the first one at or after point in the source code buffer. Here are the
431 Edebug commands for breakpoints:
435 Set a breakpoint at the stop point at or after point
436 (@code{edebug-set-breakpoint}). If you use a prefix argument, the
437 breakpoint is temporary (it turns off the first time it stops the
441 Unset the breakpoint (if any) at the stop point at or after the current
442 point (@code{edebug-unset-breakpoint}).
444 @item x @var{condition} @key{RET}
445 Set a conditional breakpoint which stops the program only if
446 @var{condition} evaluates to a non-@code{nil} value
447 (@code{edebug-set-conditional-breakpoint}). If you use a prefix
448 argument, the breakpoint is temporary (it turns off the first time it
452 Move point to the next breakpoint in the definition
453 (@code{edebug-next-breakpoint}).
456 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
457 with @kbd{u}. First you must move point to a position at or before the
458 desired Edebug stop point, then hit the key to change the breakpoint.
459 Unsetting a breakpoint that has not been set does nothing.
461 Reevaluating or reinstrumenting a definition clears all its breakpoints.
463 A @dfn{conditional breakpoint} tests a condition each time the program
464 gets there. To set a conditional breakpoint, use @kbd{x}, and specify
465 the condition expression in the minibuffer. Setting a conditional
466 breakpoint at a stop point that already has a conditional breakpoint
467 puts the current condition expression in the minibuffer so you can edit
470 You can make both conditional and unconditional breakpoints
471 @dfn{temporary} by using a prefix arg to the command to set the
472 breakpoint. After breaking at a temporary breakpoint, it is
473 automatically cleared.
475 Edebug always stops or pauses at a breakpoint except when the Edebug
476 mode is @code{Go-nonstop}. In that mode, it ignores breakpoints entirely.
478 To find out where your breakpoints are, use @kbd{B}, which
479 moves point to the next breakpoint in the definition following point, or
480 to the first breakpoint if there are no following breakpoints. This
481 command does not continue execution---it just moves point in the buffer.
484 * Global Break Condition:: Breaking on an event.
485 * Embedded Breakpoints:: Embedding breakpoints in code.
489 @node Global Break Condition
490 @subsubsection Global Break Condition
492 @cindex stopping on events
493 @cindex global break condition
494 In contrast to breaking when execution reaches specified locations,
495 you can also cause a break when a certain event occurs. The @dfn{global
496 break condition} is a condition that is repeatedly evaluated at every
497 stop point. If it evaluates to a non-@code{nil} value, then execution
498 is stopped or paused depending on the execution mode, just like a
499 breakpoint. Any errors that might occur as a result of evaluating the
500 condition are ignored, as if the result were @code{nil}.
502 @findex edebug-set-global-break-condition
503 @vindex edebug-global-break-condition
504 You can set or edit the condition expression, stored in
505 @code{edebug-global-break-condition}, using @kbd{X}
506 (@code{edebug-set-global-break-condition}).
508 Using the global break condition is perhaps the fastest way
509 to find where in your code some event occurs, but since it is rather
510 expensive you should reset the condition to @code{nil} when not in use.
513 @node Embedded Breakpoints
514 @subsubsection Embedded Breakpoints
517 @cindex embedded breakpoints
518 Since all breakpoints in a definition are cleared each time you
519 reinstrument it, you might rather create an @dfn{embedded breakpoint}
520 which is simply a call to the function @code{edebug}. You can, of
521 course, make such a call conditional. For example, in the @code{fac}
522 function, insert the first line as shown below to stop when the argument
527 (if (= n 0) (edebug))
533 When the @code{fac} definition is instrumented and the function is
534 called, Edebug will stop before the call to @code{edebug}. Depending on
535 the execution mode, Edebug will stop or pause.
537 However, if no instrumented code is being executed, calling
538 @code{edebug} will instead invoke @code{debug}. Calling @code{debug}
539 will always invoke the standard backtrace debugger.
542 @node Trapping Errors
543 @subsection Trapping Errors
545 @vindex edebug-on-error
546 @vindex edebug-on-quit
547 An error may be signaled by subroutines or XEmacs Lisp code. If a signal
548 is not handled by a @code{condition-case}, this indicates an
549 unrecognized situation has occurred. If Edebug is not active when an
550 unhandled error is signaled, @code{debug} is run normally (if
551 @code{debug-on-error} is non-@code{nil}). But while Edebug is active,
552 @code{debug-on-error} and @code{debug-on-quit} are bound to
553 @code{edebug-on-error} and @code{edebug-on-quit}, which are both
554 @code{t} by default. Actually, if @code{debug-on-error} already has
555 a non-@code{nil} value, that value is still used.
557 It is best to change the values of @code{edebug-on-error} or
558 @code{edebug-on-quit} when Edebug is not active since their values won't
559 be used until the next time Edebug is invoked at a deeper command level.
560 If you only change @code{debug-on-error} or @code{debug-on-quit} while
561 Edebug is active, these changes will be forgotten when Edebug becomes
562 inactive. Furthermore, during Edebug's recursive edit, these variables
563 are bound to the values they had outside of Edebug.
565 Edebug shows you the last stop point that it knew about before the
566 error was signaled. This may be the location of a call to a function
567 which was not instrumented, within which the error actually occurred.
568 For an unbound variable error, the last known stop point might be quite
569 distant from the offending variable. If the cause of the error is not
570 obvious at first, note that you can also get a full backtrace inside of
571 Edebug (see @ref{Edebug Misc}).
573 Edebug can also trap signals even if they are handled. If
574 @code{debug-on-error} is a list of signal names, Edebug will stop when
575 any of these errors are signaled. Edebug shows you the last known stop
576 point just as for unhandled errors. After you continue execution, the
577 error is signaled again (but without being caught by Edebug). Edebug
578 can only trap errors that are handled if they are signaled in Lisp code
579 (not subroutines) since it does so by temporarily replacing the
580 @code{signal} function.
584 @subsection Edebug Views
586 The following Edebug commands let you view aspects of the buffer and
587 window status that obtained before entry to Edebug.
591 View the outside window configuration (@code{edebug-view-outside}).
594 Temporarily display the outside current buffer with point at its outside
595 position (@code{edebug-bounce-point}). If prefix arg is supplied, sit for
596 that many seconds instead.
599 Move point back to the current stop point (@code{edebug-where}) in the
600 source code buffer. Also, if you use this command in another window
601 displaying the same buffer, this window will be used instead to
602 display the buffer in the future.
605 Toggle the @code{edebug-save-windows} variable which indicates whether
606 the outside window configuration is saved and restored
607 (@code{edebug-toggle-save-windows}). Also, each time it is toggled on,
608 make the outside window configuration the same as the current window
611 With a prefix argument, @code{edebug-toggle-save-windows} only toggles
612 saving and restoring of the selected window. To specify a window that
613 is not displaying the source code buffer, you must use @kbd{C-xXW} from
618 You can view the outside window configuration with @kbd{v} or just
619 bounce to the current point in the current buffer with @kbd{p}, even if
620 it is not normally displayed. After moving point, you may wish to pop
621 back to the stop point with @kbd{w} from a source code buffer.
623 By using @kbd{W} twice, Edebug again saves and restores the
624 outside window configuration, but to the current configuration. This is
625 a convenient way to, for example, add another buffer to be displayed
626 whenever Edebug is active. However, the automatic redisplay of
627 @samp{*edebug*} and @samp{*edebug-trace*} may conflict with the buffers
628 you wish to see unless you have enough windows open.
632 @subsection Evaluation
634 While within Edebug, you can evaluate expressions ``as if'' Edebug were
635 not running. Edebug tries to be invisible to the expression's
636 evaluation and printing. Evaluation of expressions that cause side
637 effects will work as expected except for things that Edebug explicitly
638 saves and restores. See @ref{The Outside Context} for details on this
639 process. Also see @ref{Reading in Edebug} and @ref{Printing in Edebug}
640 for topics related to evaluation.
643 @item e @var{exp} @key{RET}
644 Evaluate expression @var{exp} in the context outside of Edebug
645 (@code{edebug-eval-expression}). In other words, Edebug tries to avoid
646 altering the effect of @var{exp}.
648 @item M-@key{ESC} @var{exp} @key{RET}
649 Evaluate expression @var{exp} in the context of Edebug itself.
652 Evaluate the expression before point, in the context outside of Edebug
653 (@code{edebug-eval-last-sexp}).
656 @cindex lexical binding (Edebug)
657 Edebug supports evaluation of expressions containing references to
658 lexically bound symbols created by the following constructs in
659 @file{cl.el} (version 2.03 or later): @code{lexical-let},
660 @code{macrolet}, and @code{symbol-macrolet}.
664 @subsection Evaluation List Buffer
666 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
667 evaluate expressions interactively. You can also set up the
668 @dfn{evaluation list} of expressions to be evaluated automatically each
669 time Edebug updates the display.
673 Switch to the evaluation list buffer @samp{*edebug*}
674 (@code{edebug-visit-eval-list}).
677 In the @samp{*edebug*} buffer you can use the commands of Lisp
678 Interaction as well as these special commands:
682 Evaluate the expression before point, in the outside context, and insert
683 the value in the buffer (@code{edebug-eval-print-last-sexp}).
686 Evaluate the expression before point, in the context outside of Edebug
687 (@code{edebug-eval-last-sexp}).
690 Build a new evaluation list from the first expression of each group,
691 reevaluate and redisplay (@code{edebug-update-eval-list}). Groups are
692 separated by comment lines.
695 Delete the evaluation list group that point is in
696 (@code{edebug-delete-eval-item}).
699 Switch back to the source code buffer at the current stop point
700 (@code{edebug-where}).
703 You can evaluate expressions in the evaluation list window with
704 @kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
705 but they are evaluated in the context outside of Edebug.
707 @cindex evaluation list (Edebug)
708 The expressions you enter interactively (and their results) are lost
709 when you continue execution unless you add them to the
710 evaluation list with @kbd{C-c C-u}. This command builds a new list from
711 the first expression of each @dfn{evaluation list group}. Groups are
712 separated by comment lines. Be careful not to add expressions that
713 execute instrumented code otherwise an infinite loop will result.
715 When the evaluation list is redisplayed, each expression is displayed
716 followed by the result of evaluating it, and a comment line. If an
717 error occurs during an evaluation, the error message is displayed in a
718 string as if it were the result. Therefore expressions that, for
719 example, use variables not currently valid do not interrupt your
722 Here is an example of what the evaluation list window looks like after
723 several expressions have been added to it:
728 ;---------------------------------------------------------------
730 #<window 16 on *scratch*>
731 ;---------------------------------------------------------------
734 ;---------------------------------------------------------------
736 "Symbol's value as variable is void: bad-var"
737 ;---------------------------------------------------------------
740 ;---------------------------------------------------------------
743 ;---------------------------------------------------------------
746 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
747 delete the text for the group and update the evaluation list with
748 @kbd{C-c C-u}. When you add a new group, be sure it is separated from
749 its neighbors by a comment line.
751 After selecting @samp{*edebug*}, you can return to the source code
752 buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
753 you continue execution, and recreated next time it is needed.
756 @node Reading in Edebug
757 @subsection Reading in Edebug
759 @cindex reading (Edebug)
760 To instrument a form, Edebug first reads the whole form. Edebug
761 replaces the standard Lisp Reader with its own reader that remembers the
762 positions of expressions. This reader is used by the Edebug
763 replacements for @code{eval-region}, @code{eval-defun},
764 @code{eval-buffer}, and @code{eval-current-buffer}.
767 Another package, @file{cl-read.el}, replaces the standard reader with
768 one that understands Common Lisp reader macros. If you use that
769 package, Edebug will automatically load @file{edebug-cl-read.el} to
770 provide corresponding reader macros that remember positions of
771 expressions. If you define new reader macros, you will have to define
772 similar reader macros for Edebug.
775 @node Printing in Edebug
776 @subsection Printing in Edebug
778 @cindex printing (Edebug)
779 @cindex printing circular structures
781 If the result of an expression in your program contains a circular
782 reference, you may get an error when Edebug attempts to print it. You
783 can set @code{print-length} to a non-zero value to limit the print
784 length of lists (the number of cdrs), and in Emacs 19, set
785 @code{print-level} to a non-zero value to limit the print depth of
786 lists. But you can print such circular structures and structures that
787 share elements more informatively by using the @file{cust-print}
790 To load @file{cust-print} and activate custom printing only for Edebug,
791 simply use the command @kbd{M-x edebug-install-custom-print}. To
792 restore the standard print functions, use @kbd{M-x
793 edebug-uninstall-custom-print}. You can also activate custom printing
794 for printing in any Lisp code; see the package for details.
796 Here is an example of code that creates a circular structure:
800 (edebug-install-custom-print)
805 Edebug will print the result of the @code{setcar} as @samp{Result:
806 #1=(#1# y)}. The @samp{#1=} notation names the structure that follows
807 it, and the @samp{#1#} notation references the previously named
808 structure. This notation is used for any shared elements of lists or
811 @vindex edebug-print-length
812 @vindex edebug-print-level
813 @vindex edebug-print-circle
814 @vindex print-readably
815 Independent of whether @file{cust-print} is active, while printing
816 results Edebug binds @code{print-length}, @code{print-level}, and
817 @code{print-circle} to @code{edebug-print-length} (@code{50}),
818 @code{edebug-print-level} (@code{50}), and @code{edebug-print-circle}
819 (@code{t}) respectively, if these values are non-@code{nil}. Also,
820 @code{print-readably} is bound to @code{nil} since some objects simply
821 cannot be printed readably.
828 In addition to automatic stepping through source code, which is also
829 called @emph{tracing} (see @ref{Edebug Execution Modes}), Edebug can
830 produce a traditional trace listing of execution in a separate buffer,
831 @samp{*edebug-trace*}.
833 @findex edebug-print-trace-before
834 @findex edebug-print-trace-after
835 If the variable @code{edebug-trace} is non-@code{nil}, each function entry and
836 exit adds lines to the trace buffer. On function entry, Edebug prints
837 @samp{::::@{} followed by the function name and argument values. On
838 function exit, Edebug prints @samp{::::@}} followed by the function name
839 and result of the function. The number of @samp{:}s is computed from
840 the recursion depth. The balanced braces in the trace buffer can be
841 used to find the matching beginning or end of function calls. These
842 displays may be customized by replacing the functions
843 @code{edebug-print-trace-before} and @code{edebug-print-trace-after},
844 which take an arbitrary message string to print.
846 @findex edebug-tracing
847 The macro @code{edebug-tracing} provides tracing similar to function
848 enter and exit tracing, but for arbitrary expressions. This macro
849 should be explicitly inserted by you around expressions you wish to
850 trace the execution of. The first argument is a message string
851 (evaluated), and the rest are expressions to evaluate. The result of
852 the last expression is returned.
855 Finally, you can insert arbitrary strings into the trace buffer with
856 explicit calls to @code{edebug-trace}. The arguments of this function
857 are the same as for @code{message}, but a newline is always inserted
858 after each string printed in this way.
860 @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
861 buffer even if Edebug is not active. Every time the trace buffer is
862 added to, the window is scrolled to show the last lines inserted.
863 (There may be some display problems if you use tracing along with the
867 @node Coverage Testing
868 @subsection Coverage Testing
870 @cindex coverage testing
871 @cindex frequency counts
872 @cindex performance analysis
873 Edebug provides a rudimentary coverage tester and display of execution
874 frequency. Frequency counts are always accumulated, both before and
875 after evaluation of each instrumented expression, even if the execution
876 mode is @code{Go-nonstop}. Coverage testing is only done if the option
877 @code{edebug-test-coverage} is non-@code{nil} because this is relatively
878 expensive. Both data sets are displayed by @kbd{M-x
879 edebug-display-freq-count}.
881 @deffn Command edebug-display-freq-count
882 Display the frequency count data for each line of the current
883 definition. The frequency counts are inserted as comment lines after
884 each line, and you can undo all insertions with one @code{undo} command.
885 The counts are inserted starting under the @kbd{(} before an expression
886 or the @kbd{)} after an expression, or on the last char of a symbol.
887 The counts are only displayed when they differ from previous counts on
890 If coverage is being tested, whenever all known results of an expression
891 are @code{eq}, the char @kbd{=} will be appended after the count
892 for that expression. Note that this is always the case for an
893 expression only evaluated once.
895 To clear the frequency count and coverage data for a definition,
900 For example, after evaluating @code{(fac 5)} with an embedded
901 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
902 the breakpoint is reached, the frequency data is looks like this:
906 (if (= n 0) (edebug))
916 The comment lines show that @code{fac} has been called 6 times. The
917 first @code{if} statement has returned 5 times with the same result each
918 time, and the same is true for the condition on the second @code{if}.
919 The recursive call of @code{fac} has not returned at all.
922 @node The Outside Context
923 @subsection The Outside Context
925 Edebug tries to be transparent to the program you are debugging. In
926 addition, most evaluations you do within Edebug (see @ref{Edebug Eval})
927 occur in the same outside context which is temporarily restored for the
928 evaluation. But Edebug is not completely successful and this section
929 explains precisely how it fails.
931 Edebug operation unavoidably alters some data in SXEmacs, and this can
932 interfere with debugging certain programs. Also notice that Edebug's
933 protection against change of outside data means that any side effects
934 @emph{intended} by the user in the course of debugging will be
938 * Checking Whether to Stop:: When Edebug decides what to do.
939 * Edebug Display Update:: When Edebug updates the display.
940 * Edebug Recursive Edit:: When Edebug stops execution.
944 @node Checking Whether to Stop
945 @subsubsection Checking Whether to Stop
947 Whenever Edebug is entered just to think about whether to take some
948 action, it needs to save and restore certain data.
952 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
953 incremented one time to reduce Edebug's impact on the stack.
954 You could, however, still run out of stack space when using Edebug.
957 The state of keyboard macro execution is saved and restored. While
958 Edebug is active, @code{executing-macro} is bound to
959 @code{edebug-continue-kbd-macro}.
964 @node Edebug Display Update
965 @subsubsection Edebug Display Update
967 When Edebug needs to display something (e.g., in trace mode), it saves
968 the current window configuration from ``outside'' Edebug. When you exit
969 Edebug (by continuing the program), it restores the previous window
972 SXEmacs redisplays only when it pauses. Usually, when you continue
973 execution, the program comes back into Edebug at a breakpoint or after
974 stepping without pausing or reading input in between. In such cases,
975 SXEmacs never gets a chance to redisplay the ``outside'' configuration.
976 What you see is the same window configuration as the last time Edebug
977 was active, with no interruption.
979 Entry to Edebug for displaying something also saves and restores the
980 following data, but some of these are deliberately not restored if an
981 error or quit signal occurs.
985 @cindex current buffer point and mark (Edebug)
986 Which buffer is current, and where point and mark are in the current
987 buffer are saved and restored.
990 @cindex window configuration (Edebug)
991 @findex save-excursion (Edebug)
992 @vindex edebug-save-windows
993 The Edebug Display Update, is saved and restored if
994 @code{edebug-save-windows} is non-@code{nil}. It is not restored on
995 error or quit, but the outside selected window @emph{is} reselected even
996 on error or quit in case a @code{save-excursion} is active.
997 If the value of @code{edebug-save-windows} is a list, only the listed
998 windows are saved and restored.
1000 The window start and horizontal scrolling of the source code buffer are
1001 not restored, however, so that the display remains coherent.
1004 @vindex edebug-save-displayed-buffer-points
1005 The value of point in each displayed buffer is saved and restored if
1006 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
1009 The variables @code{overlay-arrow-position} and
1010 @code{overlay-arrow-string} are saved and restored. So you can safely
1011 invoke Edebug from the recursive edit elsewhere in the same buffer.
1014 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
1015 the cursor shows up in the window.
1020 @node Edebug Recursive Edit
1021 @subsubsection Edebug Recursive Edit
1023 When Edebug is entered and actually reads commands from the user, it
1024 saves (and later restores) these additional data:
1028 The current match data, for whichever buffer was current.
1031 @code{last-command}, @code{this-command}, @code{last-command-char},
1032 @code{last-input-char}, @code{last-input-event},
1033 @code{last-command-event},
1034 @code{last-event-frame}, @code{last-nonmenu-event}, and
1035 @code{track-mouse} . Commands used within Edebug do not affect these
1036 variables outside of Edebug.
1038 The key sequence returned by @code{this-command-keys} is changed by
1039 executing commands within Edebug and there is no way to reset
1040 the key sequence from Lisp.
1042 For FSF Emacs 18, Edebug cannot save and restore the value of
1043 @code{unread-command-char}. Entering Edebug while this variable has
1044 a nontrivial value can interfere with execution of the program you are
1048 Complex commands executed while in Edebug are added to the variable
1049 @code{command-history}. In rare cases this can alter execution.
1052 Within Edebug, the recursion depth appears one deeper than the recursion
1053 depth outside Edebug. This is not true of the automatically updated
1054 evaluation list window.
1057 @code{standard-output} and @code{standard-input} are bound to @code{nil}
1058 by the @code{recursive-edit}, but Edebug temporarily restores them during
1062 The state of keyboard macro definition is saved and restored. While
1063 Edebug is active, @code{defining-kbd-macro} is bound to
1064 @code{edebug-continue-kbd-macro}.
1069 @node Instrumenting Macro Calls
1070 @subsection Instrumenting Macro Calls
1072 When Edebug instruments an expression that calls a Lisp macro, it needs
1073 additional advice to do the job properly. This is because there is no
1074 way to tell which subexpressions of the macro call may be evaluated.
1075 Evaluation may occur explicitly in the macro body, or when the
1076 resulting expansion is evaluated, or any time later. You must explain
1077 the format of macro call arguments by using @code{def-edebug-spec} to
1078 define an @dfn{Edebug specification} for each macro.
1080 @defmac def-edebug-spec macro specification
1081 Specify which expressions of a call to macro @var{macro} are forms to be
1082 evaluated. For simple macros, the @var{specification} often looks very
1083 similar to the formal argument list of the macro definition, but
1084 specifications are much more general than macro arguments.
1086 The @var{macro} argument may actually be any symbol, not just a macro
1089 Unless you are using SXEmacs, Emacs 19+ or XEmacs, this macro is only
1090 defined in Edebug, so you may want to use the following which is
1092 @code{(put '@var{macro} 'edebug-form-spec '@var{specification})}
1095 Here is a simple example that defines the specification for the
1096 @code{for} macro described in the SXEmacs Lisp Reference Manual,
1097 followed by an alternative, equivalent specification.
1100 (def-edebug-spec for
1101 (symbolp "from" form "to" form "do" &rest form))
1103 (def-edebug-spec for
1104 (symbolp ['from form] ['to form] ['do body]))
1107 Here is a table of the possibilities for @var{specification} and how each
1108 directs processing of arguments.
1113 All arguments are instrumented for evaluation.
1116 None of the arguments is instrumented.
1119 The symbol must have an Edebug specification which is used instead.
1120 This indirection is repeated until another kind of specification is
1121 found. This allows you to inherit the specification for another macro.
1124 The elements of the list describe the types of the arguments of a
1125 calling form. The possible elements of a specification list are
1126 described in the following sections.
1130 * Specification List:: How to specify complex patterns of evaluation.
1131 * Backtracking:: What Edebug does when matching fails.
1132 * Debugging Backquote:: Debugging Backquote
1133 * Specification Examples:: To help understand specifications.
1137 @node Specification List
1138 @subsubsection Specification List
1140 @cindex Edebug specification list
1141 A @dfn{specification list} is required for an Edebug specification if
1142 some arguments of a macro call are evaluated while others are not. Some
1143 elements in a specification list match one or more arguments, but others
1144 modify the processing of all following elements. The latter, called
1145 @dfn{keyword specifications}, are symbols beginning with @samp{@code{&}}
1146 (e.g. @code{&optional}).
1148 A specification list may contain sublists which match arguments that are
1149 themselves lists, or it may contain vectors used for grouping. Sublists
1150 and groups thus subdivide the specification list into a hierarchy of
1151 levels. Keyword specifications only apply to the remainder of the
1152 sublist or group they are contained in and there is an implicit grouping
1153 around a keyword specification and all following elements in the
1156 If a specification list fails
1157 at some level, then backtracking may be invoked to find some alternative
1158 at a higher level, or if no alternatives remain, an error will be
1159 signaled. See @ref{Backtracking} for more details.
1161 Edebug specifications provide at least the power of regular expression
1162 matching. Some context-free constructs are also supported: the matching
1163 of sublists with balanced parentheses, recursive processing of forms,
1164 and recursion via indirect specifications.
1166 Each element of a specification list may be one of the following, with
1167 the corresponding type of argument:
1172 A single unevaluated expression.
1175 A single evaluated expression, which is instrumented.
1178 @findex edebug-unwrap
1179 A place as in the Common Lisp @code{setf} place argument. It will be
1180 instrumented just like a form, but the macro is expected to strip the
1181 instrumentation. Two functions, @code{edebug-unwrap} and
1182 @code{edebug-unwrap*}, are provided to strip the instrumentation one
1183 level or recursively at all levels.
1186 Short for @code{&rest form}. See @code{&rest} below.
1189 A function form: either a quoted function symbol, a quoted lambda expression,
1190 or a form (that should evaluate to a function symbol or lambda
1191 expression). This is useful when function arguments might be quoted
1192 with @code{quote} rather than @code{function} since the body of a lambda
1193 expression will be instrumented either way.
1196 An unquoted anonymous lambda expression.
1199 @cindex &optional (Edebug)
1200 All following elements in the specification list are optional; as soon
1201 as one does not match, Edebug stops matching at this level.
1203 To make just a few elements optional followed by non-optional elements,
1204 use @code{[&optional @var{specs}@dots{}]}. To specify that several
1205 elements should all succeed together, use @code{&optional
1206 [@var{specs}@dots{}]}. See the @code{defun} example below.
1209 @cindex &rest (Edebug)
1210 All following elements in the specification list are repeated zero or
1211 more times. All the elements need not match in the last repetition,
1214 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
1215 To specify all elements must match on every repetition, use @code{&rest
1216 [@var{specs}@dots{}]}.
1219 @cindex &or (Edebug)
1220 Each of the following elements in the specification list is an
1221 alternative, processed left to right until one matches. One of the
1222 alternatives must match otherwise the @code{&or} specification fails.
1224 Each list element following @code{&or} is a single alternative even if
1225 it is a keyword specification. (This breaks the implicit grouping rule.)
1226 To group two or more list elements as a single alternative, enclose them
1227 in @code{[@dots{}]}.
1230 @cindex ¬ (Edebug)
1231 Each of the following elements is matched as alternatives as if by using
1232 @code{&or}, but if any of them match, the specification fails. If none
1233 of them match, nothing is matched, but the @code{¬} specification
1237 @cindex &define (Edebug)
1238 Indicates that the specification is for a defining form. The defining
1239 form itself is not instrumented (i.e. Edebug does not stop before and
1240 after the defining form), but forms inside it typically will be
1241 instrumented. The @code{&define} keyword should be the first element in
1242 a list specification.
1244 Additional specifications that may only appear after @code{&define} are
1245 described here. See the @code{defun} example below.
1250 The argument, a symbol, is the name of the defining form.
1251 But a defining form need not be named at all, in which
1252 case a unique name will be created for it.
1254 The @code{name} specification may be used more than once in the
1255 specification and each subsequent use will append the corresponding
1256 symbol argument to the previous name with @samp{@code{@@}} between them.
1257 This is useful for generating unique but meaningful names for
1258 definitions such as @code{defadvice} and @code{defmethod}.
1261 The element following @code{:name} should be a symbol; it is used as an
1262 additional name component for the definition. This is useful to add a
1263 unique, static component to the name of the definition. It may be used
1264 more than once. No argument is matched.
1267 The argument, a symbol, is the name of an argument of the defining form.
1268 However, lambda list keywords (symbols starting with @samp{@code{&}})
1269 are not allowed. See @code{lambda-list} and the example below.
1272 @cindex lambda-list (Edebug)
1273 This matches the whole argument list of an SXEmacs Lisp lambda
1274 expression, which is a list of symbols and the keywords
1275 @code{&optional} and @code{&rest}
1278 The argument is the body of code in a definition. This is like
1279 @code{body}, described above, but a definition body must be instrumented
1280 with a different Edebug call that looks up information associated with
1281 the definition. Use @code{def-body} for the highest level list of forms
1282 within the definition.
1285 The argument is a single, highest-level form in a definition. This is
1286 like @code{def-body}, except use this to match a single form rather than
1287 a list of forms. As a special case, @code{def-form} also means that
1288 tracing information is not output when the form is executed. See the
1289 @code{interactive} example below.
1294 This is successful when there are no more arguments to match at the
1295 current argument list level; otherwise it fails. See sublist
1296 specifications and the backquote example below.
1299 @cindex preventing backtracking
1300 No argument is matched but backtracking through the gate is disabled
1301 while matching the remainder of the specifications at this level. This
1302 is primarily used to generate more specific syntax error messages. See
1303 @ref{Backtracking} for more details. Also see the @code{let} example
1306 @item @var{other-symbol}
1307 @cindex indirect specifications
1308 Any other symbol in a specification list may be a predicate or an
1309 indirect specification.
1311 If the symbol has an Edebug specification, this @dfn{indirect
1312 specification} should be either a list specification that is used in
1313 place of the symbol, or a function that is called to process the
1314 arguments. The specification may be defined with @code{def-edebug-spec}
1315 just as for macros. See the @code{defun} example below.
1317 Otherwise, the symbol should be a predicate. The predicate is called
1318 with the argument and the specification fails if the predicate fails.
1319 The argument is not instrumented.
1322 @findex lambda-list-keywordp
1323 Predicates that may be used include: @code{symbolp}, @code{integerp},
1324 @code{stringp}, @code{vectorp}, @code{atom} (which matches a number,
1325 string, symbol, or vector), @code{keywordp}, and
1326 @code{lambda-list-keywordp}. The last two, defined in @file{edebug.el},
1327 test whether the argument is a symbol starting with @samp{@code{:}} and
1328 @samp{@code{&}} respectively.
1330 @item [@var{elements}@dots{}]
1331 @cindex [@dots{}] (Edebug)
1332 Rather than matching a vector argument, a vector treats
1333 the @var{elements} as a single @dfn{group specification}.
1335 @item "@var{string}"
1336 The argument should be a symbol named @var{string}. This specification
1337 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
1338 of @var{symbol} is the @var{string}, but the string form is preferred.
1340 @item '@var{symbol} @r{or} (quote @var{symbol})
1341 The argument should be the symbol @var{symbol}. But use a string
1342 specification instead.
1344 @item (vector @var{elements}@dots{})
1345 The argument should be a vector whose elements must match the
1346 @var{elements} in the specification. See the backquote example below.
1348 @item (@var{elements}@dots{})
1349 Any other list is a @dfn{sublist specification} and the argument must be
1350 a list whose elements match the specification @var{elements}.
1352 @cindex dotted lists (Edebug)
1353 A sublist specification may be a dotted list and the corresponding list
1354 argument may then be a dotted list. Alternatively, the last cdr of a
1355 dotted list specification may be another sublist specification (via a
1356 grouping or an indirect specification, e.g. @code{(spec . [(more
1357 specs@dots{})])}) whose elements match the non-dotted list arguments.
1358 This is useful in recursive specifications such as in the backquote
1359 example below. Also see the description of a @code{nil} specification
1360 above for terminating such recursion.
1362 Note that a sublist specification of the form @code{(specs . nil)}
1363 means the same as @code{(specs)}, and @code{(specs .
1364 (sublist-elements@dots{}))} means the same as @code{(specs
1365 sublist-elements@dots{})}.
1369 @c Need to document extensions with &symbol and :symbol
1373 @subsubsection Backtracking
1375 @cindex backtracking
1376 @cindex syntax error (Edebug)
1377 If a specification fails to match at some point, this does not
1378 necessarily mean a syntax error will be signaled; instead,
1379 @dfn{backtracking} will take place until all alternatives have been
1380 exhausted. Eventually every element of the argument list must be
1381 matched by some element in the specification, and every required element
1382 in the specification must match some argument.
1384 Backtracking is disabled for the remainder of a sublist or group when
1385 certain conditions occur, described below. Backtracking is reenabled
1386 when a new alternative is established by @code{&optional}, @code{&rest},
1387 or @code{&or}. It is also reenabled initially when processing a
1388 sublist or group specification or an indirect specification.
1390 You might want to disable backtracking to commit to some alternative so
1391 that Edebug can provide a more specific syntax error message. Normally,
1392 if no alternative matches, Edebug reports that none matched, but if one
1393 alternative is committed to, Edebug can report how it failed to match.
1395 First, backtracking is disabled while matching any of the form
1396 specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
1397 @code{def-body}). These specifications will match any form so any error
1398 must be in the form itself rather than at a higher level.
1400 Second, backtracking is disabled after successfully matching a quoted
1401 symbol or string specification, since this usually indicates a
1402 recognized construct. If you have a set of alternative constructs that
1403 all begin with the same symbol, you can usually work around this
1404 constraint by factoring the symbol out of the alternatives, e.g.,
1405 @code{["foo" &or [first case] [second case] ...]}.
1407 Third, backtracking may be explicitly disabled by using the
1408 @code{gate} specification. This is useful when you know that
1409 no higher alternatives may apply.
1412 @node Debugging Backquote
1413 @subsubsection Debugging Backquote
1416 @cindex backquote (Edebug)
1417 Backquote (@kbd{`}) is a macro that results in an expression that may or
1418 may not be evaluated. It is often used to simplify the definition of a
1419 macro to return an expression that is evaluated, but Edebug does not know
1420 when this is the case. However, the forms inside unquotes (@code{,} and
1421 @code{,@@}) are evaluated and Edebug instruments them.
1423 Nested backquotes are supported by Edebug, but there is a limit on the
1424 support of quotes inside of backquotes. Quoted forms (with @code{'})
1425 are not normally evaluated, but if the quoted form appears immediately
1426 within @code{,} and @code{,@@} forms, Edebug treats this as a backquoted
1427 form at the next higher level (even if there is not a next higher level
1428 - this is difficult to fix).
1431 If the backquoted forms happen to be code intended to be evaluated, you
1432 can have Edebug instrument them by using @code{edebug-`} instead of the
1433 regular @code{`}. Unquoted forms can always appear inside
1434 @code{edebug-`} anywhere a form is normally allowed. But @code{(,
1435 @var{form})} may be used in two other places specially recognized by
1436 Edebug: wherever a predicate specification would match, and at the head
1437 of a list form in place of a function name or lambda expression. The
1438 @var{form} inside a spliced unquote, @code{(,@@ @var{form})}, will be
1439 wrapped, but the unquote form itself will not be wrapped since this
1440 would interfere with the splicing.
1442 There is one other complication with using @code{edebug-`}. If the
1443 @code{edebug-`} call is in a macro and the macro may be called from code
1444 that is also instrumented, and if unquoted forms contain any macro
1445 arguments bound to instrumented forms, then you should modify the
1446 specification for the macro as follows: the specifications for those
1447 arguments must use @code{def-form} instead of @code{form}. (This is to
1448 reestablish the Edebugging context for those external forms.)
1450 For example, the @code{for} macro
1451 @c (@pxref{Problems with Macros}) @c in SXEmacs Lisp Reference Manual
1452 (@pxref{Problems with Macros,,,, SXEmacs Lisp Reference Manual}) @c Edebug Doc
1453 is shown here but with @code{edebug-`}
1454 substituted for regular @code{`}.
1458 (list 'setq var (list '1+ var)))
1460 (defmacro for (var from init to final do &rest body)
1461 (let ((tempvar (make-symbol "max")))
1462 (edebug-` (let (((, var) (, init))
1463 ((, tempvar) (, final)))
1464 (while (<= (, var) (, tempvar))
1469 Here is the corresponding modified Edebug specification and some code
1470 that calls the macro:
1473 (def-edebug-spec for
1474 (symbolp "from" def-form "to" def-form "do" &rest def-form))
1477 (for i from n to (* n (+ n 1)) do
1481 After instrumenting the @code{for} macro and the macro call, Edebug
1482 first steps to the beginning of the macro call, then into the macro
1483 body, then through each of the unquoted expressions in the backquote
1484 showing the expressions that will be embedded in the backquote form.
1485 Then when the macro expansion is evaluated, Edebug will step through the
1486 @code{let} form and each time it gets to an unquoted form, it will jump
1487 back to an argument of the macro call to step through that expression.
1488 Finally stepping will continue after the macro call. Even more
1489 convoluted execution paths may result when using anonymous functions.
1491 @vindex edebug-unwrap-results
1492 When the result of an expression is an instrumented expression, it is
1493 difficult to see the expression inside the instrumentation. So
1494 you may want to set the option @code{edebug-unwrap-results} to a
1495 non-@code{nil} value while debugging such expressions, but it would slow
1496 Edebug down to always do this.
1499 @node Specification Examples
1500 @subsubsection Specification Examples
1502 Here we provide several examples of Edebug specifications to show
1503 many of its capabilities.
1505 A @code{let} special form has a sequence of bindings and a body. Each
1506 of the bindings is either a symbol or a sublist with a symbol and
1507 optional value. In the specification below, notice the @code{gate}
1508 inside of the sublist to prevent backtracking.
1511 (def-edebug-spec let
1513 &or symbolp (gate symbolp &optional form))
1517 Edebug uses the following specifications for @code{defun} and
1518 @code{defmacro} and the associated argument list and @code{interactive}
1519 specifications. It is necessary to handle the expression argument of an
1520 interactive form specially since it is actually evaluated outside of the
1524 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec}
1525 (def-edebug-spec defun
1526 (&define name lambda-list
1527 [&optional stringp] ; @r{Match the doc string, if present.}
1528 [&optional ("interactive" interactive)]
1531 (def-edebug-spec lambda-list
1533 [&optional ["&optional" arg &rest arg]]
1534 &optional ["&rest" arg]
1537 (def-edebug-spec interactive
1538 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
1541 The specification for backquote below illustrates how to match
1542 dotted lists and use @code{nil} to terminate recursion. It also
1543 illustrates how components of a vector may be matched. (The actual
1544 specification provided by Edebug does not support dotted lists because
1545 doing so causes very deep recursion that could fail.)
1548 (def-edebug-spec ` (backquote-form)) ;; alias just for clarity
1550 (def-edebug-spec backquote-form
1551 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
1552 (backquote-form . [&or nil backquote-form])
1553 (vector &rest backquote-form)
1558 @node Edebug Options
1559 @subsection Edebug Options
1561 These options affect the behavior of Edebug:
1563 @defopt edebug-setup-hook
1564 Functions to call before Edebug is used. Each time it is set to a new
1565 value, Edebug will call those functions once and then
1566 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to
1567 load up Edebug specifications associated with a package you are using
1568 but only when you also use Edebug.
1569 See @ref{Instrumenting}.
1572 @defopt edebug-all-defs
1573 If non-@code{nil}, normal evaluation of any defining forms (e.g.
1574 @code{defun} and @code{defmacro}) will instrument them for Edebug. This
1575 applies to @code{eval-defun}, @code{eval-region}, and
1576 @code{eval-current-buffer}.
1578 Use the command @kbd{M-x edebug-all-defs} to toggle the value of
1579 this variable. You may want to make this variable local to each
1580 buffer by calling @code{(make-local-variable 'edebug-all-defs)} in your
1581 @code{emacs-lisp-mode-hook}.
1582 See @ref{Instrumenting}.
1585 @defopt edebug-all-forms
1586 If non-@code{nil}, normal evaluation of any forms by @code{eval-defun},
1587 @code{eval-region}, and @code{eval-current-buffer} will instrument them
1590 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
1592 See @ref{Instrumenting}.
1595 @defopt edebug-save-windows
1596 If non-@code{nil}, save and restore window configuration on Edebug
1597 calls. It takes some time to do this, so if your program does not care
1598 what happens to data about windows, you may want to set this variable to
1601 If the value is a list, only the listed windows are saved and
1604 @kbd{M-x edebug-toggle-save-windows} may be used to change this variable.
1605 This command is bound to @kbd{W} in source code buffers.
1606 See @ref{Edebug Display Update}.
1609 @defopt edebug-save-displayed-buffer-points
1610 If non-@code{nil}, save and restore point in all displayed buffers.
1611 This is necessary if you are debugging code that changes the point of a
1612 buffer which is displayed in a non-selected window. If Edebug or the
1613 user then selects the window, the buffer's point will be changed to the
1616 This is an expensive operation since it visits each window and therefore
1617 each displayed buffer twice for each Edebug activation, so it is best to
1618 avoid it if you can.
1619 See @ref{Edebug Display Update}.
1623 @defopt edebug-initial-mode
1624 If this variable is non-@code{nil}, it specifies the initial execution
1625 mode for Edebug when it is first activated. Possible values are
1626 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
1627 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
1629 The default value is @code{step}.
1630 See @ref{Edebug Execution Modes}.
1633 @defopt edebug-trace
1634 @findex edebug-print-trace-before
1635 @findex edebug-print-trace-after
1636 Non-@code{nil} means display a trace of function entry and exit.
1637 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
1638 function entry or exit per line, indented by the recursion level.
1640 The default value is @code{nil}.
1642 Also see @code{edebug-tracing}.
1646 @defopt edebug-test-coverage
1647 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
1648 This is done by comparing the result of each expression
1649 with the previous result. Coverage is considered OK if two different
1650 results are found. So to sufficiently test the coverage of your code,
1651 try to execute it under conditions that evaluate all expressions more
1652 than once, and produce different results for each expression.
1654 Use @kbd{M-x edebug-display-freq-count} to display the frequency count
1655 and coverage information for a definition.
1656 See @ref{Coverage Testing}.
1659 @defopt edebug-continue-kbd-macro
1660 If non-@code{nil}, continue defining or executing any keyboard macro
1661 that is executing outside of Edebug.
1663 Use this with caution since it is not debugged.
1664 See @ref{Edebug Execution Modes}.
1667 @defopt edebug-print-length
1668 If non-@code{nil}, bind @code{print-length} to this while printing
1669 results in Edebug. The default value is @code{50}.
1670 See @ref{Printing in Edebug}.
1673 @defopt edebug-print-level
1674 If non-@code{nil}, bind @code{print-level} to this while printing
1675 results in Edebug. The default value is @code{50}.
1678 @defopt edebug-print-circle
1679 If non-@code{nil}, bind @code{print-circle} to this while printing
1680 results in Edebug. The default value is @code{nil}.
1683 @defopt edebug-on-error
1684 @code{debug-on-error} is bound to this while Edebug is active.
1685 See @ref{Trapping Errors}.
1688 @defopt edebug-on-quit
1689 @code{debug-on-quit} is bound to this while Edebug is active.
1690 See @ref{Trapping Errors}.
1693 @defopt edebug-unwrap-results
1694 Non-@code{nil} if Edebug should unwrap results of expressions.
1695 This is useful when debugging macros where the results of expressions
1696 are instrumented expressions. But don't do this when results might be
1697 circular or an infinite loop will result.
1698 See @ref{Debugging Backquote}.
1701 @defopt edebug-global-break-condition
1702 If non-@code{nil}, an expression to test for at every stop point.
1703 If the result is non-@code{nil}, then break. Errors are ignored.
1704 See @ref{Global Break Condition}.