1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
55 Edebug Execution Modes
56 ----------------------
58 Edebug supports several execution modes for running the program you
59 are debugging. We call these alternatives "Edebug execution modes"; do
60 not confuse them with major or minor modes. The current Edebug
61 execution mode determines how Edebug displays the progress of the
62 evaluation, whether it stops at each stop point, or continues to the
63 next breakpoint, for example.
65 Normally, you specify the Edebug execution mode by typing a command
66 to continue the program in a certain mode. Here is a table of these
67 commands. All except for `S' resume execution of the program, at least
68 for a certain distance.
71 Stop: don't execute any more of the program for now, just wait for
72 more Edebug commands (`edebug-stop').
75 Step: stop at the next stop point encountered (`edebug-step-mode').
78 Next: stop at the next stop point encountered after an expression
79 (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note
83 Trace: pause one second at each Edebug stop point
84 (`edebug-trace-mode').
87 Rapid trace: update at each stop point, but don't actually pause
88 (`edebug-Trace-fast-mode').
91 Go: run until the next breakpoint (`edebug-go-mode'). *Note
95 Continue: pause for one second at each breakpoint, but don't stop
96 (`edebug-continue-mode').
99 Rapid continue: update at each breakpoint, but don't actually pause
100 (`edebug-Continue-fast-mode').
103 Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You
104 can still stop the program by hitting any key.
106 In general, the execution modes earlier in the above list run the
107 program more slowly or stop sooner.
109 When you enter a new Edebug level, the initial execution mode comes
110 from the value of the variable `edebug-initial-mode'. By default, this
111 specifies `step' mode. Note that you may reenter the same Edebug level
112 several times if, for example, an instrumented function is called
113 several times from one command.
115 While executing or tracing, you can interrupt the execution by typing
116 any Edebug command. Edebug stops the program at the next stop point and
117 then executes the command that you typed. For example, typing `t'
118 during execution switches to trace mode at the next stop point. You can
119 use `S' to stop execution without doing anything else.
121 If your function happens to read input, a character you hit
122 intending to interrupt execution may be read by the function instead.
123 You can avoid such unintended results by paying attention to when your
126 Keyboard macros containing Edebug commands do not work; when you exit
127 from Edebug, to resume the program, whether you are defining or
128 executing a keyboard macro is forgotten. Also, defining or executing a
129 keyboard macro outside of Edebug does not affect the command loop inside
130 Edebug. This is usually an advantage. But see
131 `edebug-continue-kbd-macro'.
134 File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug
139 Commands described here let you jump to a specified location. All,
140 except `i', use temporary breakpoints to establish the stop point and
141 then switch to `go' mode. Any other breakpoint reached before the
142 intended stop point will also stop execution. See *Note Breakpoints::
143 for the details on breakpoints.
146 Run the program forward over one expression
147 (`edebug-forward-sexp'). More precisely, set a temporary
148 breakpoint at the position that `C-M-f' would reach, then execute
149 in `go' mode so that the program will stop at breakpoints.
151 With a prefix argument N, the temporary breakpoint is placed N
152 sexps beyond point. If the containing list ends before N more
153 elements, then the place to stop is after the containing
156 Be careful that the position `C-M-f' finds is a place that the
157 program will really get to; this may not be true in a `cond', for
160 This command does `forward-sexp' starting at point rather than the
161 stop point. If you want to execute one expression from the
162 current stop point, type `w' first, to move point there.
165 Continue "out of" an expression (`edebug-step-out'). It places a
166 temporary breakpoint at the end of the sexp containing point.
168 If the containing sexp is a function definition itself, it
169 continues until just before the last sexp in the definition. If
170 that is where you are now, it returns from the function and then
171 stops. In other words, this command does not exit the currently
172 executing function unless you are positioned after the last sexp.
175 Step into the function or macro after point after first ensuring
176 that it is instrumented. It does this by calling
177 `edebug-on-entry' and then switching to `go' mode.
179 Although the automatic instrumentation is convenient, it is not
180 later automatically uninstrumented.
183 Proceed to the stop point near where point is using a temporary
184 breakpoint (`edebug-goto-here').
186 All the commands in this section may fail to work as expected in case
187 of nonlocal exit, because a nonlocal exit can bypass the temporary
188 breakpoint where you expected the program to stop.
191 File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug
196 Some miscellaneous commands are described here.
199 Display the help message for Edebug (`edebug-help').
202 Abort one level back to the previous command level
203 (`abort-recursive-edit').
206 Return to the top level editor command loop (`top-level'). This
207 exits all recursive editing levels, including all levels of Edebug
208 activity. However, instrumented code protected with
209 `unwind-protect' or `condition-case' forms may resume debugging.
212 Like `q' but don't stop even for protected code
213 (`top-level-nonstop').
216 Redisplay the most recently known expression result in the echo
217 area (`edebug-previous-result').
220 Display a backtrace, excluding Edebug's own functions for clarity
221 (`edebug-backtrace').
223 You cannot use debugger commands in the backtrace buffer in Edebug
224 as you would in the standard debugger.
226 The backtrace buffer is killed automatically when you continue
229 From the Edebug recursive edit, you may invoke commands that activate
230 Edebug again recursively. Any time Edebug is active, you can quit to
231 the top level with `q' or abort one recursive edit level with `C-]'.
232 You can display a backtrace of all the pending evaluations with `d'.
235 File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug
240 There are three more ways to stop execution once it has started:
241 breakpoints, the global break condition, and embedded breakpoints.
243 While using Edebug, you can specify "breakpoints" in the program you
244 are testing: points where execution should stop. You can set a
245 breakpoint at any stop point, as defined in *Note Using Edebug::. For
246 setting and unsetting breakpoints, the stop point that is affected is
247 the first one at or after point in the source code buffer. Here are the
248 Edebug commands for breakpoints:
251 Set a breakpoint at the stop point at or after point
252 (`edebug-set-breakpoint'). If you use a prefix argument, the
253 breakpoint is temporary (it turns off the first time it stops the
257 Unset the breakpoint (if any) at the stop point at or after the
258 current point (`edebug-unset-breakpoint').
261 Set a conditional breakpoint which stops the program only if
262 CONDITION evaluates to a non-`nil' value
263 (`edebug-set-conditional-breakpoint'). If you use a prefix
264 argument, the breakpoint is temporary (it turns off the first time
265 it stops the program).
268 Move point to the next breakpoint in the definition
269 (`edebug-next-breakpoint').
271 While in Edebug, you can set a breakpoint with `b' and unset one
272 with `u'. First you must move point to a position at or before the
273 desired Edebug stop point, then hit the key to change the breakpoint.
274 Unsetting a breakpoint that has not been set does nothing.
276 Reevaluating or reinstrumenting a definition clears all its
279 A "conditional breakpoint" tests a condition each time the program
280 gets there. To set a conditional breakpoint, use `x', and specify the
281 condition expression in the minibuffer. Setting a conditional
282 breakpoint at a stop point that already has a conditional breakpoint
283 puts the current condition expression in the minibuffer so you can edit
286 You can make both conditional and unconditional breakpoints
287 "temporary" by using a prefix arg to the command to set the breakpoint.
288 After breaking at a temporary breakpoint, it is automatically cleared.
290 Edebug always stops or pauses at a breakpoint except when the Edebug
291 mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely.
293 To find out where your breakpoints are, use `B', which moves point
294 to the next breakpoint in the definition following point, or to the
295 first breakpoint if there are no following breakpoints. This command
296 does not continue execution--it just moves point in the buffer.
300 * Global Break Condition:: Breaking on an event.
301 * Embedded Breakpoints:: Embedding breakpoints in code.
304 File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints
306 Global Break Condition
307 ......................
309 In contrast to breaking when execution reaches specified locations,
310 you can also cause a break when a certain event occurs. The "global
311 break condition" is a condition that is repeatedly evaluated at every
312 stop point. If it evaluates to a non-`nil' value, then execution is
313 stopped or paused depending on the execution mode, just like a
314 breakpoint. Any errors that might occur as a result of evaluating the
315 condition are ignored, as if the result were `nil'.
317 You can set or edit the condition expression, stored in
318 `edebug-global-break-condition', using `X'
319 (`edebug-set-global-break-condition').
321 Using the global break condition is perhaps the fastest way to find
322 where in your code some event occurs, but since it is rather expensive
323 you should reset the condition to `nil' when not in use.
326 File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints
331 Since all breakpoints in a definition are cleared each time you
332 reinstrument it, you might rather create an "embedded breakpoint" which
333 is simply a call to the function `edebug'. You can, of course, make
334 such a call conditional. For example, in the `fac' function, insert
335 the first line as shown below to stop when the argument reaches zero:
338 (if (= n 0) (edebug))
343 When the `fac' definition is instrumented and the function is
344 called, Edebug will stop before the call to `edebug'. Depending on the
345 execution mode, Edebug will stop or pause.
347 However, if no instrumented code is being executed, calling `edebug'
348 will instead invoke `debug'. Calling `debug' will always invoke the
349 standard backtrace debugger.
352 File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug
357 An error may be signaled by subroutines or XEmacs Lisp code. If a
358 signal is not handled by a `condition-case', this indicates an
359 unrecognized situation has occurred. If Edebug is not active when an
360 unhandled error is signaled, `debug' is run normally (if
361 `debug-on-error' is non-`nil'). But while Edebug is active,
362 `debug-on-error' and `debug-on-quit' are bound to `edebug-on-error' and
363 `edebug-on-quit', which are both `t' by default. Actually, if
364 `debug-on-error' already has a non-`nil' value, that value is still
367 It is best to change the values of `edebug-on-error' or
368 `edebug-on-quit' when Edebug is not active since their values won't be
369 used until the next time Edebug is invoked at a deeper command level.
370 If you only change `debug-on-error' or `debug-on-quit' while Edebug is
371 active, these changes will be forgotten when Edebug becomes inactive.
372 Furthermore, during Edebug's recursive edit, these variables are bound
373 to the values they had outside of Edebug.
375 Edebug shows you the last stop point that it knew about before the
376 error was signaled. This may be the location of a call to a function
377 which was not instrumented, within which the error actually occurred.
378 For an unbound variable error, the last known stop point might be quite
379 distant from the offending variable. If the cause of the error is not
380 obvious at first, note that you can also get a full backtrace inside of
381 Edebug (see *Note Edebug Misc::).
383 Edebug can also trap signals even if they are handled. If
384 `debug-on-error' is a list of signal names, Edebug will stop when any
385 of these errors are signaled. Edebug shows you the last known stop
386 point just as for unhandled errors. After you continue execution, the
387 error is signaled again (but without being caught by Edebug). Edebug
388 can only trap errors that are handled if they are signaled in Lisp code
389 (not subroutines) since it does so by temporarily replacing the
393 File: lispref.info, Node: Edebug Views, Next: Edebug Eval, Prev: Trapping Errors, Up: Edebug
398 The following Edebug commands let you view aspects of the buffer and
399 window status that obtained before entry to Edebug.
402 View the outside window configuration (`edebug-view-outside').
405 Temporarily display the outside current buffer with point at its
406 outside position (`edebug-bounce-point'). If prefix arg is
407 supplied, sit for that many seconds instead.
410 Move point back to the current stop point (`edebug-where') in the
411 source code buffer. Also, if you use this command in another
412 window displaying the same buffer, this window will be used
413 instead to display the buffer in the future.
416 Toggle the `edebug-save-windows' variable which indicates whether
417 the outside window configuration is saved and restored
418 (`edebug-toggle-save-windows'). Also, each time it is toggled on,
419 make the outside window configuration the same as the current
420 window configuration.
422 With a prefix argument, `edebug-toggle-save-windows' only toggles
423 saving and restoring of the selected window. To specify a window
424 that is not displaying the source code buffer, you must use
425 `C-xXW' from the global keymap.
427 You can view the outside window configuration with `v' or just
428 bounce to the current point in the current buffer with `p', even if it
429 is not normally displayed. After moving point, you may wish to pop
430 back to the stop point with `w' from a source code buffer.
432 By using `W' twice, Edebug again saves and restores the outside
433 window configuration, but to the current configuration. This is a
434 convenient way to, for example, add another buffer to be displayed
435 whenever Edebug is active. However, the automatic redisplay of
436 `*edebug*' and `*edebug-trace*' may conflict with the buffers you wish
437 to see unless you have enough windows open.
440 File: lispref.info, Node: Edebug Eval, Next: Eval List, Prev: Edebug Views, Up: Edebug
445 While within Edebug, you can evaluate expressions "as if" Edebug were
446 not running. Edebug tries to be invisible to the expression's
447 evaluation and printing. Evaluation of expressions that cause side
448 effects will work as expected except for things that Edebug explicitly
449 saves and restores. See *Note The Outside Context:: for details on this
450 process. Also see *Note Reading in Edebug:: and *Note Printing in
451 Edebug:: for topics related to evaluation.
454 Evaluate expression EXP in the context outside of Edebug
455 (`edebug-eval-expression'). In other words, Edebug tries to avoid
456 altering the effect of EXP.
459 Evaluate expression EXP in the context of Edebug itself.
462 Evaluate the expression before point, in the context outside of
463 Edebug (`edebug-eval-last-sexp').
465 Edebug supports evaluation of expressions containing references to
466 lexically bound symbols created by the following constructs in `cl.el'
467 (version 2.03 or later): `lexical-let', `macrolet', and
471 File: lispref.info, Node: Eval List, Next: Reading in Edebug, Prev: Edebug Eval, Up: Edebug
473 Evaluation List Buffer
474 ----------------------
476 You can use the "evaluation list buffer", called `*edebug*', to
477 evaluate expressions interactively. You can also set up the
478 "evaluation list" of expressions to be evaluated automatically each
479 time Edebug updates the display.
482 Switch to the evaluation list buffer `*edebug*'
483 (`edebug-visit-eval-list').
485 In the `*edebug*' buffer you can use the commands of Lisp
486 Interaction as well as these special commands:
489 Evaluate the expression before point, in the outside context, and
490 insert the value in the buffer (`edebug-eval-print-last-sexp').
493 Evaluate the expression before point, in the context outside of
494 Edebug (`edebug-eval-last-sexp').
497 Build a new evaluation list from the first expression of each
498 group, reevaluate and redisplay (`edebug-update-eval-list').
499 Groups are separated by comment lines.
502 Delete the evaluation list group that point is in
503 (`edebug-delete-eval-item').
506 Switch back to the source code buffer at the current stop point
509 You can evaluate expressions in the evaluation list window with
510 `LFD' or `C-x C-e', just as you would in `*scratch*'; but they are
511 evaluated in the context outside of Edebug.
513 The expressions you enter interactively (and their results) are lost
514 when you continue execution unless you add them to the evaluation list
515 with `C-c C-u'. This command builds a new list from the first
516 expression of each "evaluation list group". Groups are separated by
517 comment lines. Be careful not to add expressions that execute
518 instrumented code otherwise an infinite loop will result.
520 When the evaluation list is redisplayed, each expression is displayed
521 followed by the result of evaluating it, and a comment line. If an
522 error occurs during an evaluation, the error message is displayed in a
523 string as if it were the result. Therefore expressions that, for
524 example, use variables not currently valid do not interrupt your
527 Here is an example of what the evaluation list window looks like
528 after several expressions have been added to it:
532 ;---------------------------------------------------------------
534 #<window 16 on *scratch*>
535 ;---------------------------------------------------------------
538 ;---------------------------------------------------------------
540 "Symbol's value as variable is void: bad-var"
541 ;---------------------------------------------------------------
544 ;---------------------------------------------------------------
547 ;---------------------------------------------------------------
549 To delete a group, move point into it and type `C-c C-d', or simply
550 delete the text for the group and update the evaluation list with `C-c
551 C-u'. When you add a new group, be sure it is separated from its
552 neighbors by a comment line.
554 After selecting `*edebug*', you can return to the source code buffer
555 with `C-c C-w'. The `*edebug*' buffer is killed when you continue
556 execution, and recreated next time it is needed.
559 File: lispref.info, Node: Reading in Edebug, Next: Printing in Edebug, Prev: Eval List, Up: Edebug
564 To instrument a form, Edebug first reads the whole form. Edebug
565 replaces the standard Lisp Reader with its own reader that remembers the
566 positions of expressions. This reader is used by the Edebug
567 replacements for `eval-region', `eval-defun', `eval-buffer', and
568 `eval-current-buffer'.
570 Another package, `cl-read.el', replaces the standard reader with one
571 that understands Common Lisp reader macros. If you use that package,
572 Edebug will automatically load `edebug-cl-read.el' to provide
573 corresponding reader macros that remember positions of expressions. If
574 you define new reader macros, you will have to define similar reader
578 File: lispref.info, Node: Printing in Edebug, Next: Tracing, Prev: Reading in Edebug, Up: Edebug
583 If the result of an expression in your program contains a circular
584 reference, you may get an error when Edebug attempts to print it. You
585 can set `print-length' to a non-zero value to limit the print length of
586 lists (the number of cdrs), and in Emacs 19, set `print-level' to a
587 non-zero value to limit the print depth of lists. But you can print
588 such circular structures and structures that share elements more
589 informatively by using the `cust-print' package.
591 To load `cust-print' and activate custom printing only for Edebug,
592 simply use the command `M-x edebug-install-custom-print'. To restore
593 the standard print functions, use `M-x edebug-uninstall-custom-print'.
594 You can also activate custom printing for printing in any Lisp code;
595 see the package for details.
597 Here is an example of code that creates a circular structure:
600 (edebug-install-custom-print)
604 Edebug will print the result of the `setcar' as `Result: #1=(#1#
605 y)'. The `#1=' notation names the structure that follows it, and the
606 `#1#' notation references the previously named structure. This
607 notation is used for any shared elements of lists or vectors.
609 Independent of whether `cust-print' is active, while printing
610 results Edebug binds `print-length', `print-level', and `print-circle'
611 to `edebug-print-length' (`50'), `edebug-print-level' (`50'), and
612 `edebug-print-circle' (`t') respectively, if these values are
613 non-`nil'. Also, `print-readably' is bound to `nil' since some objects
614 simply cannot be printed readably.
617 File: lispref.info, Node: Tracing, Next: Coverage Testing, Prev: Printing in Edebug, Up: Edebug
622 In addition to automatic stepping through source code, which is also
623 called _tracing_ (see *Note Edebug Execution Modes::), Edebug can
624 produce a traditional trace listing of execution in a separate buffer,
627 If the variable `edebug-trace' is non-`nil', each function entry and
628 exit adds lines to the trace buffer. On function entry, Edebug prints
629 `::::{' followed by the function name and argument values. On function
630 exit, Edebug prints `::::}' followed by the function name and result of
631 the function. The number of `:'s is computed from the recursion depth.
632 The balanced braces in the trace buffer can be used to find the
633 matching beginning or end of function calls. These displays may be
634 customized by replacing the functions `edebug-print-trace-before' and
635 `edebug-print-trace-after', which take an arbitrary message string to
638 The macro `edebug-tracing' provides tracing similar to function
639 enter and exit tracing, but for arbitrary expressions. This macro
640 should be explicitly inserted by you around expressions you wish to
641 trace the execution of. The first argument is a message string
642 (evaluated), and the rest are expressions to evaluate. The result of
643 the last expression is returned.
645 Finally, you can insert arbitrary strings into the trace buffer with
646 explicit calls to `edebug-trace'. The arguments of this function are
647 the same as for `message', but a newline is always inserted after each
648 string printed in this way.
650 `edebug-tracing' and `edebug-trace' insert lines in the trace buffer
651 even if Edebug is not active. Every time the trace buffer is added to,
652 the window is scrolled to show the last lines inserted. (There may be
653 some display problems if you use tracing along with the evaluation
657 File: lispref.info, Node: Coverage Testing, Next: The Outside Context, Prev: Tracing, Up: Edebug
662 Edebug provides a rudimentary coverage tester and display of
663 execution frequency. Frequency counts are always accumulated, both
664 before and after evaluation of each instrumented expression, even if
665 the execution mode is `Go-nonstop'. Coverage testing is only done if
666 the option `edebug-test-coverage' is non-`nil' because this is
667 relatively expensive. Both data sets are displayed by `M-x
668 edebug-display-freq-count'.
670 - Command: edebug-display-freq-count
671 Display the frequency count data for each line of the current
672 definition. The frequency counts are inserted as comment lines
673 after each line, and you can undo all insertions with one `undo'
674 command. The counts are inserted starting under the `(' before an
675 expression or the `)' after an expression, or on the last char of
676 a symbol. The counts are only displayed when they differ from
677 previous counts on the same line.
679 If coverage is being tested, whenever all known results of an
680 expression are `eq', the char `=' will be appended after the count
681 for that expression. Note that this is always the case for an
682 expression only evaluated once.
684 To clear the frequency count and coverage data for a definition,
688 For example, after evaluating `(fac 5)' with an embedded breakpoint,
689 and setting `edebug-test-coverage' to `t', when the breakpoint is
690 reached, the frequency data is looks like this:
693 (if (= n 0) (edebug))
702 The comment lines show that `fac' has been called 6 times. The
703 first `if' statement has returned 5 times with the same result each
704 time, and the same is true for the condition on the second `if'. The
705 recursive call of `fac' has not returned at all.
708 File: lispref.info, Node: The Outside Context, Next: Instrumenting Macro Calls, Prev: Coverage Testing, Up: Edebug
713 Edebug tries to be transparent to the program you are debugging. In
714 addition, most evaluations you do within Edebug (see *Note Edebug
715 Eval::) occur in the same outside context which is temporarily restored
716 for the evaluation. But Edebug is not completely successful and this
717 section explains precisely how it fails. Edebug operation unavoidably
718 alters some data in XEmacs, and this can interfere with debugging
719 certain programs. Also notice that Edebug's protection against change
720 of outside data means that any side effects _intended_ by the user in
721 the course of debugging will be defeated.
725 * Checking Whether to Stop:: When Edebug decides what to do.
726 * Edebug Display Update:: When Edebug updates the display.
727 * Edebug Recursive Edit:: When Edebug stops execution.
730 File: lispref.info, Node: Checking Whether to Stop, Next: Edebug Display Update, Up: The Outside Context
732 Checking Whether to Stop
733 ........................
735 Whenever Edebug is entered just to think about whether to take some
736 action, it needs to save and restore certain data.
738 * `max-lisp-eval-depth' and `max-specpdl-size' are both incremented
739 one time to reduce Edebug's impact on the stack. You could,
740 however, still run out of stack space when using Edebug.
742 * The state of keyboard macro execution is saved and restored. While
743 Edebug is active, `executing-macro' is bound to
744 `edebug-continue-kbd-macro'.
748 File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context
750 Edebug Display Update
751 .....................
753 When Edebug needs to display something (e.g., in trace mode), it
754 saves the current window configuration from "outside" Edebug. When you
755 exit Edebug (by continuing the program), it restores the previous window
758 XEmacs redisplays only when it pauses. Usually, when you continue
759 execution, the program comes back into Edebug at a breakpoint or after
760 stepping without pausing or reading input in between. In such cases,
761 XEmacs never gets a chance to redisplay the "outside" configuration.
762 What you see is the same window configuration as the last time Edebug
763 was active, with no interruption.
765 Entry to Edebug for displaying something also saves and restores the
766 following data, but some of these are deliberately not restored if an
767 error or quit signal occurs.
769 * Which buffer is current, and where point and mark are in the
770 current buffer are saved and restored.
772 * The Edebug Display Update, is saved and restored if
773 `edebug-save-windows' is non-`nil'. It is not restored on error
774 or quit, but the outside selected window _is_ reselected even on
775 error or quit in case a `save-excursion' is active. If the value
776 of `edebug-save-windows' is a list, only the listed windows are
779 The window start and horizontal scrolling of the source code
780 buffer are not restored, however, so that the display remains
783 * The value of point in each displayed buffer is saved and restored
784 if `edebug-save-displayed-buffer-points' is non-`nil'.
786 * The variables `overlay-arrow-position' and `overlay-arrow-string'
787 are saved and restored. So you can safely invoke Edebug from the
788 recursive edit elsewhere in the same buffer.
790 * `cursor-in-echo-area' is locally bound to `nil' so that the cursor
791 shows up in the window.
795 File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context
797 Edebug Recursive Edit
798 .....................
800 When Edebug is entered and actually reads commands from the user, it
801 saves (and later restores) these additional data:
803 * The current match data, for whichever buffer was current.
805 * `last-command', `this-command', `last-command-char',
806 `last-input-char', `last-input-event', `last-command-event',
807 `last-event-frame', `last-nonmenu-event', and `track-mouse' .
808 Commands used within Edebug do not affect these variables outside
811 The key sequence returned by `this-command-keys' is changed by
812 executing commands within Edebug and there is no way to reset the
813 key sequence from Lisp.
815 For Emacs 18, Edebug cannot save and restore the value of
816 `unread-command-char'. Entering Edebug while this variable has a
817 nontrivial value can interfere with execution of the program you
820 * Complex commands executed while in Edebug are added to the variable
821 `command-history'. In rare cases this can alter execution.
823 * Within Edebug, the recursion depth appears one deeper than the
824 recursion depth outside Edebug. This is not true of the
825 automatically updated evaluation list window.
827 * `standard-output' and `standard-input' are bound to `nil' by the
828 `recursive-edit', but Edebug temporarily restores them during
831 * The state of keyboard macro definition is saved and restored.
832 While Edebug is active, `defining-kbd-macro' is bound to
833 `edebug-continue-kbd-macro'.
837 File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug
839 Instrumenting Macro Calls
840 -------------------------
842 When Edebug instruments an expression that calls a Lisp macro, it
843 needs additional advice to do the job properly. This is because there
844 is no way to tell which subexpressions of the macro call may be
845 evaluated. (Evaluation may occur explicitly in the macro body, or when
846 the resulting expansion is evaluated, or any time later.) You must
847 explain the format of macro call arguments by using `def-edebug-spec' to
848 define an "Edebug specification" for each macro.
850 - Macro: def-edebug-spec macro specification
851 Specify which expressions of a call to macro MACRO are forms to be
852 evaluated. For simple macros, the SPECIFICATION often looks very
853 similar to the formal argument list of the macro definition, but
854 specifications are much more general than macro arguments.
856 The MACRO argument may actually be any symbol, not just a macro
859 Unless you are using Emacs 19 or XEmacs, this macro is only defined
860 in Edebug, so you may want to use the following which is
861 equivalent: `(put 'MACRO 'edebug-form-spec 'SPECIFICATION)'
863 Here is a simple example that defines the specification for the
864 `for' macro described in the XEmacs Lisp Reference Manual, followed by
865 an alternative, equivalent specification.
868 (symbolp "from" form "to" form "do" &rest form))
871 (symbolp ['from form] ['to form] ['do body]))
873 Here is a table of the possibilities for SPECIFICATION and how each
874 directs processing of arguments.
877 All arguments are instrumented for evaluation.
880 None of the arguments is instrumented.
883 The symbol must have an Edebug specification which is used instead.
884 This indirection is repeated until another kind of specification is
885 found. This allows you to inherit the specification for another
889 The elements of the list describe the types of the arguments of a
890 calling form. The possible elements of a specification list are
891 described in the following sections.
895 * Specification List:: How to specify complex patterns of evaluation.
896 * Backtracking:: What Edebug does when matching fails.
897 * Debugging Backquote:: Debugging Backquote
898 * Specification Examples:: To help understand specifications.
901 File: lispref.info, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls
906 A "specification list" is required for an Edebug specification if
907 some arguments of a macro call are evaluated while others are not. Some
908 elements in a specification list match one or more arguments, but others
909 modify the processing of all following elements. The latter, called
910 "keyword specifications", are symbols beginning with ``&'' (e.g.
913 A specification list may contain sublists which match arguments that
914 are themselves lists, or it may contain vectors used for grouping.
915 Sublists and groups thus subdivide the specification list into a
916 hierarchy of levels. Keyword specifications only apply to the
917 remainder of the sublist or group they are contained in and there is an
918 implicit grouping around a keyword specification and all following
919 elements in the sublist or group.
921 If a specification list fails at some level, then backtracking may
922 be invoked to find some alternative at a higher level, or if no
923 alternatives remain, an error will be signaled. See *Note
924 Backtracking:: for more details.
926 Edebug specifications provide at least the power of regular
927 expression matching. Some context-free constructs are also supported:
928 the matching of sublists with balanced parentheses, recursive
929 processing of forms, and recursion via indirect specifications.
931 Each element of a specification list may be one of the following,
932 with the corresponding type of argument:
935 A single unevaluated expression.
938 A single evaluated expression, which is instrumented.
941 A place as in the Common Lisp `setf' place argument. It will be
942 instrumented just like a form, but the macro is expected to strip
943 the instrumentation. Two functions, `edebug-unwrap' and
944 `edebug-unwrap*', are provided to strip the instrumentation one
945 level or recursively at all levels.
948 Short for `&rest form'. See `&rest' below.
951 A function form: either a quoted function symbol, a quoted lambda
952 expression, or a form (that should evaluate to a function symbol
953 or lambda expression). This is useful when function arguments
954 might be quoted with `quote' rather than `function' since the body
955 of a lambda expression will be instrumented either way.
958 An unquoted anonymous lambda expression.
961 All following elements in the specification list are optional; as
962 soon as one does not match, Edebug stops matching at this level.
964 To make just a few elements optional followed by non-optional
965 elements, use `[&optional SPECS...]'. To specify that several
966 elements should all succeed together, use `&optional [SPECS...]'.
967 See the `defun' example below.
970 All following elements in the specification list are repeated zero
971 or more times. All the elements need not match in the last
974 To repeat only a few elements, use `[&rest SPECS...]'. To specify
975 all elements must match on every repetition, use `&rest
979 Each of the following elements in the specification list is an
980 alternative, processed left to right until one matches. One of the
981 alternatives must match otherwise the `&or' specification fails.
983 Each list element following `&or' is a single alternative even if
984 it is a keyword specification. (This breaks the implicit grouping
985 rule.) To group two or more list elements as a single
986 alternative, enclose them in `[...]'.
989 Each of the following elements is matched as alternatives as if by
990 using `&or', but if any of them match, the specification fails.
991 If none of them match, nothing is matched, but the `¬'
992 specification succeeds.
995 Indicates that the specification is for a defining form. The
996 defining form itself is not instrumented (i.e. Edebug does not
997 stop before and after the defining form), but forms inside it
998 typically will be instrumented. The `&define' keyword should be
999 the first element in a list specification.
1001 Additional specifications that may only appear after `&define' are
1002 described here. See the `defun' example below.
1005 The argument, a symbol, is the name of the defining form.
1006 But a defining form need not be named at all, in which case a
1007 unique name will be created for it.
1009 The `name' specification may be used more than once in the
1010 specification and each subsequent use will append the
1011 corresponding symbol argument to the previous name with ``@''
1012 between them. This is useful for generating unique but
1013 meaningful names for definitions such as `defadvice' and
1017 The element following `:name' should be a symbol; it is used
1018 as an additional name component for the definition. This is
1019 useful to add a unique, static component to the name of the
1020 definition. It may be used more than once. No argument is
1024 The argument, a symbol, is the name of an argument of the
1025 defining form. However, lambda list keywords (symbols
1026 starting with ``&'') are not allowed. See `lambda-list' and
1030 This matches the whole argument list of an XEmacs Lisp lambda
1031 expression, which is a list of symbols and the keywords
1032 `&optional' and `&rest'
1035 The argument is the body of code in a definition. This is
1036 like `body', described above, but a definition body must be
1037 instrumented with a different Edebug call that looks up
1038 information associated with the definition. Use `def-body'
1039 for the highest level list of forms within the definition.
1042 The argument is a single, highest-level form in a definition.
1043 This is like `def-body', except use this to match a single
1044 form rather than a list of forms. As a special case,
1045 `def-form' also means that tracing information is not output
1046 when the form is executed. See the `interactive' example
1050 This is successful when there are no more arguments to match at the
1051 current argument list level; otherwise it fails. See sublist
1052 specifications and the backquote example below.
1055 No argument is matched but backtracking through the gate is
1056 disabled while matching the remainder of the specifications at
1057 this level. This is primarily used to generate more specific
1058 syntax error messages. See *Note Backtracking:: for more details.
1059 Also see the `let' example below.
1062 Any other symbol in a specification list may be a predicate or an
1063 indirect specification.
1065 If the symbol has an Edebug specification, this "indirect
1066 specification" should be either a list specification that is used
1067 in place of the symbol, or a function that is called to process the
1068 arguments. The specification may be defined with `def-edebug-spec'
1069 just as for macros. See the `defun' example below.
1071 Otherwise, the symbol should be a predicate. The predicate is
1072 called with the argument and the specification fails if the
1073 predicate fails. The argument is not instrumented.
1075 Predicates that may be used include: `symbolp', `integerp',
1076 `stringp', `vectorp', `atom' (which matches a number, string,
1077 symbol, or vector), `keywordp', and `lambda-list-keywordp'. The
1078 last two, defined in `edebug.el', test whether the argument is a
1079 symbol starting with ``:'' and ``&'' respectively.
1082 Rather than matching a vector argument, a vector treats the
1083 ELEMENTS as a single "group specification".
1086 The argument should be a symbol named STRING. This specification
1087 is equivalent to the quoted symbol, `'SYMBOL', where the name of
1088 SYMBOL is the STRING, but the string form is preferred.
1090 `'SYMBOL or (quote SYMBOL)'
1091 The argument should be the symbol SYMBOL. But use a string
1092 specification instead.
1094 `(vector ELEMENTS...)'
1095 The argument should be a vector whose elements must match the
1096 ELEMENTS in the specification. See the backquote example below.
1099 Any other list is a "sublist specification" and the argument must
1100 be a list whose elements match the specification ELEMENTS.
1102 A sublist specification may be a dotted list and the corresponding
1103 list argument may then be a dotted list. Alternatively, the last
1104 cdr of a dotted list specification may be another sublist
1105 specification (via a grouping or an indirect specification, e.g.
1106 `(spec . [(more specs...)])') whose elements match the non-dotted
1107 list arguments. This is useful in recursive specifications such
1108 as in the backquote example below. Also see the description of a
1109 `nil' specification above for terminating such recursion.
1111 Note that a sublist specification of the form `(specs . nil)'
1112 means the same as `(specs)', and `(specs .
1113 (sublist-elements...))' means the same as `(specs
1114 sublist-elements...)'.
1117 File: lispref.info, Node: Backtracking, Next: Debugging Backquote, Prev: Specification List, Up: Instrumenting Macro Calls
1122 If a specification fails to match at some point, this does not
1123 necessarily mean a syntax error will be signaled; instead,
1124 "backtracking" will take place until all alternatives have been
1125 exhausted. Eventually every element of the argument list must be
1126 matched by some element in the specification, and every required element
1127 in the specification must match some argument.
1129 Backtracking is disabled for the remainder of a sublist or group when
1130 certain conditions occur, described below. Backtracking is reenabled
1131 when a new alternative is established by `&optional', `&rest', or
1132 `&or'. It is also reenabled initially when processing a sublist or
1133 group specification or an indirect specification.
1135 You might want to disable backtracking to commit to some alternative
1136 so that Edebug can provide a more specific syntax error message.
1137 Normally, if no alternative matches, Edebug reports that none matched,
1138 but if one alternative is committed to, Edebug can report how it failed
1141 First, backtracking is disabled while matching any of the form
1142 specifications (i.e. `form', `body', `def-form', and `def-body').
1143 These specifications will match any form so any error must be in the
1144 form itself rather than at a higher level.
1146 Second, backtracking is disabled after successfully matching a quoted
1147 symbol or string specification, since this usually indicates a
1148 recognized construct. If you have a set of alternative constructs that
1149 all begin with the same symbol, you can usually work around this
1150 constraint by factoring the symbol out of the alternatives, e.g.,
1151 `["foo" &or [first case] [second case] ...]'.
1153 Third, backtracking may be explicitly disabled by using the `gate'
1154 specification. This is useful when you know that no higher
1155 alternatives may apply.
1158 File: lispref.info, Node: Debugging Backquote, Next: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls
1163 Backquote (``') is a macro that results in an expression that may or
1164 may not be evaluated. It is often used to simplify the definition of a
1165 macro to return an expression that is evaluated, but Edebug does not
1166 know when this is the case. However, the forms inside unquotes (`,' and
1167 `,@') are evaluated and Edebug instruments them.
1169 Nested backquotes are supported by Edebug, but there is a limit on
1170 the support of quotes inside of backquotes. Quoted forms (with `'')
1171 are not normally evaluated, but if the quoted form appears immediately
1172 within `,' and `,@' forms, Edebug treats this as a backquoted form at
1173 the next higher level (even if there is not a next higher level - this
1174 is difficult to fix).
1176 If the backquoted forms happen to be code intended to be evaluated,
1177 you can have Edebug instrument them by using `edebug-`' instead of the
1178 regular ``'. Unquoted forms can always appear inside `edebug-`'
1179 anywhere a form is normally allowed. But `(, FORM)' may be used in two
1180 other places specially recognized by Edebug: wherever a predicate
1181 specification would match, and at the head of a list form in place of a
1182 function name or lambda expression. The FORM inside a spliced unquote,
1183 `(,@ FORM)', will be wrapped, but the unquote form itself will not be
1184 wrapped since this would interfere with the splicing.
1186 There is one other complication with using `edebug-`'. If the
1187 `edebug-`' call is in a macro and the macro may be called from code
1188 that is also instrumented, and if unquoted forms contain any macro
1189 arguments bound to instrumented forms, then you should modify the
1190 specification for the macro as follows: the specifications for those
1191 arguments must use `def-form' instead of `form'. (This is to
1192 reestablish the Edebugging context for those external forms.)
1194 For example, the `for' macro (*note Problems with Macros: ()Problems
1195 with Macros.) is shown here but with `edebug-`' substituted for regular
1199 (list 'setq var (list '1+ var)))
1201 (defmacro for (var from init to final do &rest body)
1202 (let ((tempvar (make-symbol "max")))
1203 (edebug-` (let (((, var) (, init))
1204 ((, tempvar) (, final)))
1205 (while (<= (, var) (, tempvar))
1209 Here is the corresponding modified Edebug specification and some code
1210 that calls the macro:
1212 (def-edebug-spec for
1213 (symbolp "from" def-form "to" def-form "do" &rest def-form))
1216 (for i from n to (* n (+ n 1)) do
1219 After instrumenting the `for' macro and the macro call, Edebug first
1220 steps to the beginning of the macro call, then into the macro body,
1221 then through each of the unquoted expressions in the backquote showing
1222 the expressions that will be embedded in the backquote form. Then when
1223 the macro expansion is evaluated, Edebug will step through the `let'
1224 form and each time it gets to an unquoted form, it will jump back to an
1225 argument of the macro call to step through that expression. Finally
1226 stepping will continue after the macro call. Even more convoluted
1227 execution paths may result when using anonymous functions.
1229 When the result of an expression is an instrumented expression, it is
1230 difficult to see the expression inside the instrumentation. So you may
1231 want to set the option `edebug-unwrap-results' to a non-`nil' value
1232 while debugging such expressions, but it would slow Edebug down to
projects / chise / xemacs-chise.git / blob