1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug
58 Commands described here let you jump to a specified location. All,
59 except `i', use temporary breakpoints to establish the stop point and
60 then switch to `go' mode. Any other breakpoint reached before the
61 intended stop point will also stop execution. See *Note Breakpoints::
62 for the details on breakpoints.
65 Run the program forward over one expression
66 (`edebug-forward-sexp'). More precisely, set a temporary
67 breakpoint at the position that `C-M-f' would reach, then execute
68 in `go' mode so that the program will stop at breakpoints.
70 With a prefix argument N, the temporary breakpoint is placed N
71 sexps beyond point. If the containing list ends before N more
72 elements, then the place to stop is after the containing
75 Be careful that the position `C-M-f' finds is a place that the
76 program will really get to; this may not be true in a `cond', for
79 This command does `forward-sexp' starting at point rather than the
80 stop point. If you want to execute one expression from the
81 current stop point, type `w' first, to move point there.
84 Continue "out of" an expression (`edebug-step-out'). It places a
85 temporary breakpoint at the end of the sexp containing point.
87 If the containing sexp is a function definition itself, it
88 continues until just before the last sexp in the definition. If
89 that is where you are now, it returns from the function and then
90 stops. In other words, this command does not exit the currently
91 executing function unless you are positioned after the last sexp.
94 Step into the function or macro after point after first ensuring
95 that it is instrumented. It does this by calling
96 `edebug-on-entry' and then switching to `go' mode.
98 Although the automatic instrumentation is convenient, it is not
99 later automatically uninstrumented.
102 Proceed to the stop point near where point is using a temporary
103 breakpoint (`edebug-goto-here').
105 All the commands in this section may fail to work as expected in case
106 of nonlocal exit, because a nonlocal exit can bypass the temporary
107 breakpoint where you expected the program to stop.
110 File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug
115 Some miscellaneous commands are described here.
118 Display the help message for Edebug (`edebug-help').
121 Abort one level back to the previous command level
122 (`abort-recursive-edit').
125 Return to the top level editor command loop (`top-level'). This
126 exits all recursive editing levels, including all levels of Edebug
127 activity. However, instrumented code protected with
128 `unwind-protect' or `condition-case' forms may resume debugging.
131 Like `q' but don't stop even for protected code
132 (`top-level-nonstop').
135 Redisplay the most recently known expression result in the echo
136 area (`edebug-previous-result').
139 Display a backtrace, excluding Edebug's own functions for clarity
140 (`edebug-backtrace').
142 You cannot use debugger commands in the backtrace buffer in Edebug
143 as you would in the standard debugger.
145 The backtrace buffer is killed automatically when you continue
148 From the Edebug recursive edit, you may invoke commands that activate
149 Edebug again recursively. Any time Edebug is active, you can quit to
150 the top level with `q' or abort one recursive edit level with `C-]'.
151 You can display a backtrace of all the pending evaluations with `d'.
154 File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug
159 There are three more ways to stop execution once it has started:
160 breakpoints, the global break condition, and embedded breakpoints.
162 While using Edebug, you can specify "breakpoints" in the program you
163 are testing: points where execution should stop. You can set a
164 breakpoint at any stop point, as defined in *Note Using Edebug::. For
165 setting and unsetting breakpoints, the stop point that is affected is
166 the first one at or after point in the source code buffer. Here are the
167 Edebug commands for breakpoints:
170 Set a breakpoint at the stop point at or after point
171 (`edebug-set-breakpoint'). If you use a prefix argument, the
172 breakpoint is temporary (it turns off the first time it stops the
176 Unset the breakpoint (if any) at the stop point at or after the
177 current point (`edebug-unset-breakpoint').
180 Set a conditional breakpoint which stops the program only if
181 CONDITION evaluates to a non-`nil' value
182 (`edebug-set-conditional-breakpoint'). If you use a prefix
183 argument, the breakpoint is temporary (it turns off the first time
184 it stops the program).
187 Move point to the next breakpoint in the definition
188 (`edebug-next-breakpoint').
190 While in Edebug, you can set a breakpoint with `b' and unset one
191 with `u'. First you must move point to a position at or before the
192 desired Edebug stop point, then hit the key to change the breakpoint.
193 Unsetting a breakpoint that has not been set does nothing.
195 Reevaluating or reinstrumenting a definition clears all its
198 A "conditional breakpoint" tests a condition each time the program
199 gets there. To set a conditional breakpoint, use `x', and specify the
200 condition expression in the minibuffer. Setting a conditional
201 breakpoint at a stop point that already has a conditional breakpoint
202 puts the current condition expression in the minibuffer so you can edit
205 You can make both conditional and unconditional breakpoints
206 "temporary" by using a prefix arg to the command to set the breakpoint.
207 After breaking at a temporary breakpoint, it is automatically cleared.
209 Edebug always stops or pauses at a breakpoint except when the Edebug
210 mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely.
212 To find out where your breakpoints are, use `B', which moves point
213 to the next breakpoint in the definition following point, or to the
214 first breakpoint if there are no following breakpoints. This command
215 does not continue execution--it just moves point in the buffer.
219 * Global Break Condition:: Breaking on an event.
220 * Embedded Breakpoints:: Embedding breakpoints in code.
223 File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints
225 Global Break Condition
226 ......................
228 In contrast to breaking when execution reaches specified locations,
229 you can also cause a break when a certain event occurs. The "global
230 break condition" is a condition that is repeatedly evaluated at every
231 stop point. If it evaluates to a non-`nil' value, then execution is
232 stopped or paused depending on the execution mode, just like a
233 breakpoint. Any errors that might occur as a result of evaluating the
234 condition are ignored, as if the result were `nil'.
236 You can set or edit the condition expression, stored in
237 `edebug-global-break-condition', using `X'
238 (`edebug-set-global-break-condition').
240 Using the global break condition is perhaps the fastest way to find
241 where in your code some event occurs, but since it is rather expensive
242 you should reset the condition to `nil' when not in use.
245 File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints
250 Since all breakpoints in a definition are cleared each time you
251 reinstrument it, you might rather create an "embedded breakpoint" which
252 is simply a call to the function `edebug'. You can, of course, make
253 such a call conditional. For example, in the `fac' function, insert
254 the first line as shown below to stop when the argument reaches zero:
257 (if (= n 0) (edebug))
262 When the `fac' definition is instrumented and the function is
263 called, Edebug will stop before the call to `edebug'. Depending on the
264 execution mode, Edebug will stop or pause.
266 However, if no instrumented code is being executed, calling `edebug'
267 will instead invoke `debug'. Calling `debug' will always invoke the
268 standard backtrace debugger.
271 File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug
276 An error may be signaled by subroutines or XEmacs Lisp code. If a
277 signal is not handled by a `condition-case', this indicates an
278 unrecognized situation has occurred. If Edebug is not active when an
279 unhandled error is signaled, `debug' is run normally (if
280 `debug-on-error' is non-`nil'). But while Edebug is active,
281 `debug-on-error' and `debug-on-quit' are bound to `edebug-on-error' and
282 `edebug-on-quit', which are both `t' by default. Actually, if
283 `debug-on-error' already has a non-`nil' value, that value is still
286 It is best to change the values of `edebug-on-error' or
287 `edebug-on-quit' when Edebug is not active since their values won't be
288 used until the next time Edebug is invoked at a deeper command level.
289 If you only change `debug-on-error' or `debug-on-quit' while Edebug is
290 active, these changes will be forgotten when Edebug becomes inactive.
291 Furthermore, during Edebug's recursive edit, these variables are bound
292 to the values they had outside of Edebug.
294 Edebug shows you the last stop point that it knew about before the
295 error was signaled. This may be the location of a call to a function
296 which was not instrumented, within which the error actually occurred.
297 For an unbound variable error, the last known stop point might be quite
298 distant from the offending variable. If the cause of the error is not
299 obvious at first, note that you can also get a full backtrace inside of
300 Edebug (see *Note Edebug Misc::).
302 Edebug can also trap signals even if they are handled. If
303 `debug-on-error' is a list of signal names, Edebug will stop when any
304 of these errors are signaled. Edebug shows you the last known stop
305 point just as for unhandled errors. After you continue execution, the
306 error is signaled again (but without being caught by Edebug). Edebug
307 can only trap errors that are handled if they are signaled in Lisp code
308 (not subroutines) since it does so by temporarily replacing the
312 File: lispref.info, Node: Edebug Views, Next: Edebug Eval, Prev: Trapping Errors, Up: Edebug
317 The following Edebug commands let you view aspects of the buffer and
318 window status that obtained before entry to Edebug.
321 View the outside window configuration (`edebug-view-outside').
324 Temporarily display the outside current buffer with point at its
325 outside position (`edebug-bounce-point'). If prefix arg is
326 supplied, sit for that many seconds instead.
329 Move point back to the current stop point (`edebug-where') in the
330 source code buffer. Also, if you use this command in another
331 window displaying the same buffer, this window will be used
332 instead to display the buffer in the future.
335 Toggle the `edebug-save-windows' variable which indicates whether
336 the outside window configuration is saved and restored
337 (`edebug-toggle-save-windows'). Also, each time it is toggled on,
338 make the outside window configuration the same as the current
339 window configuration.
341 With a prefix argument, `edebug-toggle-save-windows' only toggles
342 saving and restoring of the selected window. To specify a window
343 that is not displaying the source code buffer, you must use
344 `C-xXW' from the global keymap.
346 You can view the outside window configuration with `v' or just
347 bounce to the current point in the current buffer with `p', even if it
348 is not normally displayed. After moving point, you may wish to pop
349 back to the stop point with `w' from a source code buffer.
351 By using `W' twice, Edebug again saves and restores the outside
352 window configuration, but to the current configuration. This is a
353 convenient way to, for example, add another buffer to be displayed
354 whenever Edebug is active. However, the automatic redisplay of
355 `*edebug*' and `*edebug-trace*' may conflict with the buffers you wish
356 to see unless you have enough windows open.
359 File: lispref.info, Node: Edebug Eval, Next: Eval List, Prev: Edebug Views, Up: Edebug
364 While within Edebug, you can evaluate expressions "as if" Edebug were
365 not running. Edebug tries to be invisible to the expression's
366 evaluation and printing. Evaluation of expressions that cause side
367 effects will work as expected except for things that Edebug explicitly
368 saves and restores. See *Note The Outside Context:: for details on this
369 process. Also see *Note Reading in Edebug:: and *Note Printing in
370 Edebug:: for topics related to evaluation.
373 Evaluate expression EXP in the context outside of Edebug
374 (`edebug-eval-expression'). In other words, Edebug tries to avoid
375 altering the effect of EXP.
378 Evaluate expression EXP in the context of Edebug itself.
381 Evaluate the expression before point, in the context outside of
382 Edebug (`edebug-eval-last-sexp').
384 Edebug supports evaluation of expressions containing references to
385 lexically bound symbols created by the following constructs in `cl.el'
386 (version 2.03 or later): `lexical-let', `macrolet', and
390 File: lispref.info, Node: Eval List, Next: Reading in Edebug, Prev: Edebug Eval, Up: Edebug
392 Evaluation List Buffer
393 ----------------------
395 You can use the "evaluation list buffer", called `*edebug*', to
396 evaluate expressions interactively. You can also set up the
397 "evaluation list" of expressions to be evaluated automatically each
398 time Edebug updates the display.
401 Switch to the evaluation list buffer `*edebug*'
402 (`edebug-visit-eval-list').
404 In the `*edebug*' buffer you can use the commands of Lisp
405 Interaction as well as these special commands:
408 Evaluate the expression before point, in the outside context, and
409 insert the value in the buffer (`edebug-eval-print-last-sexp').
412 Evaluate the expression before point, in the context outside of
413 Edebug (`edebug-eval-last-sexp').
416 Build a new evaluation list from the first expression of each
417 group, reevaluate and redisplay (`edebug-update-eval-list').
418 Groups are separated by comment lines.
421 Delete the evaluation list group that point is in
422 (`edebug-delete-eval-item').
425 Switch back to the source code buffer at the current stop point
428 You can evaluate expressions in the evaluation list window with
429 `LFD' or `C-x C-e', just as you would in `*scratch*'; but they are
430 evaluated in the context outside of Edebug.
432 The expressions you enter interactively (and their results) are lost
433 when you continue execution unless you add them to the evaluation list
434 with `C-c C-u'. This command builds a new list from the first
435 expression of each "evaluation list group". Groups are separated by
436 comment lines. Be careful not to add expressions that execute
437 instrumented code otherwise an infinite loop will result.
439 When the evaluation list is redisplayed, each expression is displayed
440 followed by the result of evaluating it, and a comment line. If an
441 error occurs during an evaluation, the error message is displayed in a
442 string as if it were the result. Therefore expressions that, for
443 example, use variables not currently valid do not interrupt your
446 Here is an example of what the evaluation list window looks like
447 after several expressions have been added to it:
451 ;---------------------------------------------------------------
453 #<window 16 on *scratch*>
454 ;---------------------------------------------------------------
457 ;---------------------------------------------------------------
459 "Symbol's value as variable is void: bad-var"
460 ;---------------------------------------------------------------
463 ;---------------------------------------------------------------
466 ;---------------------------------------------------------------
468 To delete a group, move point into it and type `C-c C-d', or simply
469 delete the text for the group and update the evaluation list with `C-c
470 C-u'. When you add a new group, be sure it is separated from its
471 neighbors by a comment line.
473 After selecting `*edebug*', you can return to the source code buffer
474 with `C-c C-w'. The `*edebug*' buffer is killed when you continue
475 execution, and recreated next time it is needed.
478 File: lispref.info, Node: Reading in Edebug, Next: Printing in Edebug, Prev: Eval List, Up: Edebug
483 To instrument a form, Edebug first reads the whole form. Edebug
484 replaces the standard Lisp Reader with its own reader that remembers the
485 positions of expressions. This reader is used by the Edebug
486 replacements for `eval-region', `eval-defun', `eval-buffer', and
487 `eval-current-buffer'.
489 Another package, `cl-read.el', replaces the standard reader with one
490 that understands Common Lisp reader macros. If you use that package,
491 Edebug will automatically load `edebug-cl-read.el' to provide
492 corresponding reader macros that remember positions of expressions. If
493 you define new reader macros, you will have to define similar reader
497 File: lispref.info, Node: Printing in Edebug, Next: Tracing, Prev: Reading in Edebug, Up: Edebug
502 If the result of an expression in your program contains a circular
503 reference, you may get an error when Edebug attempts to print it. You
504 can set `print-length' to a non-zero value to limit the print length of
505 lists (the number of cdrs), and in Emacs 19, set `print-level' to a
506 non-zero value to limit the print depth of lists. But you can print
507 such circular structures and structures that share elements more
508 informatively by using the `cust-print' package.
510 To load `cust-print' and activate custom printing only for Edebug,
511 simply use the command `M-x edebug-install-custom-print'. To restore
512 the standard print functions, use `M-x edebug-uninstall-custom-print'.
513 You can also activate custom printing for printing in any Lisp code;
514 see the package for details.
516 Here is an example of code that creates a circular structure:
519 (edebug-install-custom-print)
523 Edebug will print the result of the `setcar' as `Result: #1=(#1#
524 y)'. The `#1=' notation names the structure that follows it, and the
525 `#1#' notation references the previously named structure. This
526 notation is used for any shared elements of lists or vectors.
528 Independent of whether `cust-print' is active, while printing
529 results Edebug binds `print-length', `print-level', and `print-circle'
530 to `edebug-print-length' (`50'), `edebug-print-level' (`50'), and
531 `edebug-print-circle' (`t') respectively, if these values are
532 non-`nil'. Also, `print-readably' is bound to `nil' since some objects
533 simply cannot be printed readably.
536 File: lispref.info, Node: Tracing, Next: Coverage Testing, Prev: Printing in Edebug, Up: Edebug
541 In addition to automatic stepping through source code, which is also
542 called _tracing_ (see *Note Edebug Execution Modes::), Edebug can
543 produce a traditional trace listing of execution in a separate buffer,
546 If the variable `edebug-trace' is non-`nil', each function entry and
547 exit adds lines to the trace buffer. On function entry, Edebug prints
548 `::::{' followed by the function name and argument values. On function
549 exit, Edebug prints `::::}' followed by the function name and result of
550 the function. The number of `:'s is computed from the recursion depth.
551 The balanced braces in the trace buffer can be used to find the
552 matching beginning or end of function calls. These displays may be
553 customized by replacing the functions `edebug-print-trace-before' and
554 `edebug-print-trace-after', which take an arbitrary message string to
557 The macro `edebug-tracing' provides tracing similar to function
558 enter and exit tracing, but for arbitrary expressions. This macro
559 should be explicitly inserted by you around expressions you wish to
560 trace the execution of. The first argument is a message string
561 (evaluated), and the rest are expressions to evaluate. The result of
562 the last expression is returned.
564 Finally, you can insert arbitrary strings into the trace buffer with
565 explicit calls to `edebug-trace'. The arguments of this function are
566 the same as for `message', but a newline is always inserted after each
567 string printed in this way.
569 `edebug-tracing' and `edebug-trace' insert lines in the trace buffer
570 even if Edebug is not active. Every time the trace buffer is added to,
571 the window is scrolled to show the last lines inserted. (There may be
572 some display problems if you use tracing along with the evaluation
576 File: lispref.info, Node: Coverage Testing, Next: The Outside Context, Prev: Tracing, Up: Edebug
581 Edebug provides a rudimentary coverage tester and display of
582 execution frequency. Frequency counts are always accumulated, both
583 before and after evaluation of each instrumented expression, even if
584 the execution mode is `Go-nonstop'. Coverage testing is only done if
585 the option `edebug-test-coverage' is non-`nil' because this is
586 relatively expensive. Both data sets are displayed by `M-x
587 edebug-display-freq-count'.
589 - Command: edebug-display-freq-count
590 Display the frequency count data for each line of the current
591 definition. The frequency counts are inserted as comment lines
592 after each line, and you can undo all insertions with one `undo'
593 command. The counts are inserted starting under the `(' before an
594 expression or the `)' after an expression, or on the last char of
595 a symbol. The counts are only displayed when they differ from
596 previous counts on the same line.
598 If coverage is being tested, whenever all known results of an
599 expression are `eq', the char `=' will be appended after the count
600 for that expression. Note that this is always the case for an
601 expression only evaluated once.
603 To clear the frequency count and coverage data for a definition,
607 For example, after evaluating `(fac 5)' with an embedded breakpoint,
608 and setting `edebug-test-coverage' to `t', when the breakpoint is
609 reached, the frequency data is looks like this:
612 (if (= n 0) (edebug))
621 The comment lines show that `fac' has been called 6 times. The
622 first `if' statement has returned 5 times with the same result each
623 time, and the same is true for the condition on the second `if'. The
624 recursive call of `fac' has not returned at all.
627 File: lispref.info, Node: The Outside Context, Next: Instrumenting Macro Calls, Prev: Coverage Testing, Up: Edebug
632 Edebug tries to be transparent to the program you are debugging. In
633 addition, most evaluations you do within Edebug (see *Note Edebug
634 Eval::) occur in the same outside context which is temporarily restored
635 for the evaluation. But Edebug is not completely successful and this
636 section explains precisely how it fails. Edebug operation unavoidably
637 alters some data in XEmacs, and this can interfere with debugging
638 certain programs. Also notice that Edebug's protection against change
639 of outside data means that any side effects _intended_ by the user in
640 the course of debugging will be defeated.
644 * Checking Whether to Stop:: When Edebug decides what to do.
645 * Edebug Display Update:: When Edebug updates the display.
646 * Edebug Recursive Edit:: When Edebug stops execution.
649 File: lispref.info, Node: Checking Whether to Stop, Next: Edebug Display Update, Up: The Outside Context
651 Checking Whether to Stop
652 ........................
654 Whenever Edebug is entered just to think about whether to take some
655 action, it needs to save and restore certain data.
657 * `max-lisp-eval-depth' and `max-specpdl-size' are both incremented
658 one time to reduce Edebug's impact on the stack. You could,
659 however, still run out of stack space when using Edebug.
661 * The state of keyboard macro execution is saved and restored. While
662 Edebug is active, `executing-macro' is bound to
663 `edebug-continue-kbd-macro'.
667 File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context
669 Edebug Display Update
670 .....................
672 When Edebug needs to display something (e.g., in trace mode), it
673 saves the current window configuration from "outside" Edebug. When you
674 exit Edebug (by continuing the program), it restores the previous window
677 XEmacs redisplays only when it pauses. Usually, when you continue
678 execution, the program comes back into Edebug at a breakpoint or after
679 stepping without pausing or reading input in between. In such cases,
680 XEmacs never gets a chance to redisplay the "outside" configuration.
681 What you see is the same window configuration as the last time Edebug
682 was active, with no interruption.
684 Entry to Edebug for displaying something also saves and restores the
685 following data, but some of these are deliberately not restored if an
686 error or quit signal occurs.
688 * Which buffer is current, and where point and mark are in the
689 current buffer are saved and restored.
691 * The Edebug Display Update, is saved and restored if
692 `edebug-save-windows' is non-`nil'. It is not restored on error
693 or quit, but the outside selected window _is_ reselected even on
694 error or quit in case a `save-excursion' is active. If the value
695 of `edebug-save-windows' is a list, only the listed windows are
698 The window start and horizontal scrolling of the source code
699 buffer are not restored, however, so that the display remains
702 * The value of point in each displayed buffer is saved and restored
703 if `edebug-save-displayed-buffer-points' is non-`nil'.
705 * The variables `overlay-arrow-position' and `overlay-arrow-string'
706 are saved and restored. So you can safely invoke Edebug from the
707 recursive edit elsewhere in the same buffer.
709 * `cursor-in-echo-area' is locally bound to `nil' so that the cursor
710 shows up in the window.
714 File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context
716 Edebug Recursive Edit
717 .....................
719 When Edebug is entered and actually reads commands from the user, it
720 saves (and later restores) these additional data:
722 * The current match data, for whichever buffer was current.
724 * `last-command', `this-command', `last-command-char',
725 `last-input-char', `last-input-event', `last-command-event',
726 `last-event-frame', `last-nonmenu-event', and `track-mouse' .
727 Commands used within Edebug do not affect these variables outside
730 The key sequence returned by `this-command-keys' is changed by
731 executing commands within Edebug and there is no way to reset the
732 key sequence from Lisp.
734 For Emacs 18, Edebug cannot save and restore the value of
735 `unread-command-char'. Entering Edebug while this variable has a
736 nontrivial value can interfere with execution of the program you
739 * Complex commands executed while in Edebug are added to the variable
740 `command-history'. In rare cases this can alter execution.
742 * Within Edebug, the recursion depth appears one deeper than the
743 recursion depth outside Edebug. This is not true of the
744 automatically updated evaluation list window.
746 * `standard-output' and `standard-input' are bound to `nil' by the
747 `recursive-edit', but Edebug temporarily restores them during
750 * The state of keyboard macro definition is saved and restored.
751 While Edebug is active, `defining-kbd-macro' is bound to
752 `edebug-continue-kbd-macro'.
756 File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug
758 Instrumenting Macro Calls
759 -------------------------
761 When Edebug instruments an expression that calls a Lisp macro, it
762 needs additional advice to do the job properly. This is because there
763 is no way to tell which subexpressions of the macro call may be
764 evaluated. (Evaluation may occur explicitly in the macro body, or when
765 the resulting expansion is evaluated, or any time later.) You must
766 explain the format of macro call arguments by using `def-edebug-spec' to
767 define an "Edebug specification" for each macro.
769 - Macro: def-edebug-spec macro specification
770 Specify which expressions of a call to macro MACRO are forms to be
771 evaluated. For simple macros, the SPECIFICATION often looks very
772 similar to the formal argument list of the macro definition, but
773 specifications are much more general than macro arguments.
775 The MACRO argument may actually be any symbol, not just a macro
778 Unless you are using Emacs 19 or XEmacs, this macro is only defined
779 in Edebug, so you may want to use the following which is
780 equivalent: `(put 'MACRO 'edebug-form-spec 'SPECIFICATION)'
782 Here is a simple example that defines the specification for the
783 `for' macro described in the XEmacs Lisp Reference Manual, followed by
784 an alternative, equivalent specification.
787 (symbolp "from" form "to" form "do" &rest form))
790 (symbolp ['from form] ['to form] ['do body]))
792 Here is a table of the possibilities for SPECIFICATION and how each
793 directs processing of arguments.
796 All arguments are instrumented for evaluation.
799 None of the arguments is instrumented.
802 The symbol must have an Edebug specification which is used instead.
803 This indirection is repeated until another kind of specification is
804 found. This allows you to inherit the specification for another
808 The elements of the list describe the types of the arguments of a
809 calling form. The possible elements of a specification list are
810 described in the following sections.
814 * Specification List:: How to specify complex patterns of evaluation.
815 * Backtracking:: What Edebug does when matching fails.
816 * Debugging Backquote:: Debugging Backquote
817 * Specification Examples:: To help understand specifications.
820 File: lispref.info, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls
825 A "specification list" is required for an Edebug specification if
826 some arguments of a macro call are evaluated while others are not. Some
827 elements in a specification list match one or more arguments, but others
828 modify the processing of all following elements. The latter, called
829 "keyword specifications", are symbols beginning with ``&'' (e.g.
832 A specification list may contain sublists which match arguments that
833 are themselves lists, or it may contain vectors used for grouping.
834 Sublists and groups thus subdivide the specification list into a
835 hierarchy of levels. Keyword specifications only apply to the
836 remainder of the sublist or group they are contained in and there is an
837 implicit grouping around a keyword specification and all following
838 elements in the sublist or group.
840 If a specification list fails at some level, then backtracking may
841 be invoked to find some alternative at a higher level, or if no
842 alternatives remain, an error will be signaled. See *Note
843 Backtracking:: for more details.
845 Edebug specifications provide at least the power of regular
846 expression matching. Some context-free constructs are also supported:
847 the matching of sublists with balanced parentheses, recursive
848 processing of forms, and recursion via indirect specifications.
850 Each element of a specification list may be one of the following,
851 with the corresponding type of argument:
854 A single unevaluated expression.
857 A single evaluated expression, which is instrumented.
860 A place as in the Common Lisp `setf' place argument. It will be
861 instrumented just like a form, but the macro is expected to strip
862 the instrumentation. Two functions, `edebug-unwrap' and
863 `edebug-unwrap*', are provided to strip the instrumentation one
864 level or recursively at all levels.
867 Short for `&rest form'. See `&rest' below.
870 A function form: either a quoted function symbol, a quoted lambda
871 expression, or a form (that should evaluate to a function symbol
872 or lambda expression). This is useful when function arguments
873 might be quoted with `quote' rather than `function' since the body
874 of a lambda expression will be instrumented either way.
877 An unquoted anonymous lambda expression.
880 All following elements in the specification list are optional; as
881 soon as one does not match, Edebug stops matching at this level.
883 To make just a few elements optional followed by non-optional
884 elements, use `[&optional SPECS...]'. To specify that several
885 elements should all succeed together, use `&optional [SPECS...]'.
886 See the `defun' example below.
889 All following elements in the specification list are repeated zero
890 or more times. All the elements need not match in the last
893 To repeat only a few elements, use `[&rest SPECS...]'. To specify
894 all elements must match on every repetition, use `&rest
898 Each of the following elements in the specification list is an
899 alternative, processed left to right until one matches. One of the
900 alternatives must match otherwise the `&or' specification fails.
902 Each list element following `&or' is a single alternative even if
903 it is a keyword specification. (This breaks the implicit grouping
904 rule.) To group two or more list elements as a single
905 alternative, enclose them in `[...]'.
908 Each of the following elements is matched as alternatives as if by
909 using `&or', but if any of them match, the specification fails.
910 If none of them match, nothing is matched, but the `¬'
911 specification succeeds.
914 Indicates that the specification is for a defining form. The
915 defining form itself is not instrumented (i.e. Edebug does not
916 stop before and after the defining form), but forms inside it
917 typically will be instrumented. The `&define' keyword should be
918 the first element in a list specification.
920 Additional specifications that may only appear after `&define' are
921 described here. See the `defun' example below.
924 The argument, a symbol, is the name of the defining form.
925 But a defining form need not be named at all, in which case a
926 unique name will be created for it.
928 The `name' specification may be used more than once in the
929 specification and each subsequent use will append the
930 corresponding symbol argument to the previous name with ``@''
931 between them. This is useful for generating unique but
932 meaningful names for definitions such as `defadvice' and
936 The element following `:name' should be a symbol; it is used
937 as an additional name component for the definition. This is
938 useful to add a unique, static component to the name of the
939 definition. It may be used more than once. No argument is
943 The argument, a symbol, is the name of an argument of the
944 defining form. However, lambda list keywords (symbols
945 starting with ``&'') are not allowed. See `lambda-list' and
949 This matches the whole argument list of an XEmacs Lisp lambda
950 expression, which is a list of symbols and the keywords
951 `&optional' and `&rest'
954 The argument is the body of code in a definition. This is
955 like `body', described above, but a definition body must be
956 instrumented with a different Edebug call that looks up
957 information associated with the definition. Use `def-body'
958 for the highest level list of forms within the definition.
961 The argument is a single, highest-level form in a definition.
962 This is like `def-body', except use this to match a single
963 form rather than a list of forms. As a special case,
964 `def-form' also means that tracing information is not output
965 when the form is executed. See the `interactive' example
969 This is successful when there are no more arguments to match at the
970 current argument list level; otherwise it fails. See sublist
971 specifications and the backquote example below.
974 No argument is matched but backtracking through the gate is
975 disabled while matching the remainder of the specifications at
976 this level. This is primarily used to generate more specific
977 syntax error messages. See *Note Backtracking:: for more details.
978 Also see the `let' example below.
981 Any other symbol in a specification list may be a predicate or an
982 indirect specification.
984 If the symbol has an Edebug specification, this "indirect
985 specification" should be either a list specification that is used
986 in place of the symbol, or a function that is called to process the
987 arguments. The specification may be defined with `def-edebug-spec'
988 just as for macros. See the `defun' example below.
990 Otherwise, the symbol should be a predicate. The predicate is
991 called with the argument and the specification fails if the
992 predicate fails. The argument is not instrumented.
994 Predicates that may be used include: `symbolp', `integerp',
995 `stringp', `vectorp', `atom' (which matches a number, string,
996 symbol, or vector), `keywordp', and `lambda-list-keywordp'. The
997 last two, defined in `edebug.el', test whether the argument is a
998 symbol starting with ``:'' and ``&'' respectively.
1001 Rather than matching a vector argument, a vector treats the
1002 ELEMENTS as a single "group specification".
1005 The argument should be a symbol named STRING. This specification
1006 is equivalent to the quoted symbol, `'SYMBOL', where the name of
1007 SYMBOL is the STRING, but the string form is preferred.
1009 `'SYMBOL or (quote SYMBOL)'
1010 The argument should be the symbol SYMBOL. But use a string
1011 specification instead.
1013 `(vector ELEMENTS...)'
1014 The argument should be a vector whose elements must match the
1015 ELEMENTS in the specification. See the backquote example below.
1018 Any other list is a "sublist specification" and the argument must
1019 be a list whose elements match the specification ELEMENTS.
1021 A sublist specification may be a dotted list and the corresponding
1022 list argument may then be a dotted list. Alternatively, the last
1023 cdr of a dotted list specification may be another sublist
1024 specification (via a grouping or an indirect specification, e.g.
1025 `(spec . [(more specs...)])') whose elements match the non-dotted
1026 list arguments. This is useful in recursive specifications such
1027 as in the backquote example below. Also see the description of a
1028 `nil' specification above for terminating such recursion.
1030 Note that a sublist specification of the form `(specs . nil)'
1031 means the same as `(specs)', and `(specs .
1032 (sublist-elements...))' means the same as `(specs
1033 sublist-elements...)'.
1036 File: lispref.info, Node: Backtracking, Next: Debugging Backquote, Prev: Specification List, Up: Instrumenting Macro Calls
1041 If a specification fails to match at some point, this does not
1042 necessarily mean a syntax error will be signaled; instead,
1043 "backtracking" will take place until all alternatives have been
1044 exhausted. Eventually every element of the argument list must be
1045 matched by some element in the specification, and every required element
1046 in the specification must match some argument.
1048 Backtracking is disabled for the remainder of a sublist or group when
1049 certain conditions occur, described below. Backtracking is reenabled
1050 when a new alternative is established by `&optional', `&rest', or
1051 `&or'. It is also reenabled initially when processing a sublist or
1052 group specification or an indirect specification.
1054 You might want to disable backtracking to commit to some alternative
1055 so that Edebug can provide a more specific syntax error message.
1056 Normally, if no alternative matches, Edebug reports that none matched,
1057 but if one alternative is committed to, Edebug can report how it failed
1060 First, backtracking is disabled while matching any of the form
1061 specifications (i.e. `form', `body', `def-form', and `def-body').
1062 These specifications will match any form so any error must be in the
1063 form itself rather than at a higher level.
1065 Second, backtracking is disabled after successfully matching a quoted
1066 symbol or string specification, since this usually indicates a
1067 recognized construct. If you have a set of alternative constructs that
1068 all begin with the same symbol, you can usually work around this
1069 constraint by factoring the symbol out of the alternatives, e.g.,
1070 `["foo" &or [first case] [second case] ...]'.
1072 Third, backtracking may be explicitly disabled by using the `gate'
1073 specification. This is useful when you know that no higher
1074 alternatives may apply.
1077 File: lispref.info, Node: Debugging Backquote, Next: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls
1082 Backquote (``') is a macro that results in an expression that may or
1083 may not be evaluated. It is often used to simplify the definition of a
1084 macro to return an expression that is evaluated, but Edebug does not
1085 know when this is the case. However, the forms inside unquotes (`,' and
1086 `,@') are evaluated and Edebug instruments them.
1088 Nested backquotes are supported by Edebug, but there is a limit on
1089 the support of quotes inside of backquotes. Quoted forms (with `'')
1090 are not normally evaluated, but if the quoted form appears immediately
1091 within `,' and `,@' forms, Edebug treats this as a backquoted form at
1092 the next higher level (even if there is not a next higher level - this
1093 is difficult to fix).
1095 If the backquoted forms happen to be code intended to be evaluated,
1096 you can have Edebug instrument them by using `edebug-`' instead of the
1097 regular ``'. Unquoted forms can always appear inside `edebug-`'
1098 anywhere a form is normally allowed. But `(, FORM)' may be used in two
1099 other places specially recognized by Edebug: wherever a predicate
1100 specification would match, and at the head of a list form in place of a
1101 function name or lambda expression. The FORM inside a spliced unquote,
1102 `(,@ FORM)', will be wrapped, but the unquote form itself will not be
1103 wrapped since this would interfere with the splicing.
1105 There is one other complication with using `edebug-`'. If the
1106 `edebug-`' call is in a macro and the macro may be called from code
1107 that is also instrumented, and if unquoted forms contain any macro
1108 arguments bound to instrumented forms, then you should modify the
1109 specification for the macro as follows: the specifications for those
1110 arguments must use `def-form' instead of `form'. (This is to
1111 reestablish the Edebugging context for those external forms.)
1113 For example, the `for' macro (*note Problems with Macros: ()Problems
1114 with Macros.) is shown here but with `edebug-`' substituted for regular
1118 (list 'setq var (list '1+ var)))
1120 (defmacro for (var from init to final do &rest body)
1121 (let ((tempvar (make-symbol "max")))
1122 (edebug-` (let (((, var) (, init))
1123 ((, tempvar) (, final)))
1124 (while (<= (, var) (, tempvar))
1128 Here is the corresponding modified Edebug specification and some code
1129 that calls the macro:
1131 (def-edebug-spec for
1132 (symbolp "from" def-form "to" def-form "do" &rest def-form))
1135 (for i from n to (* n (+ n 1)) do
1138 After instrumenting the `for' macro and the macro call, Edebug first
1139 steps to the beginning of the macro call, then into the macro body,
1140 then through each of the unquoted expressions in the backquote showing
1141 the expressions that will be embedded in the backquote form. Then when
1142 the macro expansion is evaluated, Edebug will step through the `let'
1143 form and each time it gets to an unquoted form, it will jump back to an
1144 argument of the macro call to step through that expression. Finally
1145 stepping will continue after the macro call. Even more convoluted
1146 execution paths may result when using anonymous functions.
1148 When the result of an expression is an instrumented expression, it is
1149 difficult to see the expression inside the instrumentation. So you may
1150 want to set the option `edebug-unwrap-results' to a non-`nil' value
1151 while debugging such expressions, but it would slow Edebug down to
1155 File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls
1157 Specification Examples
1158 ......................
1160 Here we provide several examples of Edebug specifications to show
1161 many of its capabilities.
1163 A `let' special form has a sequence of bindings and a body. Each of
1164 the bindings is either a symbol or a sublist with a symbol and optional
1165 value. In the specification below, notice the `gate' inside of the
1166 sublist to prevent backtracking.
1168 (def-edebug-spec let
1170 &or symbolp (gate symbolp &optional form))
1173 Edebug uses the following specifications for `defun' and `defmacro'
1174 and the associated argument list and `interactive' specifications. It
1175 is necessary to handle the expression argument of an interactive form
1176 specially since it is actually evaluated outside of the function body.
1178 (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec
1179 (def-edebug-spec defun
1180 (&define name lambda-list
1181 [&optional stringp] ; Match the doc string, if present.
1182 [&optional ("interactive" interactive)]
1185 (def-edebug-spec lambda-list
1187 [&optional ["&optional" arg &rest arg]]
1188 &optional ["&rest" arg]
1191 (def-edebug-spec interactive
1192 (&optional &or stringp def-form)) ; Notice: `def-form'
1194 The specification for backquote below illustrates how to match
1195 dotted lists and use `nil' to terminate recursion. It also illustrates
1196 how components of a vector may be matched. (The actual specification
1197 provided by Edebug does not support dotted lists because doing so
1198 causes very deep recursion that could fail.)
1200 (def-edebug-spec ` (backquote-form)) ;; alias just for clarity
1202 (def-edebug-spec backquote-form
1203 (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
1204 (backquote-form . [&or nil backquote-form])
1205 (vector &rest backquote-form)
projects / chise / xemacs-chise.git- / blob