1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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-ignored-errors
84 This variable specifies certain kinds of errors that should not
85 enter the debugger. Its value is a list of error condition
86 symbols and/or regular expressions. If the error has any of those
87 condition symbols, or if the error message matches any of the
88 regular expressions, then that error does not enter the debugger,
89 regardless of the value of `debug-on-error'.
91 The normal value of this variable lists several errors that happen
92 often during editing but rarely result from bugs in Lisp programs.
94 To debug an error that happens during loading of the `.emacs' file,
95 use the option `-debug-init', which binds `debug-on-error' to `t' while
96 `.emacs' is loaded and inhibits use of `condition-case' to catch init
99 If your `.emacs' file sets `debug-on-error', the effect may not last
100 past the end of loading `.emacs'. (This is an undesirable byproduct of
101 the code that implements the `-debug-init' command line option.) The
102 best way to make `.emacs' set `debug-on-error' permanently is with
103 `after-init-hook', like this:
105 (add-hook 'after-init-hook
106 '(lambda () (setq debug-on-error t)))
108 - User Option: debug-on-signal
109 This variable is similar to `debug-on-error' but breaks whenever
110 an error is signalled, regardless of whether it would be handled.
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
724 The first three sections should tell you enough about Edebug to
725 enable you to use it.
729 * Using Edebug:: Introduction to use of Edebug.
730 * Instrumenting:: You must first instrument code.
731 * Edebug Execution Modes:: Execution modes, stopping more or less often.
732 * Jumping:: Commands to jump to a specified place.
733 * Edebug Misc:: Miscellaneous commands.
734 * Breakpoints:: Setting breakpoints to make the program stop.
735 * Trapping Errors:: trapping errors with Edebug.
736 * Edebug Views:: Views inside and outside of Edebug.
737 * Edebug Eval:: Evaluating expressions within Edebug.
738 * Eval List:: Automatic expression evaluation.
739 * Reading in Edebug:: Customization of reading.
740 * Printing in Edebug:: Customization of printing.
741 * Tracing:: How to produce tracing output.
742 * Coverage Testing:: How to test evaluation coverage.
743 * The Outside Context:: Data that Edebug saves and restores.
744 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
745 * Edebug Options:: Option variables for customizing Edebug.
748 File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug
753 To debug an XEmacs Lisp program with Edebug, you must first
754 "instrument" the Lisp code that you want to debug. If you want to just
755 try it now, load `edebug.el', move point into a definition and do `C-u
756 C-M-x' (`eval-defun' with a prefix argument). See *Note
757 Instrumenting:: for alternative ways to instrument code.
759 Once a function is instrumented, any call to the function activates
760 Edebug. Activating Edebug may stop execution and let you step through
761 the function, or it may update the display and continue execution while
762 checking for debugging commands, depending on the selected Edebug
763 execution mode. The initial execution mode is `step', by default,
764 which does stop execution. *Note Edebug Execution Modes::.
766 Within Edebug, you normally view an XEmacs buffer showing the source
767 of the Lisp function you are debugging. This is referred to as the
768 "source code buffer"--but note that it is not always the same buffer
769 depending on which function is currently being executed.
771 An arrow at the left margin indicates the line where the function is
772 executing. Point initially shows where within the line the function is
773 executing, but you can move point yourself.
775 If you instrument the definition of `fac' (shown below) and then
776 execute `(fac 3)', here is what you normally see. Point is at the
777 open-parenthesis before `if'.
784 The places within a function where Edebug can stop execution are
785 called "stop points". These occur both before and after each
786 subexpression that is a list, and also after each variable reference.
787 Here we show with periods the stop points found in the function `fac':
791 .(* n. .(fac (1- n.).).).
794 While the source code buffer is selected, the special commands of
795 Edebug are available in it, in addition to the commands of XEmacs Lisp
796 mode. (The buffer is temporarily made read-only, however.) For
797 example, you can type the Edebug command <SPC> to execute until the
798 next stop point. If you type <SPC> once after entry to `fac', here is
799 the display you will see:
806 When Edebug stops execution after an expression, it displays the
807 expression's value in the echo area.
809 Other frequently used commands are `b' to set a breakpoint at a stop
810 point, `g' to execute until a breakpoint is reached, and `q' to exit to
811 the top-level command loop. Type `?' to display a list of all Edebug
815 File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug
817 Instrumenting for Edebug
818 ------------------------
820 In order to use Edebug to debug Lisp code, you must first
821 "instrument" the code. Instrumenting a form inserts additional code
822 into it which invokes Edebug at the proper places. Furthermore, if
823 Edebug detects a syntax error while instrumenting, point is left at the
824 erroneous code and an `invalid-read-syntax' error is signaled.
826 Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is
827 redefined so that when invoked with a prefix argument on a definition,
828 it instruments the definition before evaluating it. (The source code
829 itself is not modified.) If the variable `edebug-all-defs' is
830 non-`nil', that inverts the meaning of the prefix argument: then
831 `C-M-x' instruments the definition *unless* it has a prefix argument.
832 The default value of `edebug-all-defs' is `nil'. The command `M-x
833 edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
835 If `edebug-all-defs' is non-`nil', then the commands `eval-region',
836 `eval-current-buffer', and `eval-buffer' also instrument any
837 definitions they evaluate. Similarly, `edebug-all-forms' controls
838 whether `eval-region' should instrument *any* form, even non-defining
839 forms. This doesn't apply to loading or evaluations in the minibuffer.
840 The command `M-x edebug-all-forms' toggles this option.
842 Another command, `M-x edebug-eval-top-level-form', is available to
843 instrument any top-level form regardless of the value of
844 `edebug-all-defs' or `edebug-all-forms'.
846 Just before Edebug instruments any code, it calls any functions in
847 the variable `edebug-setup-hook' and resets its value to `nil'. You
848 could use this to load up Edebug specifications associated with a
849 package you are using but only when you also use Edebug. For example,
850 `my-specs.el' may be loaded automatically when you use `my-package'
851 with Edebug by including the following code in `my-package.el'.
853 (add-hook 'edebug-setup-hook
854 (function (lambda () (require 'my-specs))))
856 While Edebug is active, the command `I' (`edebug-instrument-callee')
857 instruments the definition of the function or macro called by the list
858 form after point, if is not already instrumented. If the location of
859 the definition is not known to Edebug, this command cannot be used.
860 After loading Edebug, `eval-region' records the position of every
861 definition it evaluates, even if not instrumenting it. Also see the
862 command `i' (*Note Jumping::) which steps into the callee.
864 Edebug knows how to instrument all the standard special forms, an
865 interactive form with an expression argument, anonymous lambda
866 expressions, and other defining forms. (Specifications for macros
867 defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.)
868 Edebug cannot know what a user-defined macro will do with the arguments
869 of a macro call so you must tell it. See *Note Instrumenting Macro
870 Calls:: for the details.
872 Note that a couple ways remain to evaluate expressions without
873 instrumenting them. Loading a file via the `load' subroutine does not
874 instrument expressions for Edebug. Evaluations in the minibuffer via
875 `eval-expression' (`M-ESC') are not instrumented.
877 To remove instrumentation from a definition, simply reevaluate it
878 with one of the non-instrumenting commands, or reload the file.
880 See *Note Edebug Eval:: for other evaluation functions available
884 File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
886 Edebug Execution Modes
887 ----------------------
889 Edebug supports several execution modes for running the program you
890 are debugging. We call these alternatives "Edebug execution modes"; do
891 not confuse them with major or minor modes. The current Edebug
892 execution mode determines how Edebug displays the progress of the
893 evaluation, whether it stops at each stop point, or continues to the
894 next breakpoint, for example.
896 Normally, you specify the Edebug execution mode by typing a command
897 to continue the program in a certain mode. Here is a table of these
898 commands. All except for `S' resume execution of the program, at least
899 for a certain distance.
902 Stop: don't execute any more of the program for now, just wait for
903 more Edebug commands (`edebug-stop').
906 Step: stop at the next stop point encountered (`edebug-step-mode').
909 Next: stop at the next stop point encountered after an expression
910 (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note
914 Trace: pause one second at each Edebug stop point
915 (`edebug-trace-mode').
918 Rapid trace: update at each stop point, but don't actually pause
919 (`edebug-Trace-fast-mode').
922 Go: run until the next breakpoint (`edebug-go-mode'). *Note
926 Continue: pause for one second at each breakpoint, but don't stop
927 (`edebug-continue-mode').
930 Rapid continue: update at each breakpoint, but don't actually pause
931 (`edebug-Continue-fast-mode').
934 Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You
935 can still stop the program by hitting any key.
937 In general, the execution modes earlier in the above list run the
938 program more slowly or stop sooner.
940 When you enter a new Edebug level, the initial execution mode comes
941 from the value of the variable `edebug-initial-mode'. By default, this
942 specifies `step' mode. Note that you may reenter the same Edebug level
943 several times if, for example, an instrumented function is called
944 several times from one command.
946 While executing or tracing, you can interrupt the execution by typing
947 any Edebug command. Edebug stops the program at the next stop point and
948 then executes the command that you typed. For example, typing `t'
949 during execution switches to trace mode at the next stop point. You can
950 use `S' to stop execution without doing anything else.
952 If your function happens to read input, a character you hit
953 intending to interrupt execution may be read by the function instead.
954 You can avoid such unintended results by paying attention to when your
957 Keyboard macros containing Edebug commands do not work; when you exit
958 from Edebug, to resume the program, whether you are defining or
959 executing a keyboard macro is forgotten. Also, defining or executing a
960 keyboard macro outside of Edebug does not affect the command loop inside
961 Edebug. This is usually an advantage. But see
962 `edebug-continue-kbd-macro'.
965 File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug
970 Commands described here let you jump to a specified location. All,
971 except `i', use temporary breakpoints to establish the stop point and
972 then switch to `go' mode. Any other breakpoint reached before the
973 intended stop point will also stop execution. See *Note Breakpoints::
974 for the details on breakpoints.
977 Run the program forward over one expression
978 (`edebug-forward-sexp'). More precisely, set a temporary
979 breakpoint at the position that `C-M-f' would reach, then execute
980 in `go' mode so that the program will stop at breakpoints.
982 With a prefix argument N, the temporary breakpoint is placed N
983 sexps beyond point. If the containing list ends before N more
984 elements, then the place to stop is after the containing
987 Be careful that the position `C-M-f' finds is a place that the
988 program will really get to; this may not be true in a `cond', for
991 This command does `forward-sexp' starting at point rather than the
992 stop point. If you want to execute one expression from the
993 current stop point, type `w' first, to move point there.
996 Continue "out of" an expression (`edebug-step-out'). It places a
997 temporary breakpoint at the end of the sexp containing point.
999 If the containing sexp is a function definition itself, it
1000 continues until just before the last sexp in the definition. If
1001 that is where you are now, it returns from the function and then
1002 stops. In other words, this command does not exit the currently
1003 executing function unless you are positioned after the last sexp.
1006 Step into the function or macro after point after first ensuring
1007 that it is instrumented. It does this by calling
1008 `edebug-on-entry' and then switching to `go' mode.
1010 Although the automatic instrumentation is convenient, it is not
1011 later automatically uninstrumented.
1014 Proceed to the stop point near where point is using a temporary
1015 breakpoint (`edebug-goto-here').
1017 All the commands in this section may fail to work as expected in case
1018 of nonlocal exit, because a nonlocal exit can bypass the temporary
1019 breakpoint where you expected the program to stop.
1022 File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug
1027 Some miscellaneous commands are described here.
1030 Display the help message for Edebug (`edebug-help').
1033 Abort one level back to the previous command level
1034 (`abort-recursive-edit').
1037 Return to the top level editor command loop (`top-level'). This
1038 exits all recursive editing levels, including all levels of Edebug
1039 activity. However, instrumented code protected with
1040 `unwind-protect' or `condition-case' forms may resume debugging.
1043 Like `q' but don't stop even for protected code
1044 (`top-level-nonstop').
1047 Redisplay the most recently known expression result in the echo
1048 area (`edebug-previous-result').
1051 Display a backtrace, excluding Edebug's own functions for clarity
1052 (`edebug-backtrace').
1054 You cannot use debugger commands in the backtrace buffer in Edebug
1055 as you would in the standard debugger.
1057 The backtrace buffer is killed automatically when you continue
1060 From the Edebug recursive edit, you may invoke commands that activate
1061 Edebug again recursively. Any time Edebug is active, you can quit to
1062 the top level with `q' or abort one recursive edit level with `C-]'.
1063 You can display a backtrace of all the pending evaluations with `d'.
1066 File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug
1071 There are three more ways to stop execution once it has started:
1072 breakpoints, the global break condition, and embedded breakpoints.
1074 While using Edebug, you can specify "breakpoints" in the program you
1075 are testing: points where execution should stop. You can set a
1076 breakpoint at any stop point, as defined in *Note Using Edebug::. For
1077 setting and unsetting breakpoints, the stop point that is affected is
1078 the first one at or after point in the source code buffer. Here are the
1079 Edebug commands for breakpoints:
1082 Set a breakpoint at the stop point at or after point
1083 (`edebug-set-breakpoint'). If you use a prefix argument, the
1084 breakpoint is temporary (it turns off the first time it stops the
1088 Unset the breakpoint (if any) at the stop point at or after the
1089 current point (`edebug-unset-breakpoint').
1092 Set a conditional breakpoint which stops the program only if
1093 CONDITION evaluates to a non-`nil' value
1094 (`edebug-set-conditional-breakpoint'). If you use a prefix
1095 argument, the breakpoint is temporary (it turns off the first time
1096 it stops the program).
1099 Move point to the next breakpoint in the definition
1100 (`edebug-next-breakpoint').
1102 While in Edebug, you can set a breakpoint with `b' and unset one
1103 with `u'. First you must move point to a position at or before the
1104 desired Edebug stop point, then hit the key to change the breakpoint.
1105 Unsetting a breakpoint that has not been set does nothing.
1107 Reevaluating or reinstrumenting a definition clears all its
1110 A "conditional breakpoint" tests a condition each time the program
1111 gets there. To set a conditional breakpoint, use `x', and specify the
1112 condition expression in the minibuffer. Setting a conditional
1113 breakpoint at a stop point that already has a conditional breakpoint
1114 puts the current condition expression in the minibuffer so you can edit
1117 You can make both conditional and unconditional breakpoints
1118 "temporary" by using a prefix arg to the command to set the breakpoint.
1119 After breaking at a temporary breakpoint, it is automatically cleared.
1121 Edebug always stops or pauses at a breakpoint except when the Edebug
1122 mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely.
1124 To find out where your breakpoints are, use `B', which moves point
1125 to the next breakpoint in the definition following point, or to the
1126 first breakpoint if there are no following breakpoints. This command
1127 does not continue execution--it just moves point in the buffer.
1131 * Global Break Condition:: Breaking on an event.
1132 * Embedded Breakpoints:: Embedding breakpoints in code.
1135 File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints
1137 Global Break Condition
1138 ......................
1140 In contrast to breaking when execution reaches specified locations,
1141 you can also cause a break when a certain event occurs. The "global
1142 break condition" is a condition that is repeatedly evaluated at every
1143 stop point. If it evaluates to a non-`nil' value, then execution is
1144 stopped or paused depending on the execution mode, just like a
1145 breakpoint. Any errors that might occur as a result of evaluating the
1146 condition are ignored, as if the result were `nil'.
1148 You can set or edit the condition expression, stored in
1149 `edebug-global-break-condition', using `X'
1150 (`edebug-set-global-break-condition').
1152 Using the global break condition is perhaps the fastest way to find
1153 where in your code some event occurs, but since it is rather expensive
1154 you should reset the condition to `nil' when not in use.
1157 File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints
1159 Embedded Breakpoints
1160 ....................
1162 Since all breakpoints in a definition are cleared each time you
1163 reinstrument it, you might rather create an "embedded breakpoint" which
1164 is simply a call to the function `edebug'. You can, of course, make
1165 such a call conditional. For example, in the `fac' function, insert
1166 the first line as shown below to stop when the argument reaches zero:
1169 (if (= n 0) (edebug))
1174 When the `fac' definition is instrumented and the function is
1175 called, Edebug will stop before the call to `edebug'. Depending on the
1176 execution mode, Edebug will stop or pause.
1178 However, if no instrumented code is being executed, calling `edebug'
1179 will instead invoke `debug'. Calling `debug' will always invoke the
1180 standard backtrace debugger.
projects / chise / xemacs-chise.git.1 / blob