C-x 5 1
[emacs.git] / lispref / edebug.texi
blob7e1099be2364c339338abf5b148cc07a409e661e
1 @comment -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1992, 1993, 1994, 1998, 1999 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, Syntax Errors, Debugger, Debugging
13 @section Edebug
14 @cindex Edebug mode
16 @cindex Edebug
17   Edebug is a source-level debugger for Emacs Lisp programs with which
18 you can:
20 @itemize @bullet
21 @item
22 Step through evaluation, stopping before and after each expression.
24 @item
25 Set conditional or unconditional breakpoints.
27 @item
28 Stop when a specified condition is true (the global break event).
30 @item
31 Trace slow or fast, stopping briefly at each stop point, or
32 at each breakpoint.
34 @item
35 Display expression results and evaluate expressions as if outside of
36 Edebug.
38 @item 
39 Automatically re-evaluate a list of expressions and
40 display their results each time Edebug updates the display.
42 @item
43 Output trace info on function enter and exit.
45 @item
46 Stop when an error occurs.
48 @item
49 Display a backtrace, omitting Edebug's own frames.
51 @item
52 Specify argument evaluation for macros and defining forms.
54 @item
55 Obtain rudimentary coverage testing and frequency counts.
56 @end itemize
58 The first three sections below should tell you enough about Edebug to
59 enable you to use it.
61 @menu
62 * Using Edebug::                Introduction to use of Edebug.
63 * Instrumenting::               You must instrument your code
64                                   in order to debug it with Edebug.
65 * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
66 * Jumping::                     Commands to jump to a specified place.
67 * Misc: Edebug Misc.            Miscellaneous commands.
68 * Breakpoints::                 Setting breakpoints to make the program stop.
69 * Trapping Errors::             Trapping errors with Edebug.
70 * Views: Edebug Views.          Views inside and outside of Edebug.
71 * Eval: Edebug Eval.            Evaluating expressions within Edebug.
72 * Eval List::                   Expressions whose values are displayed
73                                   each time you enter Edebug.
74 * Printing in Edebug::          Customization of printing.
75 * Trace Buffer::                How to produce trace output in a buffer.
76 * Coverage Testing::            How to test evaluation coverage.
77 * The Outside Context::         Data that Edebug saves and restores.
78 * Instrumenting Macro Calls::   Specifying how to handle macro calls.
79 * Options: Edebug Options.      Option variables for customizing Edebug.
80 @end menu
82 @node Using Edebug
83 @subsection Using Edebug
85   To debug a Lisp program with Edebug, you must first @dfn{instrument}
86 the Lisp code that you want to debug.  A simple way to do this is to
87 first move point into the definition of a function or macro and then do
88 @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument).  See
89 @ref{Instrumenting}, for alternative ways to instrument code.
91   Once a function is instrumented, any call to the function activates
92 Edebug.  Depending on which Edebug execution mode you have selected,
93 activating Edebug may stop execution and let you step through the
94 function, or it may update the display and continue execution while
95 checking for debugging commands.  The default execution mode is step,
96 which stops execution.  @xref{Edebug Execution Modes}.
98   Within Edebug, you normally view an Emacs buffer showing the source of
99 the Lisp code you are debugging.  This is referred to as the @dfn{source
100 code buffer}, and it is temporarily read-only.
102   An arrow at the left margin indicates the line where the function is
103 executing.  Point initially shows where within the line the function is
104 executing, but this ceases to be true if you move point yourself.
106   If you instrument the definition of @code{fac} (shown below) and then
107 execute @code{(fac 3)}, here is what you would normally see.  Point is
108 at the open-parenthesis before @code{if}.
110 @example
111 (defun fac (n)
112 =>@point{}(if (< 0 n)
113       (* n (fac (1- n)))
114     1))
115 @end example
117 @cindex stop points
118 The places within a function where Edebug can stop execution are called
119 @dfn{stop points}.  These occur both before and after each subexpression
120 that is a list, and also after each variable reference.  
121 Here we use periods to show the stop points in the function
122 @code{fac}:
124 @example
125 (defun fac (n)
126   .(if .(< 0 n.).
127       .(* n. .(fac (1- n.).).).
128     1).)
129 @end example
131 The special commands of Edebug are available in the source code buffer
132 in addition to the commands of Emacs Lisp mode.  For example, you can
133 type the Edebug command @key{SPC} to execute until the next stop point.
134 If you type @key{SPC} once after entry to @code{fac}, here is the
135 display you will see:
137 @example
138 (defun fac (n)
139 =>(if @point{}(< 0 n)
140       (* n (fac (1- n)))
141     1))
142 @end example
144 When Edebug stops execution after an expression, it displays the
145 expression's value in the echo area. 
147 Other frequently used commands are @kbd{b} to set a breakpoint at a stop
148 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
149 exit Edebug and return to the top-level command loop.  Type @kbd{?} to
150 display a list of all Edebug commands.
152 @node Instrumenting
153 @subsection Instrumenting for Edebug
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   Once you have loaded Edebug, the command @kbd{C-M-x}
162 (@code{eval-defun}) is redefined so that when invoked with a prefix
163 argument on a definition, it instruments the definition before
164 evaluating it.  (The source code itself is not modified.)  If the
165 variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
166 meaning of the prefix argument: in this case, @kbd{C-M-x} instruments the
167 definition @emph{unless} it has a prefix argument.  The default value of
168 @code{edebug-all-defs} is @code{nil}.  The command @kbd{M-x
169 edebug-all-defs} toggles the value of the variable
170 @code{edebug-all-defs}.
172 @findex eval-region @r{(Edebug)}
173 @findex eval-current-buffer @r{(Edebug)}
174   If @code{edebug-all-defs} is non-@code{nil}, then the commands
175 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
176 also instrument any definitions they evaluate.  Similarly,
177 @code{edebug-all-forms} controls whether @code{eval-region} should
178 instrument @emph{any} form, even non-defining forms.  This doesn't apply
179 to loading or evaluations in the minibuffer.  The command @kbd{M-x
180 edebug-all-forms} toggles this option.
182 @findex edebug-eval-top-level-form
183   Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
184 instrument any top-level form regardless of the values of
185 @code{edebug-all-defs} and @code{edebug-all-forms}.
187   While Edebug is active, the command @kbd{I}
188 (@code{edebug-instrument-callee}) instruments the definition of the
189 function or macro called by the list form after point, if is not already
190 instrumented.  This is possible only if Edebug knows where to find the
191 source for that function; for this reading, after loading Edebug,
192 @code{eval-region} records the position of every definition it
193 evaluates, even if not instrumenting it.  See also the @kbd{i} command
194 (@pxref{Jumping}), which steps into the call after instrumenting the
195 function.
197 @cindex special forms (Edebug)
198 @cindex interactive commands (Edebug)
199 @cindex anonymous lambda expressions (Edebug)
200 @cindex Common Lisp (Edebug)
201 @pindex cl.el @r{(Edebug)}
202 @pindex cl-specs.el
203   Edebug knows how to instrument all the standard special forms,
204 @code{interactive} forms with an expression argument, anonymous lambda
205 expressions, and other defining forms.  However, Edebug cannot determine
206 on its own what a user-defined macro will do with the arguments of a
207 macro call, so you must provide that information; see @ref{Instrumenting
208 Macro Calls}, for details.
210   When Edebug is about to instrument code for the first time in a
211 session, it runs the hook @code{edebug-setup-hook}, then sets it to
212 @code{nil}.  You can use this to load Edebug specifications
213 (@pxref{Instrumenting Macro Calls}) associated with a package you are
214 using, but only when you use Edebug.
216 @findex eval-expression @r{(Edebug)}
217   To remove instrumentation from a definition, simply re-evaluate its
218 definition in a way that does not instrument.  There are two ways of
219 evaluating forms that never instrument them: from a file with
220 @code{load}, and from the minibuffer with @code{eval-expression}
221 (@kbd{M-:}).
223   If Edebug detects a syntax error while instrumenting, it leaves point
224 at the erroneous code and signals an @code{invalid-read-syntax} error.
226   @xref{Edebug Eval}, for other evaluation functions available
227 inside of Edebug.
229 @node Edebug Execution Modes
230 @subsection Edebug Execution Modes
232 @cindex Edebug execution modes
233 Edebug supports several execution modes for running the program you are
234 debugging.  We call these alternatives @dfn{Edebug execution modes}; do
235 not confuse them with major or minor modes.  The current Edebug execution mode
236 determines how far Edebug continues execution before stopping---whether
237 it stops at each stop point, or continues to the next breakpoint, for
238 example---and how much Edebug displays the progress of the evaluation
239 before it stops.
241 Normally, you specify the Edebug execution mode by typing a command to
242 continue the program in a certain mode.  Here is a table of these
243 commands; all except for @kbd{S} resume execution of the program, at
244 least for a certain distance.
246 @table @kbd
247 @item S
248 Stop: don't execute any more of the program, but wait for more
249 Edebug commands (@code{edebug-stop}).
251 @item @key{SPC}
252 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
254 @item n
255 Next: stop at the next stop point encountered after an expression
256 (@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
257 @ref{Edebug Misc}.
259 @item t
260 Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
262 @item T
263 Rapid trace: update the display at each stop point, but don't actually
264 pause (@code{edebug-Trace-fast-mode}).
266 @item g
267 Go: run until the next breakpoint (@code{edebug-go-mode}).  @xref{Breakpoints}.
269 @item c
270 Continue: pause one second at each breakpoint, and then continue
271 (@code{edebug-continue-mode}).
273 @item C
274 Rapid continue: move point to each breakpoint, but don't pause
275 (@code{edebug-Continue-fast-mode}).
277 @item G
278 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}).  You
279 can still stop the program by typing @kbd{S}, or any editing command.
280 @end table
282 In general, the execution modes earlier in the above list run the
283 program more slowly or stop sooner than the modes later in the list.
285 While executing or tracing, you can interrupt the execution by typing
286 any Edebug command.  Edebug stops the program at the next stop point and
287 then executes the command you typed.  For example, typing @kbd{t} during
288 execution switches to trace mode at the next stop point.  You can use
289 @kbd{S} to stop execution without doing anything else.
291 If your function happens to read input, a character you type intending
292 to interrupt execution may be read by the function instead.  You can
293 avoid such unintended results by paying attention to when your program
294 wants input.
296 @cindex keyboard macros (Edebug)
297 Keyboard macros containing the commands in this section do not
298 completely work: exiting from Edebug, to resume the program, loses track
299 of the keyboard macro.  This is not easy to fix.  Also, defining or
300 executing a keyboard macro outside of Edebug does not affect commands
301 inside Edebug.  This is usually an advantage.  See also the
302 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
304 When you enter a new Edebug level, the initial execution mode comes from
305 the value of the variable @code{edebug-initial-mode}.  By default, this
306 specifies step mode.  Note that you may reenter the same Edebug level
307 several times if, for example, an instrumented function is called
308 several times from one command.
311 @node Jumping
312 @subsection Jumping
314   The commands described in this section execute until they reach a
315 specified location.  All except @kbd{i} make a temporary breakpoint to
316 establish the place to stop, then switch to go mode.  Any other
317 breakpoint reached before the intended stop point will also stop
318 execution.  @xref{Breakpoints}, for the details on breakpoints.
320   These commands may fail to work as expected in case of nonlocal exit,
321 as that can bypass the temporary breakpoint where you expected the
322 program to stop.
324 @table @kbd
325 @item h
326 Proceed to the stop point near where point is (@code{edebug-goto-here}).
328 @item f
329 Run the program forward over one expression
330 (@code{edebug-forward-sexp}).
332 @item o
333 Run the program until the end of the containing sexp.
335 @item i
336 Step into the function or macro called by the form after point.
337 @end table
339 The @kbd{h} command proceeds to the stop point near the current location
340 of point, using a temporary breakpoint.  See @ref{Breakpoints}, for more
341 information about breakpoints.
343 The @kbd{f} command runs the program forward over one expression.  More
344 precisely, it sets a temporary breakpoint at the position that
345 @kbd{C-M-f} would reach, then executes in go mode so that the program
346 will stop at breakpoints.
348 With a prefix argument @var{n}, the temporary breakpoint is placed
349 @var{n} sexps beyond point.  If the containing list ends before @var{n}
350 more elements, then the place to stop is after the containing
351 expression.
353 You must check that the position @kbd{C-M-f} finds is a place that the
354 program will really get to.  In @code{cond}, for example, this may not
355 be true.
357 For flexibility, the @kbd{f} command does @code{forward-sexp} starting
358 at point, rather than at the stop point.  If you want to execute one
359 expression @emph{from the current stop point}, first type @kbd{w}, to
360 move point there, and then type @kbd{f}.
362 The @kbd{o} command continues ``out of'' an expression.  It places a
363 temporary breakpoint at the end of the sexp containing point.  If the
364 containing sexp is a function definition itself, @kbd{o} continues until
365 just before the last sexp in the definition.  If that is where you are
366 now, it returns from the function and then stops.  In other words, this
367 command does not exit the currently executing function unless you are
368 positioned after the last sexp.
370 The @kbd{i} command steps into the function or macro called by the list
371 form after point, and stops at its first stop point.  Note that the form
372 need not be the one about to be evaluated.  But if the form is a
373 function call about to be evaluated, remember to use this command before
374 any of the arguments are evaluated, since otherwise it will be too late.
376 The @kbd{i} command instruments the function or macro it's supposed to
377 step into, if it isn't instrumented already.  This is convenient, but keep
378 in mind that the function or macro remains instrumented unless you explicitly
379 arrange to deinstrument it.
381 @node Edebug Misc
382 @subsection Miscellaneous Edebug Commands
384   Some miscellaneous Edebug commands are described here.
386 @table @kbd
387 @item ?
388 Display the help message for Edebug (@code{edebug-help}).
390 @item C-]
391 Abort one level back to the previous command level
392 (@code{abort-recursive-edit}).
394 @item q
395 Return to the top level editor command loop (@code{top-level}).  This
396 exits all recursive editing levels, including all levels of Edebug
397 activity.  However, instrumented code protected with
398 @code{unwind-protect} or @code{condition-case} forms may resume
399 debugging.
401 @item Q
402 Like @kbd{q}, but don't stop even for protected code
403 (@code{top-level-nonstop}).
405 @item r
406 Redisplay the most recently known expression result in the echo area
407 (@code{edebug-previous-result}).
409 @item d
410 Display a backtrace, excluding Edebug's own functions for clarity
411 (@code{edebug-backtrace}).
413 You cannot use debugger commands in the backtrace buffer in Edebug as
414 you would in the standard debugger.
416 The backtrace buffer is killed automatically when you continue
417 execution.
418 @end table
420 You can invoke commands from Edebug that activate Edebug again
421 recursively.  Whenever Edebug is active, you can quit to the top level
422 with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
423 display a backtrace of all the pending evaluations with @kbd{d}.
425 @node Breakpoints
426 @subsection Breakpoints
428 @cindex breakpoints
429 Edebug's step mode stops execution when the next stop point is reached.
430 There are three other ways to stop Edebug execution once it has started:
431 breakpoints, the global break condition, and source breakpoints.
433 While using Edebug, you can specify @dfn{breakpoints} in the program you
434 are testing: these are places where execution should stop.  You can set a
435 breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
436 setting and unsetting breakpoints, the stop point that is affected is
437 the first one at or after point in the source code buffer.  Here are the
438 Edebug commands for breakpoints:
440 @table @kbd
441 @item b
442 Set a breakpoint at the stop point at or after point
443 (@code{edebug-set-breakpoint}).  If you use a prefix argument, the
444 breakpoint is temporary---it turns off the first time it stops the
445 program.
447 @item u
448 Unset the breakpoint (if any) at the stop point at or after 
449 point (@code{edebug-unset-breakpoint}).
451 @item x @var{condition} @key{RET}
452 Set a conditional breakpoint which stops the program only if
453 @var{condition} evaluates to a non-@code{nil} value
454 (@code{edebug-set-conditional-breakpoint}).  With a prefix argument, the
455 breakpoint is temporary.
457 @item B
458 Move point to the next breakpoint in the current definition
459 (@code{edebug-next-breakpoint}).
460 @end table
462 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
463 with @kbd{u}.  First move point to the Edebug stop point of your choice,
464 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
465 Unsetting a breakpoint where none has been set has no effect.
467 Re-evaluating or reinstrumenting a definition removes all of its
468 previous breakpoints.
470 A @dfn{conditional breakpoint} tests a condition each time the program
471 gets there.  Any errors that occur as a result of evaluating the
472 condition are ignored, as if the result were @code{nil}.  To set a
473 conditional breakpoint, use @kbd{x}, and specify the condition
474 expression in the minibuffer.  Setting a conditional breakpoint at a
475 stop point that has a previously established conditional breakpoint puts
476 the previous condition expression in the minibuffer so you can edit it.
478 You can make a conditional or unconditional breakpoint
479 @dfn{temporary} by using a prefix argument with the command to set the
480 breakpoint.  When a temporary breakpoint stops the program, it is
481 automatically unset.
483 Edebug always stops or pauses at a breakpoint, except when the Edebug
484 mode is Go-nonstop.  In that mode, it ignores breakpoints entirely.
486 To find out where your breakpoints are, use the @kbd{B} command, which
487 moves point to the next breakpoint following point, within the same
488 function, or to the first breakpoint if there are no following
489 breakpoints.  This command does not continue execution---it just moves
490 point in the buffer.
492 @menu
493 * Global Break Condition::      Breaking on an event. 
494 * Source Breakpoints::          Embedding breakpoints in source code.
495 @end menu
498 @node Global Break Condition
499 @subsubsection Global Break Condition
501 @cindex stopping on events
502 @cindex global break condition
503   A @dfn{global break condition} stops execution when a specified
504 condition is satisfied, no matter where that may occur.  Edebug
505 evaluates the global break condition at every stop point; if it
506 evaluates to a non-@code{nil} value, then execution stops or pauses
507 depending on the execution mode, as if a breakpoint had been hit.  If
508 evaluating the condition gets an error, execution does not stop.
510 @findex edebug-set-global-break-condition
511   The condition expression is stored in
512 @code{edebug-global-break-condition}.  You can specify a new expression
513 using the @kbd{X} command (@code{edebug-set-global-break-condition}).
515   The global break condition is the simplest way to find where in your
516 code some event occurs, but it makes code run much more slowly.  So you
517 should reset the condition to @code{nil} when not using it.
519 @node Source Breakpoints
520 @subsubsection Source Breakpoints
522 @findex edebug
523 @cindex source breakpoints
524   All breakpoints in a definition are forgotten each time you
525 reinstrument it.  If you wish to make a breakpoint that won't be
526 forgotten, you can write a @dfn{source breakpoint}, which is simply a
527 call to the function @code{edebug} in your source code.  You can, of
528 course, make such a call conditional.  For example, in the @code{fac}
529 function, you can insert the first line as shown below, to stop when the
530 argument reaches zero:
532 @example
533 (defun fac (n)
534   (if (= n 0) (edebug))
535   (if (< 0 n)
536       (* n (fac (1- n)))
537     1))
538 @end example
540   When the @code{fac} definition is instrumented and the function is
541 called, the call to @code{edebug} acts as a breakpoint.  Depending on
542 the execution mode, Edebug stops or pauses there.
544   If no instrumented code is being executed when @code{edebug} is called,
545 that function calls @code{debug}.
546 @c This may not be a good idea anymore.
548 @node Trapping Errors
549 @subsection Trapping Errors
551   Emacs normally displays an error message when an error is signaled and
552 not handled with @code{condition-case}.  While Edebug is active and
553 executing instrumented code, it normally responds to all unhandled
554 errors.  You can customize this with the options @code{edebug-on-error}
555 and @code{edebug-on-quit}; see @ref{Edebug Options}.
557   When Edebug responds to an error, it shows the last stop point
558 encountered before the error.  This may be the location of a call to a
559 function which was not instrumented, and within which the error actually
560 occurred.  For an unbound variable error, the last known stop point
561 might be quite distant from the offending variable reference.  In that
562 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
564 @c Edebug should be changed for the following: -- dan
565   If you change @code{debug-on-error} or @code{debug-on-quit} while
566 Edebug is active, these changes will be forgotten when Edebug becomes
567 inactive.  Furthermore, during Edebug's recursive edit, these variables
568 are bound to the values they had outside of Edebug.
570 @node Edebug Views
571 @subsection Edebug Views
573   These Edebug commands let you view aspects of the buffer and window
574 status as they were before entry to Edebug.  The outside window
575 configuration is the collection of windows and contents that were in
576 effect outside of Edebug.
578 @table @kbd
579 @item v
580 Temporarily view the outside window configuration
581 (@code{edebug-view-outside}).
583 @item p
584 Temporarily display the outside current buffer with point at its outside
585 position (@code{edebug-bounce-point}).  With a prefix argument @var{n},
586 pause for @var{n} seconds instead.
588 @item w
589 Move point back to the current stop point in the source code buffer
590 (@code{edebug-where}).
592 If you use this command in a different window displaying the same
593 buffer, that window will be used instead to display the current
594 definition in the future.
596 @item W
597 @c Its function is not simply to forget the saved configuration -- dan
598 Toggle whether Edebug saves and restores the outside window
599 configuration (@code{edebug-toggle-save-windows}).
601 With a prefix argument, @code{W} only toggles saving and restoring of
602 the selected window.  To specify a window that is not displaying the
603 source code buffer, you must use @kbd{C-x X W} from the global keymap.
604 @end table
606   You can view the outside window configuration with @kbd{v} or just
607 bounce to the point in the current buffer with @kbd{p}, even if
608 it is not normally displayed.  After moving point, you may wish to jump
609 back to the stop point with @kbd{w} from a source code buffer.
611   Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
612 saved outside window configuration---so that even if you turn saving
613 back @emph{on}, the current window configuration remains unchanged when
614 you next exit Edebug (by continuing the program).  However, the
615 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
616 conflict with the buffers you wish to see unless you have enough windows
617 open.
619 @node Edebug Eval
620 @subsection Evaluation
622   While within Edebug, you can evaluate expressions ``as if'' Edebug
623 were not running.  Edebug tries to be invisible to the expression's
624 evaluation and printing.  Evaluation of expressions that cause side
625 effects will work as expected, except for changes to data that Edebug
626 explicitly saves and restores.  @xref{The Outside Context}, for details
627 on this process.
629 @table @kbd
630 @item e @var{exp} @key{RET}
631 Evaluate expression @var{exp} in the context outside of Edebug
632 (@code{edebug-eval-expression}).  That is, Edebug tries to minimize its
633 interference with the evaluation.
635 @item M-: @var{exp} @key{RET}
636 Evaluate expression @var{exp} in the context of Edebug itself.
638 @item C-x C-e
639 Evaluate the expression before point, in the context outside of Edebug
640 (@code{edebug-eval-last-sexp}).
641 @end table
643 @cindex lexical binding (Edebug)
644   Edebug supports evaluation of expressions containing references to
645 lexically bound symbols created by the following constructs in
646 @file{cl.el} (version 2.03 or later): @code{lexical-let},
647 @code{macrolet}, and @code{symbol-macrolet}.
649 @node Eval List
650 @subsection Evaluation List Buffer
652   You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
653 evaluate expressions interactively.  You can also set up the
654 @dfn{evaluation list} of expressions to be evaluated automatically each
655 time Edebug updates the display.
657 @table @kbd
658 @item E
659 Switch to the evaluation list buffer @samp{*edebug*}
660 (@code{edebug-visit-eval-list}).
661 @end table
663   In the @samp{*edebug*} buffer you can use the commands of Lisp
664 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
665 Manual}) as well as these special commands:
667 @table @kbd
668 @item C-j
669 Evaluate the expression before point, in the outside context, and insert
670 the value in the buffer (@code{edebug-eval-print-last-sexp}).
672 @item C-x C-e
673 Evaluate the expression before point, in the context outside of Edebug
674 (@code{edebug-eval-last-sexp}).
676 @item C-c C-u
677 Build a new evaluation list from the contents of the buffer
678 (@code{edebug-update-eval-list}).
680 @item C-c C-d
681 Delete the evaluation list group that point is in
682 (@code{edebug-delete-eval-item}).
684 @item C-c C-w
685 Switch back to the source code buffer at the current stop point
686 (@code{edebug-where}).
687 @end table
689   You can evaluate expressions in the evaluation list window with
690 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
691 but they are evaluated in the context outside of Edebug.
693   The expressions you enter interactively (and their results) are lost
694 when you continue execution; but you can set up an @dfn{evaluation list}
695 consisting of expressions to be evaluated each time execution stops. 
697 @cindex evaluation list group
698   To do this, write one or more @dfn{evaluation list groups} in the
699 evaluation list buffer.  An evaluation list group consists of one or
700 more Lisp expressions.  Groups are separated by comment lines.
702   The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
703 evaluation list, scanning the buffer and using the first expression of
704 each group.  (The idea is that the second expression of the group is the
705 value previously computed and displayed.)
707   Each entry to Edebug redisplays the evaluation list by inserting each
708 expression in the buffer, followed by its current value.  It also
709 inserts comment lines so that each expression becomes its own group.
710 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
711 the evaluation list is effectively unchanged.
713   If an error occurs during an evaluation from the evaluation list, the
714 error message is displayed in a string as if it were the result.
715 Therefore, expressions that use variables not currently valid do not
716 interrupt your debugging.
718   Here is an example of what the evaluation list window looks like after
719 several expressions have been added to it:
721 @smallexample
722 (current-buffer)
723 #<buffer *scratch*>
724 ;---------------------------------------------------------------
725 (selected-window)
726 #<window 16 on *scratch*>
727 ;---------------------------------------------------------------
728 (point)
730 ;---------------------------------------------------------------
731 bad-var
732 "Symbol's value as variable is void: bad-var"
733 ;---------------------------------------------------------------
734 (recursion-depth)
736 ;---------------------------------------------------------------
737 this-command
738 eval-last-sexp
739 ;---------------------------------------------------------------
740 @end smallexample
742 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
743 delete the text for the group and update the evaluation list with
744 @kbd{C-c C-u}.  To add a new expression to the evaluation list, insert
745 the expression at a suitable place, insert a new comment line, then type
746 @kbd{C-c C-u}.  You need not insert dashes in the comment line---its
747 contents don't matter.
749 After selecting @samp{*edebug*}, you can return to the source code
750 buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
751 you continue execution, and recreated next time it is needed.
753 @node Printing in Edebug
754 @subsection Printing in Edebug
756 @cindex printing (Edebug)
757 @cindex printing circular structures
758 @pindex cust-print
759   If an expression in your program produces a value containing circular
760 list structure, you may get an error when Edebug attempts to print it.
762   One way to cope with circular structure is to set @code{print-length}
763 or @code{print-level} to truncate the printing.  Edebug does this for
764 you; it binds @code{print-length} and @code{print-level} to 50 if they
765 were @code{nil}.  (Actually, the variables @code{edebug-print-length}
766 and @code{edebug-print-level} specify the values to use within Edebug.)
767 @xref{Output Variables}.
769 @defopt edebug-print-length
770 If non-@code{nil}, Edebug binds @code{print-length} to this value while
771 printing results.  The default value is @code{50}.
772 @end defopt
774 @defopt edebug-print-level 
775 If non-@code{nil}, Edebug binds @code{print-level} to this value while
776 printing results.  The default value is @code{50}.
777 @end defopt
779   You can also print circular structures and structures that share
780 elements more informatively by binding @code{print-circle}
781 to a non-@code{nil} value.
783   Here is an example of code that creates a circular structure:
785 @example
786 (setq a '(x y))
787 (setcar a a)
788 @end example
790 @noindent
791 Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
792 @samp{#1=} notation labels the structure that follows it with the label
793 @samp{1}, and the @samp{#1#} notation references the previously labeled
794 structure.  This notation is used for any shared elements of lists or
795 vectors.
797 @defopt edebug-print-circle 
798 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
799 printing results.  The default value is @code{nil}.
800 @end defopt
802   Other programs can also use custom printing; see @file{cust-print.el}
803 for details.
805 @node Trace Buffer
806 @subsection Trace Buffer
807 @cindex trace buffer
809   Edebug can record an execution trace, storing it in a buffer named
810 @samp{*edebug-trace*}.  This is a log of function calls and returns,
811 showing the function names and their arguments and values.  To enable
812 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
814   Making a trace buffer is not the same thing as using trace execution
815 mode (@pxref{Edebug Execution Modes}).
817   When trace recording is enabled, each function entry and exit adds
818 lines to the trace buffer.  A function entry record consists of
819 @samp{::::@{}, followed by the function name and argument values.  A
820 function exit record consists of @samp{::::@}}, followed by the function
821 name and result of the function.
823   The number of @samp{:}s in an entry shows its recursion depth.  You
824 can use the braces in the trace buffer to find the matching beginning or
825 end of function calls.
827 @findex edebug-print-trace-before
828 @findex edebug-print-trace-after
829   You can customize trace recording for function entry and exit by
830 redefining the functions @code{edebug-print-trace-before} and
831 @code{edebug-print-trace-after}.
833 @defmac edebug-tracing string body@dots{}
834 This macro requests additional trace information around the execution
835 of the @var{body} forms.  The argument @var{string} specifies text
836 to put in the trace buffer.  All the arguments are evaluated, and
837 @code{edebug-tracing} returns the value of the last form in @var{body}.
838 @end defmac
840 @defun edebug-trace format-string &rest format-args
841 This function inserts text in the trace buffer.  It computes the text
842 with @code{(apply 'format @var{format-string} @var{format-args})}.
843 It also appends a newline to separate entries.
844 @end defun
846   @code{edebug-tracing} and @code{edebug-trace} insert lines in the
847 trace buffer whenever they are called, even if Edebug is not active.
848 Adding text to the trace buffer also scrolls its window to show the last
849 lines inserted.
851 @node Coverage Testing
852 @subsection Coverage Testing
854 @cindex coverage testing
855 @cindex frequency counts
856 @cindex performance analysis
857 Edebug provides rudimentary coverage testing and display of execution
858 frequency.
860   Coverage testing works by comparing the result of each expression with
861 the previous result; each form in the program is considered ``covered''
862 if it has returned two different values since you began testing coverage
863 in the current Emacs session.  Thus, to do coverage testing on your
864 program, execute it under various conditions and note whether it behaves
865 correctly; Edebug will tell you when you have tried enough different
866 conditions that each form has returned two different values.
868   Coverage testing makes execution slower, so it is only done if
869 @code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
870 performed for all execution of an instrumented function, even if the
871 execution mode is Go-nonstop, and regardless of whether coverage testing
872 is enabled.
874   Use @kbd{M-x edebug-display-freq-count} to display both the
875 coverage information and the frequency counts for a definition.
877 @deffn Command edebug-display-freq-count
878 This command displays the frequency count data for each line of the
879 current definition.
881 The frequency counts appear as comment lines after each line of code,
882 and you can undo all insertions with one @code{undo} command.  The
883 counts appear under the @samp{(} before an expression or the @samp{)}
884 after an expression, or on the last character of a variable.  To
885 simplify the display, a count is not shown if it is equal to the
886 count of an earlier expression on the same line.
888 The character @samp{=} following the count for an expression says that
889 the expression has returned the same value each time it was evaluated.
890 In other words, it is not yet ``covered'' for coverage testing purposes.
892 To clear the frequency count and coverage data for a definition,
893 simply reinstrument it with @code{eval-defun}.
894 @end deffn
896 For example, after evaluating @code{(fac 5)} with a source
897 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
898 the breakpoint is reached, the frequency data looks like this:
900 @example
901 (defun fac (n)
902   (if (= n 0) (edebug))
903 ;#6           1      0 =5 
904   (if (< 0 n)
905 ;#5         = 
906       (* n (fac (1- n)))
907 ;#    5               0  
908     1))
909 ;#   0 
910 @end example
912 The comment lines show that @code{fac} was called 6 times.  The
913 first @code{if} statement returned 5 times with the same result each
914 time; the same is true of the condition on the second @code{if}.
915 The recursive call of @code{fac} did not return at all.
918 @node The Outside Context
919 @subsection The Outside Context
921 Edebug tries to be transparent to the program you are debugging, but it
922 does not succeed completely.  Edebug also tries to be transparent when
923 you evaluate expressions with @kbd{e} or with the evaluation list
924 buffer, by temporarily restoring the outside context.  This section
925 explains precisely what context Edebug restores, and how Edebug fails to
926 be completely transparent.
928 @menu
929 * Checking Whether to Stop::    When Edebug decides what to do.
930 * Edebug Display Update::       When Edebug updates the display.
931 * Edebug Recursive Edit::       When Edebug stops execution.
932 @end menu
934 @node Checking Whether to Stop
935 @subsubsection Checking Whether to Stop
937 Whenever Edebug is entered, it needs to save and restore certain data
938 before even deciding whether to make trace information or stop the
939 program.
941 @itemize @bullet
942 @item 
943 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
944 incremented once to reduce Edebug's impact on the stack.  You could,
945 however, still run out of stack space when using Edebug.
947 @item 
948 The state of keyboard macro execution is saved and restored.  While
949 Edebug is active, @code{executing-macro} is bound to
950 @code{edebug-continue-kbd-macro}.
952 @end itemize
955 @node Edebug Display Update
956 @subsubsection Edebug Display Update
958 @c This paragraph is not filled, because LaLiberte's conversion script
959 @c needs an xref to be on just one line.
960 When Edebug needs to display something (e.g., in trace mode), it saves
961 the current window configuration from ``outside'' Edebug 
962 (@pxref{Window Configurations}).  When you exit Edebug (by continuing
963 the program), it restores the previous window configuration.
965 Emacs redisplays only when it pauses.  Usually, when you continue
966 execution, the program re-enters Edebug at a breakpoint or after
967 stepping, without pausing or reading input in between.  In such cases,
968 Emacs never gets a chance to redisplay the ``outside'' configuration.
969 Consequently, what you see is the same window configuration as the last
970 time Edebug was active, with no interruption.
972 Entry to Edebug for displaying something also saves and restores the
973 following data (though some of them are deliberately not restored if an
974 error or quit signal occurs).
976 @itemize @bullet
977 @item 
978 @cindex current buffer point and mark (Edebug)
979 Which buffer is current, and the positions of point and the mark in the
980 current buffer, are saved and restored.
982 @item 
983 @cindex window configuration (Edebug)
984 The outside window configuration is saved and restored if
985 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}).
987 The window configuration is not restored on error or quit, but the
988 outside selected window @emph{is} reselected even on error or quit in
989 case a @code{save-excursion} is active.  If the value of
990 @code{edebug-save-windows} is a list, only the listed windows are saved
991 and restored.
993 The window start and horizontal scrolling of the source code buffer are
994 not restored, however, so that the display remains coherent within Edebug.
996 @item
997 The value of point in each displayed buffer is saved and restored if
998 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
1000 @item
1001 The variables @code{overlay-arrow-position} and
1002 @code{overlay-arrow-string} are saved and restored.  So you can safely
1003 invoke Edebug from the recursive edit elsewhere in the same buffer.
1005 @item 
1006 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
1007 the cursor shows up in the window.
1008 @end itemize
1010 @node Edebug Recursive Edit
1011 @subsubsection Edebug Recursive Edit
1013 When Edebug is entered and actually reads commands from the user, it
1014 saves (and later restores) these additional data:
1016 @itemize @bullet
1017 @item
1018 The current match data.  @xref{Match Data}.
1020 @item
1021 @code{last-command}, @code{this-command}, @code{last-command-char},
1022 @code{last-input-char}, @code{last-input-event},
1023 @code{last-command-event}, @code{last-event-frame},
1024 @code{last-nonmenu-event}, and @code{track-mouse}.  Commands used within
1025 Edebug do not affect these variables outside of Edebug.
1027 The key sequence returned by @code{this-command-keys} is changed by
1028 executing commands within Edebug and there is no way to reset
1029 the key sequence from Lisp.
1031 Edebug cannot save and restore the value of
1032 @code{unread-command-events}.  Entering Edebug while this variable has a
1033 nontrivial value can interfere with execution of the program you are
1034 debugging.
1036 @item
1037 Complex commands executed while in Edebug are added to the variable
1038 @code{command-history}.  In rare cases this can alter execution.
1040 @item
1041 Within Edebug, the recursion depth appears one deeper than the recursion
1042 depth outside Edebug.  This is not true of the automatically updated
1043 evaluation list window.
1045 @item
1046 @code{standard-output} and @code{standard-input} are bound to @code{nil}
1047 by the @code{recursive-edit}, but Edebug temporarily restores them during
1048 evaluations.
1050 @item 
1051 The state of keyboard macro definition is saved and restored.  While
1052 Edebug is active, @code{defining-kbd-macro} is bound to
1053 @code{edebug-continue-kbd-macro}.
1054 @end itemize
1056 @node Instrumenting Macro Calls
1057 @subsection Instrumenting Macro Calls
1059   When Edebug instruments an expression that calls a Lisp macro, it needs
1060 additional information about the macro to do the job properly.  This is
1061 because there is no a-priori way to tell which subexpressions of the
1062 macro call are forms to be evaluated.  (Evaluation may occur explicitly
1063 in the macro body, or when the resulting expansion is evaluated, or any
1064 time later.)
1066   Therefore, you must define an Edebug specification for each macro that
1067 Edebug will encounter, to explain the format of calls to that macro.  To
1068 do this, use @code{def-edebug-spec}.
1070 @deffn Macro def-edebug-spec macro specification
1071 Specify which expressions of a call to macro @var{macro} are forms to be
1072 evaluated.  For simple macros, the @var{specification} often looks very
1073 similar to the formal argument list of the macro definition, but
1074 specifications are much more general than macro arguments.
1076 The @var{macro} argument can actually be any symbol, not just a macro
1077 name.
1078 @end deffn
1080 Here is a simple example that defines the specification for the
1081 @code{for} example macro (@pxref{Argument Evaluation}), followed by an
1082 alternative, equivalent specification.
1084 @example
1085 (def-edebug-spec for
1086   (symbolp "from" form "to" form "do" &rest form))
1088 (def-edebug-spec for
1089   (symbolp ['from form] ['to form] ['do body]))
1090 @end example
1092 Here is a table of the possibilities for @var{specification} and how each
1093 directs processing of arguments.
1095 @table @asis
1096 @item @code{t}
1097 All arguments are instrumented for evaluation.
1099 @item @code{0}
1100 None of the arguments is instrumented.
1102 @item a symbol
1103 The symbol must have an Edebug specification which is used instead.
1104 This indirection is repeated until another kind of specification is
1105 found.  This allows you to inherit the specification from another macro.
1107 @item a list
1108 The elements of the list describe the types of the arguments of a
1109 calling form.  The possible elements of a specification list are
1110 described in the following sections.
1111 @end table
1113 @menu
1114 * Specification List::          How to specify complex patterns of evaluation.
1115 * Backtracking::                What Edebug does when matching fails.
1116 * Specification Examples::      To help understand specifications.
1117 @end menu
1120 @node Specification List
1121 @subsubsection Specification List
1123 @cindex Edebug specification list
1124 A @dfn{specification list} is required for an Edebug specification if
1125 some arguments of a macro call are evaluated while others are not.  Some
1126 elements in a specification list match one or more arguments, but others
1127 modify the processing of all following elements.  The latter, called
1128 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
1129 as @code{&optional}).
1131 A specification list may contain sublists which match arguments that are
1132 themselves lists, or it may contain vectors used for grouping.  Sublists
1133 and groups thus subdivide the specification list into a hierarchy of
1134 levels.  Specification keywords apply only to the remainder of the
1135 sublist or group they are contained in.
1137 When a specification list involves alternatives or repetition, matching
1138 it against an actual macro call may require backtracking.
1139 @xref{Backtracking}, for more details.
1141 Edebug specifications provide the power of regular expression matching,
1142 plus some context-free grammar constructs: the matching of sublists with
1143 balanced parentheses, recursive processing of forms, and recursion via
1144 indirect specifications.
1146 Here's a table of the possible elements of a specification list, with
1147 their meanings:
1149 @table @code
1150 @item sexp
1151 A single unevaluated Lisp object, which is not instrumented.
1152 @c an "expression" is not necessarily intended for evaluation.
1154 @item form
1155 A single evaluated expression, which is instrumented.
1157 @item place
1158 @findex edebug-unwrap
1159 A place to store a value, as in the Common Lisp @code{setf} construct.
1161 @item body
1162 Short for @code{&rest form}.  See @code{&rest} below.
1164 @item function-form
1165 A function form: either a quoted function symbol, a quoted lambda
1166 expression, or a form (that should evaluate to a function symbol or
1167 lambda expression).  This is useful when an argument that's a lambda
1168 expression might be quoted with @code{quote} rather than
1169 @code{function}, since it instruments the body of the lambda expression
1170 either way.
1172 @item lambda-expr
1173 A lambda expression with no quoting.
1175 @item &optional
1176 @kindex &optional @r{(Edebug)}
1177 All following elements in the specification list are optional; as soon
1178 as one does not match, Edebug stops matching at this level.  
1180 To make just a few elements optional followed by non-optional elements,
1181 use @code{[&optional @var{specs}@dots{}]}.  To specify that several
1182 elements must all match or none, use @code{&optional
1183 [@var{specs}@dots{}]}.  See the @code{defun} example below.
1185 @item &rest
1186 @kindex &rest @r{(Edebug)}
1187 All following elements in the specification list are repeated zero or
1188 more times.  In the last repetition, however, it is not a problem if the
1189 expression runs out before matching all of the elements of the
1190 specification list.
1192 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
1193 To specify several elements that must all match on every repetition, use
1194 @code{&rest [@var{specs}@dots{}]}.
1196 @item &or
1197 @kindex &or @r{(Edebug)}
1198 Each of the following elements in the specification list is an
1199 alternative.  One of the alternatives must match, or the @code{&or}
1200 specification fails.
1202 Each list element following @code{&or} is a single alternative.  To
1203 group two or more list elements as a single alternative, enclose them in
1204 @code{[@dots{}]}.
1206 @item &not
1207 @kindex &not @r{(Edebug)}
1208 Each of the following elements is matched as alternatives as if by using
1209 @code{&or}, but if any of them match, the specification fails.  If none
1210 of them match, nothing is matched, but the @code{&not} specification
1211 succeeds.
1213 @item &define 
1214 @kindex &define @r{(Edebug)}
1215 Indicates that the specification is for a defining form.  The defining
1216 form itself is not instrumented (that is, Edebug does not stop before and
1217 after the defining form), but forms inside it typically will be
1218 instrumented.  The @code{&define} keyword should be the first element in
1219 a list specification.
1221 @item nil
1222 This is successful when there are no more arguments to match at the
1223 current argument list level; otherwise it fails.  See sublist
1224 specifications and the backquote example below.
1226 @item gate
1227 @cindex preventing backtracking
1228 No argument is matched but backtracking through the gate is disabled
1229 while matching the remainder of the specifications at this level.  This
1230 is primarily used to generate more specific syntax error messages.  See
1231 @ref{Backtracking}, for more details.  Also see the @code{let} example
1232 below.
1234 @item @var{other-symbol}
1235 @cindex indirect specifications
1236 Any other symbol in a specification list may be a predicate or an
1237 indirect specification.
1239 If the symbol has an Edebug specification, this @dfn{indirect
1240 specification} should be either a list specification that is used in
1241 place of the symbol, or a function that is called to process the
1242 arguments.  The specification may be defined with @code{def-edebug-spec}
1243 just as for macros. See the @code{defun} example below.
1245 Otherwise, the symbol should be a predicate.  The predicate is called
1246 with the argument and the specification fails if the predicate returns
1247 @code{nil}.  In either case, that argument is not instrumented.
1249 Some suitable predicates include @code{symbolp}, @code{integerp},
1250 @code{stringp}, @code{vectorp}, and @code{atom}.
1252 @item [@var{elements}@dots{}]
1253 @cindex [@dots{}] (Edebug)
1254 A vector of elements groups the elements into a single @dfn{group
1255 specification}.  Its meaning has nothing to do with vectors.
1257 @item "@var{string}"
1258 The argument should be a symbol named @var{string}.  This specification
1259 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
1260 of @var{symbol} is the @var{string}, but the string form is preferred.
1262 @item (vector @var{elements}@dots{})
1263 The argument should be a vector whose elements must match the
1264 @var{elements} in the specification.  See the backquote example below.
1266 @item (@var{elements}@dots{})
1267 Any other list is a @dfn{sublist specification} and the argument must be
1268 a list whose elements match the specification @var{elements}.
1270 @cindex dotted lists (Edebug)
1271 A sublist specification may be a dotted list and the corresponding list
1272 argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
1273 dotted list specification may be another sublist specification (via a
1274 grouping or an indirect specification, e.g., @code{(spec .  [(more
1275 specs@dots{})])}) whose elements match the non-dotted list arguments.
1276 This is useful in recursive specifications such as in the backquote
1277 example below.  Also see the description of a @code{nil} specification
1278 above for terminating such recursion.
1280 Note that a sublist specification written as @code{(specs .  nil)}
1281 is equivalent to @code{(specs)}, and @code{(specs .
1282 (sublist-elements@dots{}))} is equivalent to @code{(specs
1283 sublist-elements@dots{})}.
1284 @end table
1286 @c Need to document extensions with &symbol and :symbol
1288 Here is a list of additional specifications that may appear only after
1289 @code{&define}.  See the @code{defun} example below.
1291 @table @code
1292 @item name
1293 The argument, a symbol, is the name of the defining form. 
1295 A defining form is not required to have a name field; and it may have
1296 multiple name fields.
1298 @item :name
1299 This construct does not actually match an argument.  The element
1300 following @code{:name} should be a symbol; it is used as an additional
1301 name component for the definition.  You can use this to add a unique,
1302 static component to the name of the definition.  It may be used more
1303 than once.
1305 @item arg
1306 The argument, a symbol, is the name of an argument of the defining form.
1307 However, lambda-list keywords (symbols starting with @samp{&})
1308 are not allowed.
1310 @item lambda-list
1311 @cindex lambda-list (Edebug)
1312 This matches a lambda list---the argument list of a lambda expression.
1314 @item def-body
1315 The argument is the body of code in a definition.  This is like
1316 @code{body}, described above, but a definition body must be instrumented
1317 with a different Edebug call that looks up information associated with
1318 the definition.  Use @code{def-body} for the highest level list of forms
1319 within the definition.
1321 @item def-form
1322 The argument is a single, highest-level form in a definition.  This is
1323 like @code{def-body}, except use this to match a single form rather than
1324 a list of forms.  As a special case, @code{def-form} also means that
1325 tracing information is not output when the form is executed.  See the
1326 @code{interactive} example below.
1327 @end table
1329 @node Backtracking
1330 @subsubsection Backtracking in Specifications
1332 @cindex backtracking
1333 @cindex syntax error (Edebug)
1334 If a specification fails to match at some point, this does not
1335 necessarily mean a syntax error will be signaled; instead,
1336 @dfn{backtracking} will take place until all alternatives have been
1337 exhausted.  Eventually every element of the argument list must be
1338 matched by some element in the specification, and every required element
1339 in the specification must match some argument.
1340   
1341 When a syntax error is detected, it might not be reported until much
1342 later after higher-level alternatives have been exhausted, and with the
1343 point positioned further from the real error.  But if backtracking is
1344 disabled when an error occurs, it can be reported immediately.  Note
1345 that backtracking is also reenabled automatically in several situations;
1346 it is reenabled when a new alternative is established by
1347 @code{&optional}, @code{&rest}, or @code{&or}, or at the start of
1348 processing a sublist, group, or indirect specification.  The effect of
1349 enabling or disabling backtracking is limited to the remainder of the
1350 level currently being processed and lower levels.
1352 Backtracking is disabled while matching any of the
1353 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
1354 @code{def-body}).  These specifications will match any form so any error
1355 must be in the form itself rather than at a higher level.
1357 Backtracking is also disabled after successfully matching a quoted
1358 symbol or string specification, since this usually indicates a
1359 recognized construct.  But if you have a set of alternative constructs that
1360 all begin with the same symbol, you can usually work around this
1361 constraint by factoring the symbol out of the alternatives, e.g.,
1362 @code{["foo" &or [first case] [second case] ...]}.
1364 Most needs are satisfied by these two ways that bactracking is
1365 automatically disabled, but occasionally it is useful to explicitly
1366 disable backtracking by using the @code{gate} specification.  This is
1367 useful when you know that no higher alternatives could apply.  See the
1368 example of the @code{let} specification.
1370 @node Specification Examples
1371 @subsubsection Specification Examples
1373 It may be easier to understand Edebug specifications by studying
1374 the examples provided here.
1376 A @code{let} special form has a sequence of bindings and a body.  Each
1377 of the bindings is either a symbol or a sublist with a symbol and
1378 optional expression.  In the specification below, notice the @code{gate}
1379 inside of the sublist to prevent backtracking once a sublist is found.
1381 @example
1382 (def-edebug-spec let
1383   ((&rest
1384     &or symbolp (gate symbolp &optional form))
1385    body))
1386 @end example
1388 Edebug uses the following specifications for @code{defun} and
1389 @code{defmacro} and the associated argument list and @code{interactive}
1390 specifications.  It is necessary to handle interactive forms specially
1391 since an expression argument it is actually evaluated outside of the
1392 function body.
1394 @smallexample
1395 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
1396 (def-edebug-spec defun 
1397   (&define name lambda-list 
1398            [&optional stringp]   ; @r{Match the doc string, if present.}
1399            [&optional ("interactive" interactive)]
1400            def-body))
1402 (def-edebug-spec lambda-list
1403   (([&rest arg]
1404     [&optional ["&optional" arg &rest arg]]
1405     &optional ["&rest" arg]
1406     )))
1408 (def-edebug-spec interactive
1409   (&optional &or stringp def-form))    ; @r{Notice: @code{def-form}}
1410 @end smallexample
1412 The specification for backquote below illustrates how to match
1413 dotted lists and use @code{nil} to terminate recursion.  It also
1414 illustrates how components of a vector may be matched.  (The actual
1415 specification defined by Edebug does not support dotted lists because
1416 doing so causes very deep recursion that could fail.)
1418 @smallexample
1419 (def-edebug-spec ` (backquote-form))   ; @r{Alias just for clarity.}
1421 (def-edebug-spec backquote-form
1422   (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
1423        (backquote-form . [&or nil backquote-form])
1424        (vector &rest backquote-form)
1425        sexp))
1426 @end smallexample
1429 @node Edebug Options
1430 @subsection Edebug Options
1432   These options affect the behavior of Edebug:
1434 @defopt edebug-setup-hook
1435 Functions to call before Edebug is used.  Each time it is set to a new
1436 value, Edebug will call those functions once and then
1437 @code{edebug-setup-hook} is reset to @code{nil}.  You could use this to
1438 load up Edebug specifications associated with a package you are using
1439 but only when you also use Edebug.
1440 @xref{Instrumenting}.
1441 @end defopt
1443 @defopt edebug-all-defs
1444 If this is non-@code{nil}, normal evaluation of defining forms such as
1445 @code{defun} and @code{defmacro} instruments them for Edebug.  This
1446 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
1447 and @code{eval-current-buffer}.
1449 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
1450 option.  @xref{Instrumenting}.
1451 @end defopt
1453 @defopt edebug-all-forms
1454 If this is non-@code{nil}, the commands @code{eval-defun},
1455 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
1456 instrument all forms, even those that don't define anything.
1457 This doesn't apply to loading or evaluations in the minibuffer.
1459 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
1460 option.  @xref{Instrumenting}.
1461 @end defopt
1463 @defopt edebug-save-windows
1464 If this is non-@code{nil}, Edebug saves and restores the window
1465 configuration.  That takes some time, so if your program does not care
1466 what happens to the window configurations, it is better to set this
1467 variable to @code{nil}.
1469 If the value is a list, only the listed windows are saved and
1470 restored.  
1472 You can use the @kbd{W} command in Edebug to change this variable
1473 interactively.  @xref{Edebug Display Update}.
1474 @end defopt
1476 @defopt edebug-save-displayed-buffer-points
1477 If this is non-@code{nil}, Edebug saves and restores point in all
1478 displayed buffers.
1480 Saving and restoring point in other buffers is necessary if you are
1481 debugging code that changes the point of a buffer which is displayed in
1482 a non-selected window.  If Edebug or the user then selects the window,
1483 point in that buffer will move to the window's value of point.
1485 Saving and restoring point in all buffers is expensive, since it
1486 requires selecting each window twice, so enable this only if you need
1487 it.  @xref{Edebug Display Update}.
1488 @end defopt
1490 @defopt edebug-initial-mode
1491 If this variable is non-@code{nil}, it specifies the initial execution
1492 mode for Edebug when it is first activated.  Possible values are
1493 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
1494 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
1496 The default value is @code{step}.  
1497 @xref{Edebug Execution Modes}.
1498 @end defopt
1500 @defopt edebug-trace
1501 Non-@code{nil} means display a trace of function entry and exit.
1502 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
1503 function entry or exit per line, indented by the recursion level.  
1505 The default value is @code{nil}.  
1507 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
1508 @end defopt
1510 @defopt edebug-test-coverage 
1511 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
1512 @xref{Coverage Testing}.
1513 @end defopt
1515 @defopt edebug-continue-kbd-macro 
1516 If non-@code{nil}, continue defining or executing any keyboard macro
1517 that is executing outside of Edebug.   Use this with caution since it is not
1518 debugged.
1519 @xref{Edebug Execution Modes}.
1520 @end defopt
1522 @defopt edebug-on-error
1523 Edebug binds @code{debug-on-error} to this value, if
1524 @code{debug-on-error} was previously @code{nil}.  @xref{Trapping
1525 Errors}.
1526 @end defopt
1528 @defopt edebug-on-quit
1529 Edebug binds @code{debug-on-quit} to this value, if
1530 @code{debug-on-quit} was previously @code{nil}.  @xref{Trapping
1531 Errors}.
1532 @end defopt
1534   If you change the values of @code{edebug-on-error} or
1535 @code{edebug-on-quit} while Edebug is active, their values won't be used
1536 until the @emph{next} time Edebug is invoked via a new command.
1537 @c Not necessarily a deeper command level.
1538 @c A new command is not precisely true, but that is close enough -- dan
1540 @defopt edebug-global-break-condition
1541 If non-@code{nil}, an expression to test for at every stop point.
1542 If the result is non-nil, then break.  Errors are ignored.
1543 @xref{Global Break Condition}.
1544 @end defopt