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: Error Debugging, Next: Infinite Loops, Up: Debugger
55 Entering the Debugger on an Error
56 ---------------------------------
58 The most important time to enter the debugger is when a Lisp error
59 happens. This allows you to investigate the immediate causes of the
62 However, entry to the debugger is not a normal consequence of an
63 error. Many commands frequently get Lisp errors when invoked in
64 inappropriate contexts (such as `C-f' at the end of the buffer) and
65 during ordinary editing it would be very unpleasant to enter the
66 debugger each time this happens. If you want errors to enter the
67 debugger, set the variable `debug-on-error' to non-`nil'.
69 - User Option: debug-on-error
70 This variable determines whether the debugger is called when an
71 error is signaled and not handled. If `debug-on-error' is `t', all
72 errors call the debugger. If it is `nil', none call the debugger.
74 The value can also be a list of error conditions that should call
75 the debugger. For example, if you set it to the list
76 `(void-variable)', then only errors about a variable that has no
77 value invoke the debugger.
79 When this variable is non-`nil', Emacs does not catch errors that
80 happen in process filter functions and sentinels. Therefore, these
81 errors also can invoke the debugger. *Note Processes::.
83 - User Option: debug-on-signal
84 This variable is similar to `debug-on-error' but breaks whenever
85 an error is signalled, regardless of whether it would be handled.
87 - User Option: debug-ignored-errors
88 This variable specifies certain kinds of errors that should not
89 enter the debugger. Its value is a list of error condition
90 symbols and/or regular expressions. If the error has any of those
91 condition symbols, or if the error message matches any of the
92 regular expressions, then that error does not enter the debugger,
93 regardless of the value of `debug-on-error'.
95 The normal value of this variable lists several errors that happen
96 often during editing but rarely result from bugs in Lisp programs.
98 To debug an error that happens during loading of the `.emacs' file,
99 use the option `-debug-init', which binds `debug-on-error' to `t' while
100 `.emacs' is loaded and inhibits use of `condition-case' to catch init
103 If your `.emacs' file sets `debug-on-error', the effect may not last
104 past the end of loading `.emacs'. (This is an undesirable byproduct of
105 the code that implements the `-debug-init' command line option.) The
106 best way to make `.emacs' set `debug-on-error' permanently is with
107 `after-init-hook', like this:
109 (add-hook 'after-init-hook
110 '(lambda () (setq debug-on-error t)))
113 File: lispref.info, Node: Infinite Loops, Next: Function Debugging, Prev: Error Debugging, Up: Debugger
115 Debugging Infinite Loops
116 ------------------------
118 When a program loops infinitely and fails to return, your first
119 problem is to stop the loop. On most operating systems, you can do this
120 with `C-g', which causes quit.
122 Ordinary quitting gives no information about why the program was
123 looping. To get more information, you can set the variable
124 `debug-on-quit' to non-`nil'. Quitting with `C-g' is not considered an
125 error, and `debug-on-error' has no effect on the handling of `C-g'.
126 Likewise, `debug-on-quit' has no effect on errors.
128 Once you have the debugger running in the middle of the infinite
129 loop, you can proceed from the debugger using the stepping commands.
130 If you step through the entire loop, you will probably get enough
131 information to solve the problem.
133 - User Option: debug-on-quit
134 This variable determines whether the debugger is called when `quit'
135 is signaled and not handled. If `debug-on-quit' is non-`nil',
136 then the debugger is called whenever you quit (that is, type
137 `C-g'). If `debug-on-quit' is `nil', then the debugger is not
138 called when you quit. *Note Quitting::.
141 File: lispref.info, Node: Function Debugging, Next: Explicit Debug, Prev: Infinite Loops, Up: Debugger
143 Entering the Debugger on a Function Call
144 ----------------------------------------
146 To investigate a problem that happens in the middle of a program, one
147 useful technique is to enter the debugger whenever a certain function is
148 called. You can do this to the function in which the problem occurs,
149 and then step through the function, or you can do this to a function
150 called shortly before the problem, step quickly over the call to that
151 function, and then step through its caller.
153 - Command: debug-on-entry function-name
154 This function requests FUNCTION-NAME to invoke the debugger each
155 time it is called. It works by inserting the form `(debug
156 'debug)' into the function definition as the first form.
158 Any function defined as Lisp code may be set to break on entry,
159 regardless of whether it is interpreted code or compiled code. If
160 the function is a command, it will enter the debugger when called
161 from Lisp and when called interactively (after the reading of the
162 arguments). You can't debug primitive functions (i.e., those
163 written in C) this way.
165 When `debug-on-entry' is called interactively, it prompts for
166 FUNCTION-NAME in the minibuffer.
168 If the function is already set up to invoke the debugger on entry,
169 `debug-on-entry' does nothing.
171 *Please note:* if you redefine a function after using
172 `debug-on-entry' on it, the code to enter the debugger is lost.
174 `debug-on-entry' returns FUNCTION-NAME.
178 (* n (fact (1- n)))))
180 (debug-on-entry 'fact)
184 ------ Buffer: *Backtrace* ------
187 eval-region(4870 4878 t)
191 eval-insert-last-sexp(nil)
192 * call-interactively(eval-insert-last-sexp)
193 ------ Buffer: *Backtrace* ------
195 (symbol-function 'fact)
197 (debug (quote debug))
198 (if (zerop n) 1 (* n (fact (1- n)))))
200 - Command: cancel-debug-on-entry function-name
201 This function undoes the effect of `debug-on-entry' on
202 FUNCTION-NAME. When called interactively, it prompts for
203 FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the
204 empty string, it cancels debugging for all functions.
206 If `cancel-debug-on-entry' is called more than once on the same
207 function, the second call does nothing. `cancel-debug-on-entry'
208 returns FUNCTION-NAME.
211 File: lispref.info, Node: Explicit Debug, Next: Using Debugger, Prev: Function Debugging, Up: Debugger
213 Explicit Entry to the Debugger
214 ------------------------------
216 You can cause the debugger to be called at a certain point in your
217 program by writing the expression `(debug)' at that point. To do this,
218 visit the source file, insert the text `(debug)' at the proper place,
219 and type `C-M-x'. Be sure to undo this insertion before you save the
222 The place where you insert `(debug)' must be a place where an
223 additional form can be evaluated and its value ignored. (If the value
224 of `(debug)' isn't ignored, it will alter the execution of the
225 program!) The most common suitable places are inside a `progn' or an
226 implicit `progn' (*note Sequencing::).
229 File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
234 When the debugger is entered, it displays the previously selected
235 buffer in one window and a buffer named `*Backtrace*' in another
236 window. The backtrace buffer contains one line for each level of Lisp
237 function execution currently going on. At the beginning of this buffer
238 is a message describing the reason that the debugger was invoked (such
239 as the error message and associated data, if it was invoked due to an
242 The backtrace buffer is read-only and uses a special major mode,
243 Debugger mode, in which letters are defined as debugger commands. The
244 usual XEmacs editing commands are available; thus, you can switch
245 windows to examine the buffer that was being edited at the time of the
246 error, switch buffers, visit files, or do any other sort of editing.
247 However, the debugger is a recursive editing level (*note Recursive
248 Editing::) and it is wise to go back to the backtrace buffer and exit
249 the debugger (with the `q' command) when you are finished with it.
250 Exiting the debugger gets out of the recursive edit and kills the
253 The backtrace buffer shows you the functions that are executing and
254 their argument values. It also allows you to specify a stack frame by
255 moving point to the line describing that frame. (A stack frame is the
256 place where the Lisp interpreter records information about a particular
257 invocation of a function.) The frame whose line point is on is
258 considered the "current frame". Some of the debugger commands operate
259 on the current frame.
261 The debugger itself must be run byte-compiled, since it makes
262 assumptions about how many stack frames are used for the debugger
263 itself. These assumptions are false if the debugger is running
267 File: lispref.info, Node: Debugger Commands, Next: Invoking the Debugger, Prev: Using Debugger, Up: Debugger
272 Inside the debugger (in Debugger mode), these special commands are
273 available in addition to the usual cursor motion commands. (Keep in
274 mind that all the usual facilities of XEmacs, such as switching windows
275 or buffers, are still available.)
277 The most important use of debugger commands is for stepping through
278 code, so that you can see how control flows. The debugger can step
279 through the control structures of an interpreted function, but cannot do
280 so in a byte-compiled function. If you would like to step through a
281 byte-compiled function, replace it with an interpreted definition of the
282 same function. (To do this, visit the source file for the function and
283 type `C-M-x' on its definition.)
285 Here is a list of Debugger mode commands:
288 Exit the debugger and continue execution. This resumes execution
289 of the program as if the debugger had never been entered (aside
290 from the effect of any variables or data structures you may have
291 changed while inside the debugger).
293 Continuing when an error or quit was signalled will cause the
294 normal action of the signalling to take place. If you do not want
295 this to happen, but instead want the program execution to continue
296 as if the call to `signal' did not occur, use the `r' command.
299 Continue execution, but enter the debugger the next time any Lisp
300 function is called. This allows you to step through the
301 subexpressions of an expression, seeing what values the
302 subexpressions compute, and what else they do.
304 The stack frame made for the function call which enters the
305 debugger in this way will be flagged automatically so that the
306 debugger will be called again when the frame is exited. You can
307 use the `u' command to cancel this flag.
310 Flag the current frame so that the debugger will be entered when
311 the frame is exited. Frames flagged in this way are marked with
312 stars in the backtrace buffer.
315 Don't enter the debugger when the current frame is exited. This
316 cancels a `b' command on that frame.
319 Read a Lisp expression in the minibuffer, evaluate it, and print
320 the value in the echo area. The debugger alters certain important
321 variables, and the current buffer, as part of its operation; `e'
322 temporarily restores their outside-the-debugger values so you can
323 examine them. This makes the debugger more transparent. By
324 contrast, `M-:' does nothing special in the debugger; it shows you
325 the variable values within the debugger.
328 Terminate the program being debugged; return to top-level XEmacs
331 If the debugger was entered due to a `C-g' but you really want to
332 quit, and not debug, use the `q' command.
335 Return a value from the debugger. The value is computed by
336 reading an expression with the minibuffer and evaluating it.
338 The `r' command is useful when the debugger was invoked due to exit
339 from a Lisp call frame (as requested with `b'); then the value
340 specified in the `r' command is used as the value of that frame.
341 It is also useful if you call `debug' and use its return value.
343 If the debugger was entered at the beginning of a function call,
344 `r' has the same effect as `c', and the specified return value
347 If the debugger was entered through a call to `signal' (i.e. as a
348 result of an error or quit), then returning a value will cause the
349 call to `signal' itself to return, rather than throwing to
350 top-level or invoking a handler, as is normal. This allows you to
351 correct an error (e.g. the type of an argument was wrong) or
352 continue from a `debug-on-quit' as if it never happened.
354 Note that some errors (e.g. any error signalled using the `error'
355 function, and many errors signalled from a primitive function) are
356 not continuable. If you return a value from them and continue
357 execution, then the error will immediately be signalled again.
358 Other errors (e.g. wrong-type-argument errors) will be continually
359 resignalled until the problem is corrected.
362 File: lispref.info, Node: Invoking the Debugger, Next: Internals of Debugger, Prev: Debugger Commands, Up: Debugger
364 Invoking the Debugger
365 ---------------------
367 Here we describe fully the function used to invoke the debugger.
369 - Function: debug &rest debugger-args
370 This function enters the debugger. It switches buffers to a buffer
371 named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
372 recursive entry to the debugger, etc.), and fills it with
373 information about the stack of Lisp function calls. It then
374 enters a recursive edit, showing the backtrace buffer in Debugger
377 The Debugger mode `c' and `r' commands exit the recursive edit;
378 then `debug' switches back to the previous buffer and returns to
379 whatever called `debug'. This is the only way the function
380 `debug' can return to its caller.
382 If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
383 if it is not one of the special values in the table below), then
384 `debug' displays the rest of its arguments at the top of the
385 `*Backtrace*' buffer. This mechanism is used to display a message
388 However, if the first argument passed to `debug' is one of the
389 following special values, then it has special significance.
390 Normally, these values are passed to `debug' only by the internals
391 of XEmacs and the debugger, and not by programmers calling `debug'.
393 The special values are:
396 A first argument of `lambda' means `debug' was called because
397 of entry to a function when `debug-on-next-call' was
398 non-`nil'. The debugger displays `Entering:' as a line of
399 text at the top of the buffer.
402 `debug' as first argument indicates a call to `debug' because
403 of entry to a function that was set to debug on entry. The
404 debugger displays `Entering:', just as in the `lambda' case.
405 It also marks the stack frame for that function so that it
406 will invoke the debugger when exited.
409 When the first argument is `t', this indicates a call to
410 `debug' due to evaluation of a list form when
411 `debug-on-next-call' is non-`nil'. The debugger displays the
412 following as the top line in the buffer:
414 Beginning evaluation of function call form:
417 When the first argument is `exit', it indicates the exit of a
418 stack frame previously marked to invoke the debugger on exit.
419 The second argument given to `debug' in this case is the
420 value being returned from the frame. The debugger displays
421 `Return value:' on the top line of the buffer, followed by
422 the value being returned.
425 When the first argument is `error', the debugger indicates
426 that it is being entered because an error or `quit' was
427 signaled and not handled, by displaying `Signaling:' followed
428 by the error signaled and any arguments to `signal'. For
431 (let ((debug-on-error t))
434 ------ Buffer: *Backtrace* ------
435 Signaling: (arith-error)
438 ------ Buffer: *Backtrace* ------
440 If an error was signaled, presumably the variable
441 `debug-on-error' is non-`nil'. If `quit' was signaled, then
442 presumably the variable `debug-on-quit' is non-`nil'.
445 Use `nil' as the first of the DEBUGGER-ARGS when you want to
446 enter the debugger explicitly. The rest of the DEBUGGER-ARGS
447 are printed on the top line of the buffer. You can use this
448 feature to display messages--for example, to remind yourself
449 of the conditions under which `debug' is called.
452 File: lispref.info, Node: Internals of Debugger, Prev: Invoking the Debugger, Up: Debugger
454 Internals of the Debugger
455 -------------------------
457 This section describes functions and variables used internally by the
461 The value of this variable is the function to call to invoke the
462 debugger. Its value must be a function of any number of arguments
463 (or, more typically, the name of a function). Presumably this
464 function will enter some kind of debugger. The default value of
465 the variable is `debug'.
467 The first argument that Lisp hands to the function indicates why it
468 was called. The convention for arguments is detailed in the
469 description of `debug'.
471 - Command: backtrace &optional stream detailed
472 This function prints a trace of Lisp function calls currently
473 active. This is the function used by `debug' to fill up the
474 `*Backtrace*' buffer. It is written in C, since it must have
475 access to the stack to determine which function calls are active.
476 The return value is always `nil'.
478 The backtrace is normally printed to `standard-output', but this
479 can be changed by specifying a value for STREAM. If DETAILED is
480 non-`nil', the backtrace also shows places where currently active
481 variable bindings, catches, condition-cases, and unwind-protects
482 were made as well as function calls.
484 In the following example, a Lisp expression calls `backtrace'
485 explicitly. This prints the backtrace to the stream
486 `standard-output': in this case, to the buffer `backtrace-output'.
487 Each line of the backtrace represents one function call. The
488 line shows the values of the function's arguments if they are all
489 known. If they are still being computed, the line says so. The
490 arguments of special forms are elided.
492 (with-output-to-temp-buffer "backtrace-output"
495 (setq var (eval '(progn
497 (list 'testing (backtrace))))))))
501 ----------- Buffer: backtrace-output ------------
503 (list ...computing arguments...)
505 eval((progn (1+ var) (list (quote testing) (backtrace))))
509 (with-output-to-temp-buffer ...)
510 eval-region(1973 2142 #<buffer *scratch*>)
511 byte-code("... for eval-print-last-sexp ...")
512 eval-print-last-sexp(nil)
513 * call-interactively(eval-print-last-sexp)
514 ----------- Buffer: backtrace-output ------------
516 The character `*' indicates a frame whose debug-on-exit flag is
519 - Variable: debug-on-next-call
520 If this variable is non-`nil', it says to call the debugger before
521 the next `eval', `apply' or `funcall'. Entering the debugger sets
522 `debug-on-next-call' to `nil'.
524 The `d' command in the debugger works by setting this variable.
526 - Function: backtrace-debug level flag
527 This function sets the debug-on-exit flag of the stack frame LEVEL
528 levels down the stack, giving it the value FLAG. If FLAG is
529 non-`nil', this will cause the debugger to be entered when that
530 frame later exits. Even a nonlocal exit through that frame will
533 This function is used only by the debugger.
535 - Variable: command-debug-status
536 This variable records the debugging status of the current
537 interactive command. Each time a command is called interactively,
538 this variable is bound to `nil'. The debugger can set this
539 variable to leave information for future debugger invocations
540 during the same command.
542 The advantage, for the debugger, of using this variable rather than
543 another global variable is that the data will never carry over to a
544 subsequent command invocation.
546 - Function: backtrace-frame frame-number
547 The function `backtrace-frame' is intended for use in Lisp
548 debuggers. It returns information about what computation is
549 happening in the stack frame FRAME-NUMBER levels down.
551 If that frame has not evaluated the arguments yet (or is a special
552 form), the value is `(nil FUNCTION ARG-FORMS...)'.
554 If that frame has evaluated its arguments and called its function
555 already, the value is `(t FUNCTION ARG-VALUES...)'.
557 In the return value, FUNCTION is whatever was supplied as the CAR
558 of the evaluated list, or a `lambda' expression in the case of a
559 macro call. If the function has a `&rest' argument, that is
560 represented as the tail of the list ARG-VALUES.
562 If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.
565 File: lispref.info, Node: Syntax Errors, Next: Compilation Errors, Prev: Debugger, Up: Debugging
567 Debugging Invalid Lisp Syntax
568 =============================
570 The Lisp reader reports invalid syntax, but cannot say where the real
571 problem is. For example, the error "End of file during parsing" in
572 evaluating an expression indicates an excess of open parentheses (or
573 square brackets). The reader detects this imbalance at the end of the
574 file, but it cannot figure out where the close parenthesis should have
575 been. Likewise, "Invalid read syntax: ")"" indicates an excess close
576 parenthesis or missing open parenthesis, but does not say where the
577 missing parenthesis belongs. How, then, to find what to change?
579 If the problem is not simply an imbalance of parentheses, a useful
580 technique is to try `C-M-e' at the beginning of each defun, and see if
581 it goes to the place where that defun appears to end. If it does not,
582 there is a problem in that defun.
584 However, unmatched parentheses are the most common syntax errors in
585 Lisp, and we can give further advice for those cases.
589 * Excess Open:: How to find a spurious open paren or missing close.
590 * Excess Close:: How to find a spurious close paren or missing open.
593 File: lispref.info, Node: Excess Open, Next: Excess Close, Up: Syntax Errors
595 Excess Open Parentheses
596 -----------------------
598 The first step is to find the defun that is unbalanced. If there is
599 an excess open parenthesis, the way to do this is to insert a close
600 parenthesis at the end of the file and type `C-M-b' (`backward-sexp').
601 This will move you to the beginning of the defun that is unbalanced.
602 (Then type `C-<SPC> C-_ C-u C-<SPC>' to set the mark there, undo the
603 insertion of the close parenthesis, and finally return to the mark.)
605 The next step is to determine precisely what is wrong. There is no
606 way to be sure of this except to study the program, but often the
607 existing indentation is a clue to where the parentheses should have
608 been. The easiest way to use this clue is to reindent with `C-M-q' and
611 Before you do this, make sure the defun has enough close parentheses.
612 Otherwise, `C-M-q' will get an error, or will reindent all the rest of
613 the file until the end. So move to the end of the defun and insert a
614 close parenthesis there. Don't use `C-M-e' to move there, since that
615 too will fail to work until the defun is balanced.
617 Now you can go to the beginning of the defun and type `C-M-q'.
618 Usually all the lines from a certain point to the end of the function
619 will shift to the right. There is probably a missing close parenthesis,
620 or a superfluous open parenthesis, near that point. (However, don't
621 assume this is true; study the code to make sure.) Once you have found
622 the discrepancy, undo the `C-M-q' with `C-_', since the old indentation
623 is probably appropriate to the intended parentheses.
625 After you think you have fixed the problem, use `C-M-q' again. If
626 the old indentation actually fit the intended nesting of parentheses,
627 and you have put back those parentheses, `C-M-q' should not change
631 File: lispref.info, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors
633 Excess Close Parentheses
634 ------------------------
636 To deal with an excess close parenthesis, first insert an open
637 parenthesis at the beginning of the file, back up over it, and type
638 `C-M-f' to find the end of the unbalanced defun. (Then type `C-<SPC>
639 C-_ C-u C-<SPC>' to set the mark there, undo the insertion of the open
640 parenthesis, and finally return to the mark.)
642 Then find the actual matching close parenthesis by typing `C-M-f' at
643 the beginning of the defun. This will leave you somewhere short of the
644 place where the defun ought to end. It is possible that you will find
645 a spurious close parenthesis in that vicinity.
647 If you don't see a problem at that point, the next thing to do is to
648 type `C-M-q' at the beginning of the defun. A range of lines will
649 probably shift left; if so, the missing open parenthesis or spurious
650 close parenthesis is probably near the first of those lines. (However,
651 don't assume this is true; study the code to make sure.) Once you have
652 found the discrepancy, undo the `C-M-q' with `C-_', since the old
653 indentation is probably appropriate to the intended parentheses.
655 After you think you have fixed the problem, use `C-M-q' again. If
656 the old indentation actually fit the intended nesting of parentheses,
657 and you have put back those parentheses, `C-M-q' should not change
661 File: lispref.info, Node: Compilation Errors, Next: Edebug, Prev: Syntax Errors, Up: Debugging
663 Debugging Problems in Compilation
664 =================================
666 When an error happens during byte compilation, it is normally due to
667 invalid syntax in the program you are compiling. The compiler prints a
668 suitable error message in the `*Compile-Log*' buffer, and then stops.
669 The message may state a function name in which the error was found, or
670 it may not. Either way, here is how to find out where in the file the
673 What you should do is switch to the buffer ` *Compiler Input*'.
674 (Note that the buffer name starts with a space, so it does not show up
675 in `M-x list-buffers'.) This buffer contains the program being
676 compiled, and point shows how far the byte compiler was able to read.
678 If the error was due to invalid Lisp syntax, point shows exactly
679 where the invalid syntax was _detected_. The cause of the error is not
680 necessarily near by! Use the techniques in the previous section to find
683 If the error was detected while compiling a form that had been read
684 successfully, then point is located at the end of the form. In this
685 case, this technique can't localize the error precisely, but can still
686 show you which function to check.
689 File: lispref.info, Node: Edebug, Prev: Compilation Errors, Up: Top
694 Edebug is a source-level debugger for XEmacs Lisp programs that
695 provides the following features:
697 * Step through evaluation, stopping before and after each expression.
699 * Set conditional or unconditional breakpoints, install embedded
700 breakpoints, or a global break event.
702 * Trace slow or fast stopping briefly at each stop point, or each
705 * Display expression results and evaluate expressions as if outside
706 of Edebug. Interface with the custom printing package for
707 printing circular structures.
709 * Automatically reevaluate a list of expressions and display their
710 results each time Edebug updates the display.
712 * Output trace info on function enter and exit.
714 * Errors stop before the source causing the error.
716 * Display backtrace without Edebug calls.
718 * Allow specification of argument evaluation for macros and defining
721 * Provide rudimentary coverage testing and display of frequency
725 The first three sections should tell you enough about Edebug to
726 enable you to use it.
730 * Using Edebug:: Introduction to use of Edebug.
731 * Instrumenting:: You must first instrument code.
732 * Edebug Execution Modes:: Execution modes, stopping more or less often.
733 * Jumping:: Commands to jump to a specified place.
734 * Edebug Misc:: Miscellaneous commands.
735 * Breakpoints:: Setting breakpoints to make the program stop.
736 * Trapping Errors:: trapping errors with Edebug.
737 * Edebug Views:: Views inside and outside of Edebug.
738 * Edebug Eval:: Evaluating expressions within Edebug.
739 * Eval List:: Automatic expression evaluation.
740 * Reading in Edebug:: Customization of reading.
741 * Printing in Edebug:: Customization of printing.
742 * Tracing:: How to produce tracing output.
743 * Coverage Testing:: How to test evaluation coverage.
744 * The Outside Context:: Data that Edebug saves and restores.
745 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
746 * Edebug Options:: Option variables for customizing Edebug.
749 File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug
754 To debug an XEmacs Lisp program with Edebug, you must first
755 "instrument" the Lisp code that you want to debug. If you want to just
756 try it now, load `edebug.el', move point into a definition and do `C-u
757 C-M-x' (`eval-defun' with a prefix argument). See *Note
758 Instrumenting:: for alternative ways to instrument code.
760 Once a function is instrumented, any call to the function activates
761 Edebug. Activating Edebug may stop execution and let you step through
762 the function, or it may update the display and continue execution while
763 checking for debugging commands, depending on the selected Edebug
764 execution mode. The initial execution mode is `step', by default,
765 which does stop execution. *Note Edebug Execution Modes::.
767 Within Edebug, you normally view an XEmacs buffer showing the source
768 of the Lisp function you are debugging. This is referred to as the
769 "source code buffer"--but note that it is not always the same buffer
770 depending on which function is currently being executed.
772 An arrow at the left margin indicates the line where the function is
773 executing. Point initially shows where within the line the function is
774 executing, but you can move point yourself.
776 If you instrument the definition of `fac' (shown below) and then
777 execute `(fac 3)', here is what you normally see. Point is at the
778 open-parenthesis before `if'.
785 The places within a function where Edebug can stop execution are
786 called "stop points". These occur both before and after each
787 subexpression that is a list, and also after each variable reference.
788 Here we show with periods the stop points found in the function `fac':
792 .(* n. .(fac (1- n.).).).
795 While the source code buffer is selected, the special commands of
796 Edebug are available in it, in addition to the commands of XEmacs Lisp
797 mode. (The buffer is temporarily made read-only, however.) For
798 example, you can type the Edebug command <SPC> to execute until the
799 next stop point. If you type <SPC> once after entry to `fac', here is
800 the display you will see:
807 When Edebug stops execution after an expression, it displays the
808 expression's value in the echo area.
810 Other frequently used commands are `b' to set a breakpoint at a stop
811 point, `g' to execute until a breakpoint is reached, and `q' to exit to
812 the top-level command loop. Type `?' to display a list of all Edebug
816 File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug
818 Instrumenting for Edebug
819 ------------------------
821 In order to use Edebug to debug Lisp code, you must first
822 "instrument" the code. Instrumenting a form inserts additional code
823 into it which invokes Edebug at the proper places. Furthermore, if
824 Edebug detects a syntax error while instrumenting, point is left at the
825 erroneous code and an `invalid-read-syntax' error is signaled.
827 Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is
828 redefined so that when invoked with a prefix argument on a definition,
829 it instruments the definition before evaluating it. (The source code
830 itself is not modified.) If the variable `edebug-all-defs' is
831 non-`nil', that inverts the meaning of the prefix argument: then
832 `C-M-x' instruments the definition _unless_ it has a prefix argument.
833 The default value of `edebug-all-defs' is `nil'. The command `M-x
834 edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
836 If `edebug-all-defs' is non-`nil', then the commands `eval-region',
837 `eval-current-buffer', and `eval-buffer' also instrument any
838 definitions they evaluate. Similarly, `edebug-all-forms' controls
839 whether `eval-region' should instrument _any_ form, even non-defining
840 forms. This doesn't apply to loading or evaluations in the minibuffer.
841 The command `M-x edebug-all-forms' toggles this option.
843 Another command, `M-x edebug-eval-top-level-form', is available to
844 instrument any top-level form regardless of the value of
845 `edebug-all-defs' or `edebug-all-forms'.
847 Just before Edebug instruments any code, it calls any functions in
848 the variable `edebug-setup-hook' and resets its value to `nil'. You
849 could use this to load up Edebug specifications associated with a
850 package you are using but only when you also use Edebug. For example,
851 `my-specs.el' may be loaded automatically when you use `my-package'
852 with Edebug by including the following code in `my-package.el'.
854 (add-hook 'edebug-setup-hook
855 (function (lambda () (require 'my-specs))))
857 While Edebug is active, the command `I' (`edebug-instrument-callee')
858 instruments the definition of the function or macro called by the list
859 form after point, if is not already instrumented. If the location of
860 the definition is not known to Edebug, this command cannot be used.
861 After loading Edebug, `eval-region' records the position of every
862 definition it evaluates, even if not instrumenting it. Also see the
863 command `i' (*Note Jumping::) which steps into the callee.
865 Edebug knows how to instrument all the standard special forms, an
866 interactive form with an expression argument, anonymous lambda
867 expressions, and other defining forms. (Specifications for macros
868 defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.)
869 Edebug cannot know what a user-defined macro will do with the arguments
870 of a macro call so you must tell it. See *Note Instrumenting Macro
871 Calls:: for the details.
873 Note that a couple ways remain to evaluate expressions without
874 instrumenting them. Loading a file via the `load' subroutine does not
875 instrument expressions for Edebug. Evaluations in the minibuffer via
876 `eval-expression' (`M-ESC') are not instrumented.
878 To remove instrumentation from a definition, simply reevaluate it
879 with one of the non-instrumenting commands, or reload the file.
881 See *Note Edebug Eval:: for other evaluation functions available
885 File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
887 Edebug Execution Modes
888 ----------------------
890 Edebug supports several execution modes for running the program you
891 are debugging. We call these alternatives "Edebug execution modes"; do
892 not confuse them with major or minor modes. The current Edebug
893 execution mode determines how Edebug displays the progress of the
894 evaluation, whether it stops at each stop point, or continues to the
895 next breakpoint, for example.
897 Normally, you specify the Edebug execution mode by typing a command
898 to continue the program in a certain mode. Here is a table of these
899 commands. All except for `S' resume execution of the program, at least
900 for a certain distance.
903 Stop: don't execute any more of the program for now, just wait for
904 more Edebug commands (`edebug-stop').
907 Step: stop at the next stop point encountered (`edebug-step-mode').
910 Next: stop at the next stop point encountered after an expression
911 (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note
915 Trace: pause one second at each Edebug stop point
916 (`edebug-trace-mode').
919 Rapid trace: update at each stop point, but don't actually pause
920 (`edebug-Trace-fast-mode').
923 Go: run until the next breakpoint (`edebug-go-mode'). *Note
927 Continue: pause for one second at each breakpoint, but don't stop
928 (`edebug-continue-mode').
931 Rapid continue: update at each breakpoint, but don't actually pause
932 (`edebug-Continue-fast-mode').
935 Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You
936 can still stop the program by hitting any key.
938 In general, the execution modes earlier in the above list run the
939 program more slowly or stop sooner.
941 When you enter a new Edebug level, the initial execution mode comes
942 from the value of the variable `edebug-initial-mode'. By default, this
943 specifies `step' mode. Note that you may reenter the same Edebug level
944 several times if, for example, an instrumented function is called
945 several times from one command.
947 While executing or tracing, you can interrupt the execution by typing
948 any Edebug command. Edebug stops the program at the next stop point and
949 then executes the command that you typed. For example, typing `t'
950 during execution switches to trace mode at the next stop point. You can
951 use `S' to stop execution without doing anything else.
953 If your function happens to read input, a character you hit
954 intending to interrupt execution may be read by the function instead.
955 You can avoid such unintended results by paying attention to when your
958 Keyboard macros containing Edebug commands do not work; when you exit
959 from Edebug, to resume the program, whether you are defining or
960 executing a keyboard macro is forgotten. Also, defining or executing a
961 keyboard macro outside of Edebug does not affect the command loop inside
962 Edebug. This is usually an advantage. But see
963 `edebug-continue-kbd-macro'.
966 File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug
971 Commands described here let you jump to a specified location. All,
972 except `i', use temporary breakpoints to establish the stop point and
973 then switch to `go' mode. Any other breakpoint reached before the
974 intended stop point will also stop execution. See *Note Breakpoints::
975 for the details on breakpoints.
978 Run the program forward over one expression
979 (`edebug-forward-sexp'). More precisely, set a temporary
980 breakpoint at the position that `C-M-f' would reach, then execute
981 in `go' mode so that the program will stop at breakpoints.
983 With a prefix argument N, the temporary breakpoint is placed N
984 sexps beyond point. If the containing list ends before N more
985 elements, then the place to stop is after the containing
988 Be careful that the position `C-M-f' finds is a place that the
989 program will really get to; this may not be true in a `cond', for
992 This command does `forward-sexp' starting at point rather than the
993 stop point. If you want to execute one expression from the
994 current stop point, type `w' first, to move point there.
997 Continue "out of" an expression (`edebug-step-out'). It places a
998 temporary breakpoint at the end of the sexp containing point.
1000 If the containing sexp is a function definition itself, it
1001 continues until just before the last sexp in the definition. If
1002 that is where you are now, it returns from the function and then
1003 stops. In other words, this command does not exit the currently
1004 executing function unless you are positioned after the last sexp.
1007 Step into the function or macro after point after first ensuring
1008 that it is instrumented. It does this by calling
1009 `edebug-on-entry' and then switching to `go' mode.
1011 Although the automatic instrumentation is convenient, it is not
1012 later automatically uninstrumented.
1015 Proceed to the stop point near where point is using a temporary
1016 breakpoint (`edebug-goto-here').
1018 All the commands in this section may fail to work as expected in case
1019 of nonlocal exit, because a nonlocal exit can bypass the temporary
1020 breakpoint where you expected the program to stop.
1023 File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug
1028 Some miscellaneous commands are described here.
1031 Display the help message for Edebug (`edebug-help').
1034 Abort one level back to the previous command level
1035 (`abort-recursive-edit').
1038 Return to the top level editor command loop (`top-level'). This
1039 exits all recursive editing levels, including all levels of Edebug
1040 activity. However, instrumented code protected with
1041 `unwind-protect' or `condition-case' forms may resume debugging.
1044 Like `q' but don't stop even for protected code
1045 (`top-level-nonstop').
1048 Redisplay the most recently known expression result in the echo
1049 area (`edebug-previous-result').
1052 Display a backtrace, excluding Edebug's own functions for clarity
1053 (`edebug-backtrace').
1055 You cannot use debugger commands in the backtrace buffer in Edebug
1056 as you would in the standard debugger.
1058 The backtrace buffer is killed automatically when you continue
1061 From the Edebug recursive edit, you may invoke commands that activate
1062 Edebug again recursively. Any time Edebug is active, you can quit to
1063 the top level with `q' or abort one recursive edit level with `C-]'.
1064 You can display a backtrace of all the pending evaluations with `d'.
1067 File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug
1072 There are three more ways to stop execution once it has started:
1073 breakpoints, the global break condition, and embedded breakpoints.
1075 While using Edebug, you can specify "breakpoints" in the program you
1076 are testing: points where execution should stop. You can set a
1077 breakpoint at any stop point, as defined in *Note Using Edebug::. For
1078 setting and unsetting breakpoints, the stop point that is affected is
1079 the first one at or after point in the source code buffer. Here are the
1080 Edebug commands for breakpoints:
1083 Set a breakpoint at the stop point at or after point
1084 (`edebug-set-breakpoint'). If you use a prefix argument, the
1085 breakpoint is temporary (it turns off the first time it stops the
1089 Unset the breakpoint (if any) at the stop point at or after the
1090 current point (`edebug-unset-breakpoint').
1093 Set a conditional breakpoint which stops the program only if
1094 CONDITION evaluates to a non-`nil' value
1095 (`edebug-set-conditional-breakpoint'). If you use a prefix
1096 argument, the breakpoint is temporary (it turns off the first time
1097 it stops the program).
1100 Move point to the next breakpoint in the definition
1101 (`edebug-next-breakpoint').
1103 While in Edebug, you can set a breakpoint with `b' and unset one
1104 with `u'. First you must move point to a position at or before the
1105 desired Edebug stop point, then hit the key to change the breakpoint.
1106 Unsetting a breakpoint that has not been set does nothing.
1108 Reevaluating or reinstrumenting a definition clears all its
1111 A "conditional breakpoint" tests a condition each time the program
1112 gets there. To set a conditional breakpoint, use `x', and specify the
1113 condition expression in the minibuffer. Setting a conditional
1114 breakpoint at a stop point that already has a conditional breakpoint
1115 puts the current condition expression in the minibuffer so you can edit
1118 You can make both conditional and unconditional breakpoints
1119 "temporary" by using a prefix arg to the command to set the breakpoint.
1120 After breaking at a temporary breakpoint, it is automatically cleared.
1122 Edebug always stops or pauses at a breakpoint except when the Edebug
1123 mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely.
1125 To find out where your breakpoints are, use `B', which moves point
1126 to the next breakpoint in the definition following point, or to the
1127 first breakpoint if there are no following breakpoints. This command
1128 does not continue execution--it just moves point in the buffer.
1132 * Global Break Condition:: Breaking on an event.
1133 * Embedded Breakpoints:: Embedding breakpoints in code.
1136 File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints
1138 Global Break Condition
1139 ......................
1141 In contrast to breaking when execution reaches specified locations,
1142 you can also cause a break when a certain event occurs. The "global
1143 break condition" is a condition that is repeatedly evaluated at every
1144 stop point. If it evaluates to a non-`nil' value, then execution is
1145 stopped or paused depending on the execution mode, just like a
1146 breakpoint. Any errors that might occur as a result of evaluating the
1147 condition are ignored, as if the result were `nil'.
1149 You can set or edit the condition expression, stored in
1150 `edebug-global-break-condition', using `X'
1151 (`edebug-set-global-break-condition').
1153 Using the global break condition is perhaps the fastest way to find
1154 where in your code some event occurs, but since it is rather expensive
1155 you should reset the condition to `nil' when not in use.
1158 File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints
1160 Embedded Breakpoints
1161 ....................
1163 Since all breakpoints in a definition are cleared each time you
1164 reinstrument it, you might rather create an "embedded breakpoint" which
1165 is simply a call to the function `edebug'. You can, of course, make
1166 such a call conditional. For example, in the `fac' function, insert
1167 the first line as shown below to stop when the argument reaches zero:
1170 (if (= n 0) (edebug))
1175 When the `fac' definition is instrumented and the function is
1176 called, Edebug will stop before the call to `edebug'. Depending on the
1177 execution mode, Edebug will stop or pause.
1179 However, if no instrumented code is being executed, calling `edebug'
1180 will instead invoke `debug'. Calling `debug' will always invoke the
1181 standard backtrace debugger.