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