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: Disassembly, Prev: Compiled-Function Objects, Up: Byte Compilation
55 Disassembled Byte-Code
56 ======================
58 People do not write byte-code; that job is left to the byte compiler.
59 But we provide a disassembler to satisfy a cat-like curiosity. The
60 disassembler converts the byte-compiled code into humanly readable form.
62 The byte-code interpreter is implemented as a simple stack machine.
63 It pushes values onto a stack of its own, then pops them off to use them
64 in calculations whose results are themselves pushed back on the stack.
65 When a byte-code function returns, it pops a value off the stack and
66 returns it as the value of the function.
68 In addition to the stack, byte-code functions can use, bind, and set
69 ordinary Lisp variables, by transferring values between variables and
72 - Command: disassemble object &optional stream
73 This function prints the disassembled code for OBJECT. If STREAM
74 is supplied, then output goes there. Otherwise, the disassembled
75 code is printed to the stream `standard-output'. The argument
76 OBJECT can be a function name or a lambda expression.
78 As a special exception, if this function is used interactively, it
79 outputs to a buffer named `*Disassemble*'.
81 Here are two examples of using the `disassemble' function. We have
82 added explanatory comments to help you relate the byte-code to the Lisp
83 source; these do not appear in the output of `disassemble'.
85 (defun factorial (integer)
86 "Compute factorial of an integer."
88 (* integer (factorial (1- integer)))))
94 (disassemble 'factorial)
95 -| byte-code for factorial:
96 doc: Compute factorial of an integer.
99 0 varref integer ; Get value of `integer'
100 ; from the environment
104 1 constant 1 ; Push 1 onto stack.
106 2 eqlsign ; Pop top two values off stack,
108 ; and push result onto stack.
110 3 goto-if-nil 1 ; Pop and test top of stack;
112 ; go to label 1 (which is also byte 7),
115 5 constant 1 ; Push 1 onto top of stack.
117 6 return ; Return the top element
120 7:1 varref integer ; Push value of `integer' onto stack.
122 8 constant factorial ; Push `factorial' onto stack.
124 9 varref integer ; Push value of `integer' onto stack.
126 10 sub1 ; Pop `integer', decrement value,
127 ; push new value onto stack.
129 ; Stack now contains:
130 ; - decremented value of `integer'
132 ; - value of `integer'
134 15 call 1 ; Call function `factorial' using
135 ; the first (i.e., the top) element
136 ; of the stack as the argument;
137 ; push returned value onto stack.
139 ; Stack now contains:
140 ; - result of recursive
141 ; call to `factorial'
142 ; - value of `integer'
144 12 mult ; Pop top two values off the stack,
146 ; pushing the result onto the stack.
148 13 return ; Return the top element
152 The `silly-loop' function is somewhat more complex:
154 (defun silly-loop (n)
155 "Return time before and after N iterations of a loop."
156 (let ((t1 (current-time-string)))
157 (while (> (setq n (1- n))
159 (list t1 (current-time-string))))
162 (disassemble 'silly-loop)
163 -| byte-code for silly-loop:
164 doc: Return time before and after N iterations of a loop.
167 0 constant current-time-string ; Push
168 ; `current-time-string'
171 1 call 0 ; Call `current-time-string'
173 ; pushing result onto stack.
175 2 varbind t1 ; Pop stack and bind `t1'
178 3:1 varref n ; Get value of `n' from
179 ; the environment and push
180 ; the value onto the stack.
182 4 sub1 ; Subtract 1 from top of stack.
184 5 dup ; Duplicate the top of the stack;
185 ; i.e., copy the top of
186 ; the stack and push the
187 ; copy onto the stack.
189 6 varset n ; Pop the top of the stack,
190 ; and set `n' to the value.
192 ; In effect, the sequence `dup varset'
193 ; copies the top of the stack
194 ; into the value of `n'
195 ; without popping it.
197 7 constant 0 ; Push 0 onto stack.
199 8 gtr ; Pop top two values off stack,
200 ; test if N is greater than 0
201 ; and push result onto stack.
203 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0
204 ; (this exits the while loop).
205 ; else pop top of stack
208 11 varref t1 ; Push value of `t1' onto stack.
210 12 constant current-time-string ; Push
211 ; `current-time-string'
214 13 call 0 ; Call `current-time-string' again.
216 14 unbind 1 ; Unbind `t1' in local environment.
218 15 list2 ; Pop top two elements off stack,
219 ; create a list of them,
220 ; and push list onto stack.
222 16 return ; Return the top element of the stack.
227 File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top
229 Debugging Lisp Programs
230 ***********************
232 There are three ways to investigate a problem in an XEmacs Lisp
233 program, depending on what you are doing with the program when the
236 * If the problem occurs when you run the program, you can use a Lisp
237 debugger (either the default debugger or Edebug) to investigate
238 what is happening during execution.
240 * If the problem is syntactic, so that Lisp cannot even read the
241 program, you can use the XEmacs facilities for editing Lisp to
244 * If the problem occurs when trying to compile the program with the
245 byte compiler, you need to know how to examine the compiler's
250 * Debugger:: How the XEmacs Lisp debugger is implemented.
251 * Syntax Errors:: How to find syntax errors.
252 * Compilation Errors:: How to find errors that show up in byte compilation.
253 * Edebug:: A source-level XEmacs Lisp debugger.
255 Another useful debugging tool is the dribble file. When a dribble
256 file is open, XEmacs copies all keyboard input characters to that file.
257 Afterward, you can examine the file to find out what input was used.
258 *Note Terminal Input::.
260 For debugging problems in terminal descriptions, the
261 `open-termscript' function can be useful. *Note Terminal Output::.
264 File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging
269 The "Lisp debugger" provides the ability to suspend evaluation of a
270 form. While evaluation is suspended (a state that is commonly known as
271 a "break"), you may examine the run time stack, examine the values of
272 local or global variables, or change those values. Since a break is a
273 recursive edit, all the usual editing facilities of XEmacs are
274 available; you can even run programs that will enter the debugger
275 recursively. *Note Recursive Editing::.
279 * Error Debugging:: Entering the debugger when an error happens.
280 * Infinite Loops:: Stopping and debugging a program that doesn't exit.
281 * Function Debugging:: Entering it when a certain function is called.
282 * Explicit Debug:: Entering it at a certain point in the program.
283 * Using Debugger:: What the debugger does; what you see while in it.
284 * Debugger Commands:: Commands used while in the debugger.
285 * Invoking the Debugger:: How to call the function `debug'.
286 * Internals of Debugger:: Subroutines of the debugger, and global variables.
289 File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger
291 Entering the Debugger on an Error
292 ---------------------------------
294 The most important time to enter the debugger is when a Lisp error
295 happens. This allows you to investigate the immediate causes of the
298 However, entry to the debugger is not a normal consequence of an
299 error. Many commands frequently get Lisp errors when invoked in
300 inappropriate contexts (such as `C-f' at the end of the buffer) and
301 during ordinary editing it would be very unpleasant to enter the
302 debugger each time this happens. If you want errors to enter the
303 debugger, set the variable `debug-on-error' to non-`nil'.
305 - User Option: debug-on-error
306 This variable determines whether the debugger is called when an
307 error is signaled and not handled. If `debug-on-error' is `t', all
308 errors call the debugger. If it is `nil', none call the debugger.
310 The value can also be a list of error conditions that should call
311 the debugger. For example, if you set it to the list
312 `(void-variable)', then only errors about a variable that has no
313 value invoke the debugger.
315 When this variable is non-`nil', Emacs does not catch errors that
316 happen in process filter functions and sentinels. Therefore, these
317 errors also can invoke the debugger. *Note Processes::.
319 - User Option: debug-on-signal
320 This variable is similar to `debug-on-error' but breaks whenever
321 an error is signalled, regardless of whether it would be handled.
323 - User Option: debug-ignored-errors
324 This variable specifies certain kinds of errors that should not
325 enter the debugger. Its value is a list of error condition
326 symbols and/or regular expressions. If the error has any of those
327 condition symbols, or if the error message matches any of the
328 regular expressions, then that error does not enter the debugger,
329 regardless of the value of `debug-on-error'.
331 The normal value of this variable lists several errors that happen
332 often during editing but rarely result from bugs in Lisp programs.
334 To debug an error that happens during loading of the `.emacs' file,
335 use the option `-debug-init', which binds `debug-on-error' to `t' while
336 `.emacs' is loaded and inhibits use of `condition-case' to catch init
339 If your `.emacs' file sets `debug-on-error', the effect may not last
340 past the end of loading `.emacs'. (This is an undesirable byproduct of
341 the code that implements the `-debug-init' command line option.) The
342 best way to make `.emacs' set `debug-on-error' permanently is with
343 `after-init-hook', like this:
345 (add-hook 'after-init-hook
346 '(lambda () (setq debug-on-error t)))
349 File: lispref.info, Node: Infinite Loops, Next: Function Debugging, Prev: Error Debugging, Up: Debugger
351 Debugging Infinite Loops
352 ------------------------
354 When a program loops infinitely and fails to return, your first
355 problem is to stop the loop. On most operating systems, you can do this
356 with `C-g', which causes quit.
358 Ordinary quitting gives no information about why the program was
359 looping. To get more information, you can set the variable
360 `debug-on-quit' to non-`nil'. Quitting with `C-g' is not considered an
361 error, and `debug-on-error' has no effect on the handling of `C-g'.
362 Likewise, `debug-on-quit' has no effect on errors.
364 Once you have the debugger running in the middle of the infinite
365 loop, you can proceed from the debugger using the stepping commands.
366 If you step through the entire loop, you will probably get enough
367 information to solve the problem.
369 - User Option: debug-on-quit
370 This variable determines whether the debugger is called when `quit'
371 is signaled and not handled. If `debug-on-quit' is non-`nil',
372 then the debugger is called whenever you quit (that is, type
373 `C-g'). If `debug-on-quit' is `nil', then the debugger is not
374 called when you quit. *Note Quitting::.
377 File: lispref.info, Node: Function Debugging, Next: Explicit Debug, Prev: Infinite Loops, Up: Debugger
379 Entering the Debugger on a Function Call
380 ----------------------------------------
382 To investigate a problem that happens in the middle of a program, one
383 useful technique is to enter the debugger whenever a certain function is
384 called. You can do this to the function in which the problem occurs,
385 and then step through the function, or you can do this to a function
386 called shortly before the problem, step quickly over the call to that
387 function, and then step through its caller.
389 - Command: debug-on-entry function-name
390 This function requests FUNCTION-NAME to invoke the debugger each
391 time it is called. It works by inserting the form `(debug
392 'debug)' into the function definition as the first form.
394 Any function defined as Lisp code may be set to break on entry,
395 regardless of whether it is interpreted code or compiled code. If
396 the function is a command, it will enter the debugger when called
397 from Lisp and when called interactively (after the reading of the
398 arguments). You can't debug primitive functions (i.e., those
399 written in C) this way.
401 When `debug-on-entry' is called interactively, it prompts for
402 FUNCTION-NAME in the minibuffer.
404 If the function is already set up to invoke the debugger on entry,
405 `debug-on-entry' does nothing.
407 *Please note:* if you redefine a function after using
408 `debug-on-entry' on it, the code to enter the debugger is lost.
410 `debug-on-entry' returns FUNCTION-NAME.
414 (* n (fact (1- n)))))
416 (debug-on-entry 'fact)
420 ------ Buffer: *Backtrace* ------
423 eval-region(4870 4878 t)
427 eval-insert-last-sexp(nil)
428 * call-interactively(eval-insert-last-sexp)
429 ------ Buffer: *Backtrace* ------
431 (symbol-function 'fact)
433 (debug (quote debug))
434 (if (zerop n) 1 (* n (fact (1- n)))))
436 - Command: cancel-debug-on-entry &optional function-name
437 This function undoes the effect of `debug-on-entry' on
438 FUNCTION-NAME. When called interactively, it prompts for
439 FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the
440 empty string, it cancels debugging for all functions.
442 If `cancel-debug-on-entry' is called more than once on the same
443 function, the second call does nothing. `cancel-debug-on-entry'
444 returns FUNCTION-NAME.
447 File: lispref.info, Node: Explicit Debug, Next: Using Debugger, Prev: Function Debugging, Up: Debugger
449 Explicit Entry to the Debugger
450 ------------------------------
452 You can cause the debugger to be called at a certain point in your
453 program by writing the expression `(debug)' at that point. To do this,
454 visit the source file, insert the text `(debug)' at the proper place,
455 and type `C-M-x'. Be sure to undo this insertion before you save the
458 The place where you insert `(debug)' must be a place where an
459 additional form can be evaluated and its value ignored. (If the value
460 of `(debug)' isn't ignored, it will alter the execution of the
461 program!) The most common suitable places are inside a `progn' or an
462 implicit `progn' (*note Sequencing::).
465 File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
470 When the debugger is entered, it displays the previously selected
471 buffer in one window and a buffer named `*Backtrace*' in another
472 window. The backtrace buffer contains one line for each level of Lisp
473 function execution currently going on. At the beginning of this buffer
474 is a message describing the reason that the debugger was invoked (such
475 as the error message and associated data, if it was invoked due to an
478 The backtrace buffer is read-only and uses a special major mode,
479 Debugger mode, in which letters are defined as debugger commands. The
480 usual XEmacs editing commands are available; thus, you can switch
481 windows to examine the buffer that was being edited at the time of the
482 error, switch buffers, visit files, or do any other sort of editing.
483 However, the debugger is a recursive editing level (*note Recursive
484 Editing::) and it is wise to go back to the backtrace buffer and exit
485 the debugger (with the `q' command) when you are finished with it.
486 Exiting the debugger gets out of the recursive edit and kills the
489 The backtrace buffer shows you the functions that are executing and
490 their argument values. It also allows you to specify a stack frame by
491 moving point to the line describing that frame. (A stack frame is the
492 place where the Lisp interpreter records information about a particular
493 invocation of a function.) The frame whose line point is on is
494 considered the "current frame". Some of the debugger commands operate
495 on the current frame.
497 The debugger itself must be run byte-compiled, since it makes
498 assumptions about how many stack frames are used for the debugger
499 itself. These assumptions are false if the debugger is running
503 File: lispref.info, Node: Debugger Commands, Next: Invoking the Debugger, Prev: Using Debugger, Up: Debugger
508 Inside the debugger (in Debugger mode), these special commands are
509 available in addition to the usual cursor motion commands. (Keep in
510 mind that all the usual facilities of XEmacs, such as switching windows
511 or buffers, are still available.)
513 The most important use of debugger commands is for stepping through
514 code, so that you can see how control flows. The debugger can step
515 through the control structures of an interpreted function, but cannot do
516 so in a byte-compiled function. If you would like to step through a
517 byte-compiled function, replace it with an interpreted definition of the
518 same function. (To do this, visit the source file for the function and
519 type `C-M-x' on its definition.)
521 Here is a list of Debugger mode commands:
524 Exit the debugger and continue execution. This resumes execution
525 of the program as if the debugger had never been entered (aside
526 from the effect of any variables or data structures you may have
527 changed while inside the debugger).
529 Continuing when an error or quit was signalled will cause the
530 normal action of the signalling to take place. If you do not want
531 this to happen, but instead want the program execution to continue
532 as if the call to `signal' did not occur, use the `r' command.
535 Continue execution, but enter the debugger the next time any Lisp
536 function is called. This allows you to step through the
537 subexpressions of an expression, seeing what values the
538 subexpressions compute, and what else they do.
540 The stack frame made for the function call which enters the
541 debugger in this way will be flagged automatically so that the
542 debugger will be called again when the frame is exited. You can
543 use the `u' command to cancel this flag.
546 Flag the current frame so that the debugger will be entered when
547 the frame is exited. Frames flagged in this way are marked with
548 stars in the backtrace buffer.
551 Don't enter the debugger when the current frame is exited. This
552 cancels a `b' command on that frame.
555 Read a Lisp expression in the minibuffer, evaluate it, and print
556 the value in the echo area. The debugger alters certain important
557 variables, and the current buffer, as part of its operation; `e'
558 temporarily restores their outside-the-debugger values so you can
559 examine them. This makes the debugger more transparent. By
560 contrast, `M-:' does nothing special in the debugger; it shows you
561 the variable values within the debugger.
564 Terminate the program being debugged; return to top-level XEmacs
567 If the debugger was entered due to a `C-g' but you really want to
568 quit, and not debug, use the `q' command.
571 Return a value from the debugger. The value is computed by
572 reading an expression with the minibuffer and evaluating it.
574 The `r' command is useful when the debugger was invoked due to exit
575 from a Lisp call frame (as requested with `b'); then the value
576 specified in the `r' command is used as the value of that frame.
577 It is also useful if you call `debug' and use its return value.
579 If the debugger was entered at the beginning of a function call,
580 `r' has the same effect as `c', and the specified return value
583 If the debugger was entered through a call to `signal' (i.e. as a
584 result of an error or quit), then returning a value will cause the
585 call to `signal' itself to return, rather than throwing to
586 top-level or invoking a handler, as is normal. This allows you to
587 correct an error (e.g. the type of an argument was wrong) or
588 continue from a `debug-on-quit' as if it never happened.
590 Note that some errors (e.g. any error signalled using the `error'
591 function, and many errors signalled from a primitive function) are
592 not continuable. If you return a value from them and continue
593 execution, then the error will immediately be signalled again.
594 Other errors (e.g. wrong-type-argument errors) will be continually
595 resignalled until the problem is corrected.
598 File: lispref.info, Node: Invoking the Debugger, Next: Internals of Debugger, Prev: Debugger Commands, Up: Debugger
600 Invoking the Debugger
601 ---------------------
603 Here we describe fully the function used to invoke the debugger.
605 - Function: debug &rest debugger-args
606 This function enters the debugger. It switches buffers to a buffer
607 named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
608 recursive entry to the debugger, etc.), and fills it with
609 information about the stack of Lisp function calls. It then
610 enters a recursive edit, showing the backtrace buffer in Debugger
613 The Debugger mode `c' and `r' commands exit the recursive edit;
614 then `debug' switches back to the previous buffer and returns to
615 whatever called `debug'. This is the only way the function
616 `debug' can return to its caller.
618 If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
619 if it is not one of the special values in the table below), then
620 `debug' displays the rest of its arguments at the top of the
621 `*Backtrace*' buffer. This mechanism is used to display a message
624 However, if the first argument passed to `debug' is one of the
625 following special values, then it has special significance.
626 Normally, these values are passed to `debug' only by the internals
627 of XEmacs and the debugger, and not by programmers calling `debug'.
629 The special values are:
632 A first argument of `lambda' means `debug' was called because
633 of entry to a function when `debug-on-next-call' was
634 non-`nil'. The debugger displays `Entering:' as a line of
635 text at the top of the buffer.
638 `debug' as first argument indicates a call to `debug' because
639 of entry to a function that was set to debug on entry. The
640 debugger displays `Entering:', just as in the `lambda' case.
641 It also marks the stack frame for that function so that it
642 will invoke the debugger when exited.
645 When the first argument is `t', this indicates a call to
646 `debug' due to evaluation of a list form when
647 `debug-on-next-call' is non-`nil'. The debugger displays the
648 following as the top line in the buffer:
650 Beginning evaluation of function call form:
653 When the first argument is `exit', it indicates the exit of a
654 stack frame previously marked to invoke the debugger on exit.
655 The second argument given to `debug' in this case is the
656 value being returned from the frame. The debugger displays
657 `Return value:' on the top line of the buffer, followed by
658 the value being returned.
661 When the first argument is `error', the debugger indicates
662 that it is being entered because an error or `quit' was
663 signaled and not handled, by displaying `Signaling:' followed
664 by the error signaled and any arguments to `signal'. For
667 (let ((debug-on-error t))
670 ------ Buffer: *Backtrace* ------
671 Signaling: (arith-error)
674 ------ Buffer: *Backtrace* ------
676 If an error was signaled, presumably the variable
677 `debug-on-error' is non-`nil'. If `quit' was signaled, then
678 presumably the variable `debug-on-quit' is non-`nil'.
681 Use `nil' as the first of the DEBUGGER-ARGS when you want to
682 enter the debugger explicitly. The rest of the DEBUGGER-ARGS
683 are printed on the top line of the buffer. You can use this
684 feature to display messages--for example, to remind yourself
685 of the conditions under which `debug' is called.
688 File: lispref.info, Node: Internals of Debugger, Prev: Invoking the Debugger, Up: Debugger
690 Internals of the Debugger
691 -------------------------
693 This section describes functions and variables used internally by the
697 The value of this variable is the function to call to invoke the
698 debugger. Its value must be a function of any number of arguments
699 (or, more typically, the name of a function). Presumably this
700 function will enter some kind of debugger. The default value of
701 the variable is `debug'.
703 The first argument that Lisp hands to the function indicates why it
704 was called. The convention for arguments is detailed in the
705 description of `debug'.
707 - Command: backtrace &optional stream detailed
708 This function prints a trace of Lisp function calls currently
709 active. This is the function used by `debug' to fill up the
710 `*Backtrace*' buffer. It is written in C, since it must have
711 access to the stack to determine which function calls are active.
712 The return value is always `nil'.
714 The backtrace is normally printed to `standard-output', but this
715 can be changed by specifying a value for STREAM. If DETAILED is
716 non-`nil', the backtrace also shows places where currently active
717 variable bindings, catches, condition-cases, and unwind-protects
718 were made as well as function calls.
720 In the following example, a Lisp expression calls `backtrace'
721 explicitly. This prints the backtrace to the stream
722 `standard-output': in this case, to the buffer `backtrace-output'.
723 Each line of the backtrace represents one function call. The
724 line shows the values of the function's arguments if they are all
725 known. If they are still being computed, the line says so. The
726 arguments of special forms are elided.
728 (with-output-to-temp-buffer "backtrace-output"
731 (setq var (eval '(progn
733 (list 'testing (backtrace))))))))
737 ----------- Buffer: backtrace-output ------------
739 (list ...computing arguments...)
741 eval((progn (1+ var) (list (quote testing) (backtrace))))
745 (with-output-to-temp-buffer ...)
746 eval-region(1973 2142 #<buffer *scratch*>)
747 byte-code("... for eval-print-last-sexp ...")
748 eval-print-last-sexp(nil)
749 * call-interactively(eval-print-last-sexp)
750 ----------- Buffer: backtrace-output ------------
752 The character `*' indicates a frame whose debug-on-exit flag is
755 - Variable: debug-on-next-call
756 If this variable is non-`nil', it says to call the debugger before
757 the next `eval', `apply' or `funcall'. Entering the debugger sets
758 `debug-on-next-call' to `nil'.
760 The `d' command in the debugger works by setting this variable.
762 - Function: backtrace-debug level flag
763 This function sets the debug-on-exit flag of the stack frame LEVEL
764 levels down the stack, giving it the value FLAG. If FLAG is
765 non-`nil', this will cause the debugger to be entered when that
766 frame later exits. Even a nonlocal exit through that frame will
769 This function is used only by the debugger.
771 - Variable: command-debug-status
772 This variable records the debugging status of the current
773 interactive command. Each time a command is called interactively,
774 this variable is bound to `nil'. The debugger can set this
775 variable to leave information for future debugger invocations
776 during the same command.
778 The advantage, for the debugger, of using this variable rather than
779 another global variable is that the data will never carry over to a
780 subsequent command invocation.
782 - Function: backtrace-frame frame-number
783 The function `backtrace-frame' is intended for use in Lisp
784 debuggers. It returns information about what computation is
785 happening in the stack frame FRAME-NUMBER levels down.
787 If that frame has not evaluated the arguments yet (or is a special
788 form), the value is `(nil FUNCTION ARG-FORMS...)'.
790 If that frame has evaluated its arguments and called its function
791 already, the value is `(t FUNCTION ARG-VALUES...)'.
793 In the return value, FUNCTION is whatever was supplied as the CAR
794 of the evaluated list, or a `lambda' expression in the case of a
795 macro call. If the function has a `&rest' argument, that is
796 represented as the tail of the list ARG-VALUES.
798 If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.
801 File: lispref.info, Node: Syntax Errors, Next: Compilation Errors, Prev: Debugger, Up: Debugging
803 Debugging Invalid Lisp Syntax
804 =============================
806 The Lisp reader reports invalid syntax, but cannot say where the real
807 problem is. For example, the error "End of file during parsing" in
808 evaluating an expression indicates an excess of open parentheses (or
809 square brackets). The reader detects this imbalance at the end of the
810 file, but it cannot figure out where the close parenthesis should have
811 been. Likewise, "Invalid read syntax: ")"" indicates an excess close
812 parenthesis or missing open parenthesis, but does not say where the
813 missing parenthesis belongs. How, then, to find what to change?
815 If the problem is not simply an imbalance of parentheses, a useful
816 technique is to try `C-M-e' at the beginning of each defun, and see if
817 it goes to the place where that defun appears to end. If it does not,
818 there is a problem in that defun.
820 However, unmatched parentheses are the most common syntax errors in
821 Lisp, and we can give further advice for those cases.
825 * Excess Open:: How to find a spurious open paren or missing close.
826 * Excess Close:: How to find a spurious close paren or missing open.
829 File: lispref.info, Node: Excess Open, Next: Excess Close, Up: Syntax Errors
831 Excess Open Parentheses
832 -----------------------
834 The first step is to find the defun that is unbalanced. If there is
835 an excess open parenthesis, the way to do this is to insert a close
836 parenthesis at the end of the file and type `C-M-b' (`backward-sexp').
837 This will move you to the beginning of the defun that is unbalanced.
838 (Then type `C-<SPC> C-_ C-u C-<SPC>' to set the mark there, undo the
839 insertion of the close parenthesis, and finally return to the mark.)
841 The next step is to determine precisely what is wrong. There is no
842 way to be sure of this except to study the program, but often the
843 existing indentation is a clue to where the parentheses should have
844 been. The easiest way to use this clue is to reindent with `C-M-q' and
847 Before you do this, make sure the defun has enough close parentheses.
848 Otherwise, `C-M-q' will get an error, or will reindent all the rest of
849 the file until the end. So move to the end of the defun and insert a
850 close parenthesis there. Don't use `C-M-e' to move there, since that
851 too will fail to work until the defun is balanced.
853 Now you can go to the beginning of the defun and type `C-M-q'.
854 Usually all the lines from a certain point to the end of the function
855 will shift to the right. There is probably a missing close parenthesis,
856 or a superfluous open parenthesis, near that point. (However, don't
857 assume this is true; study the code to make sure.) Once you have found
858 the discrepancy, undo the `C-M-q' with `C-_', since the old indentation
859 is probably appropriate to the intended parentheses.
861 After you think you have fixed the problem, use `C-M-q' again. If
862 the old indentation actually fit the intended nesting of parentheses,
863 and you have put back those parentheses, `C-M-q' should not change
867 File: lispref.info, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors
869 Excess Close Parentheses
870 ------------------------
872 To deal with an excess close parenthesis, first insert an open
873 parenthesis at the beginning of the file, back up over it, and type
874 `C-M-f' to find the end of the unbalanced defun. (Then type `C-<SPC>
875 C-_ C-u C-<SPC>' to set the mark there, undo the insertion of the open
876 parenthesis, and finally return to the mark.)
878 Then find the actual matching close parenthesis by typing `C-M-f' at
879 the beginning of the defun. This will leave you somewhere short of the
880 place where the defun ought to end. It is possible that you will find
881 a spurious close parenthesis in that vicinity.
883 If you don't see a problem at that point, the next thing to do is to
884 type `C-M-q' at the beginning of the defun. A range of lines will
885 probably shift left; if so, the missing open parenthesis or spurious
886 close parenthesis is probably near the first of those lines. (However,
887 don't assume this is true; study the code to make sure.) Once you have
888 found the discrepancy, undo the `C-M-q' with `C-_', since the old
889 indentation is probably appropriate to the intended parentheses.
891 After you think you have fixed the problem, use `C-M-q' again. If
892 the old indentation actually fit the intended nesting of parentheses,
893 and you have put back those parentheses, `C-M-q' should not change
897 File: lispref.info, Node: Compilation Errors, Next: Edebug, Prev: Syntax Errors, Up: Debugging
899 Debugging Problems in Compilation
900 =================================
902 When an error happens during byte compilation, it is normally due to
903 invalid syntax in the program you are compiling. The compiler prints a
904 suitable error message in the `*Compile-Log*' buffer, and then stops.
905 The message may state a function name in which the error was found, or
906 it may not. Either way, here is how to find out where in the file the
909 What you should do is switch to the buffer ` *Compiler Input*'.
910 (Note that the buffer name starts with a space, so it does not show up
911 in `M-x list-buffers'.) This buffer contains the program being
912 compiled, and point shows how far the byte compiler was able to read.
914 If the error was due to invalid Lisp syntax, point shows exactly
915 where the invalid syntax was _detected_. The cause of the error is not
916 necessarily near by! Use the techniques in the previous section to find
919 If the error was detected while compiling a form that had been read
920 successfully, then point is located at the end of the form. In this
921 case, this technique can't localize the error precisely, but can still
922 show you which function to check.
925 File: lispref.info, Node: Edebug, Prev: Compilation Errors, Up: Top
930 Edebug is a source-level debugger for XEmacs Lisp programs that
931 provides the following features:
933 * Step through evaluation, stopping before and after each expression.
935 * Set conditional or unconditional breakpoints, install embedded
936 breakpoints, or a global break event.
938 * Trace slow or fast stopping briefly at each stop point, or each
941 * Display expression results and evaluate expressions as if outside
942 of Edebug. Interface with the custom printing package for
943 printing circular structures.
945 * Automatically reevaluate a list of expressions and display their
946 results each time Edebug updates the display.
948 * Output trace info on function enter and exit.
950 * Errors stop before the source causing the error.
952 * Display backtrace without Edebug calls.
954 * Allow specification of argument evaluation for macros and defining
957 * Provide rudimentary coverage testing and display of frequency
961 The first three sections should tell you enough about Edebug to
962 enable you to use it.
966 * Using Edebug:: Introduction to use of Edebug.
967 * Instrumenting:: You must first instrument code.
968 * Edebug Execution Modes:: Execution modes, stopping more or less often.
969 * Jumping:: Commands to jump to a specified place.
970 * Edebug Misc:: Miscellaneous commands.
971 * Breakpoints:: Setting breakpoints to make the program stop.
972 * Trapping Errors:: trapping errors with Edebug.
973 * Edebug Views:: Views inside and outside of Edebug.
974 * Edebug Eval:: Evaluating expressions within Edebug.
975 * Eval List:: Automatic expression evaluation.
976 * Reading in Edebug:: Customization of reading.
977 * Printing in Edebug:: Customization of printing.
978 * Tracing:: How to produce tracing output.
979 * Coverage Testing:: How to test evaluation coverage.
980 * The Outside Context:: Data that Edebug saves and restores.
981 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
982 * Edebug Options:: Option variables for customizing Edebug.
985 File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug
990 To debug an XEmacs Lisp program with Edebug, you must first
991 "instrument" the Lisp code that you want to debug. If you want to just
992 try it now, load `edebug.el', move point into a definition and do `C-u
993 C-M-x' (`eval-defun' with a prefix argument). See *Note
994 Instrumenting:: for alternative ways to instrument code.
996 Once a function is instrumented, any call to the function activates
997 Edebug. Activating Edebug may stop execution and let you step through
998 the function, or it may update the display and continue execution while
999 checking for debugging commands, depending on the selected Edebug
1000 execution mode. The initial execution mode is `step', by default,
1001 which does stop execution. *Note Edebug Execution Modes::.
1003 Within Edebug, you normally view an XEmacs buffer showing the source
1004 of the Lisp function you are debugging. This is referred to as the
1005 "source code buffer"--but note that it is not always the same buffer
1006 depending on which function is currently being executed.
1008 An arrow at the left margin indicates the line where the function is
1009 executing. Point initially shows where within the line the function is
1010 executing, but you can move point yourself.
1012 If you instrument the definition of `fac' (shown below) and then
1013 execute `(fac 3)', here is what you normally see. Point is at the
1014 open-parenthesis before `if'.
1021 The places within a function where Edebug can stop execution are
1022 called "stop points". These occur both before and after each
1023 subexpression that is a list, and also after each variable reference.
1024 Here we show with periods the stop points found in the function `fac':
1028 .(* n. .(fac (1- n.).).).
1031 While the source code buffer is selected, the special commands of
1032 Edebug are available in it, in addition to the commands of XEmacs Lisp
1033 mode. (The buffer is temporarily made read-only, however.) For
1034 example, you can type the Edebug command <SPC> to execute until the
1035 next stop point. If you type <SPC> once after entry to `fac', here is
1036 the display you will see:
1043 When Edebug stops execution after an expression, it displays the
1044 expression's value in the echo area.
1046 Other frequently used commands are `b' to set a breakpoint at a stop
1047 point, `g' to execute until a breakpoint is reached, and `q' to exit to
1048 the top-level command loop. Type `?' to display a list of all Edebug
1052 File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug
1054 Instrumenting for Edebug
1055 ------------------------
1057 In order to use Edebug to debug Lisp code, you must first
1058 "instrument" the code. Instrumenting a form inserts additional code
1059 into it which invokes Edebug at the proper places. Furthermore, if
1060 Edebug detects a syntax error while instrumenting, point is left at the
1061 erroneous code and an `invalid-read-syntax' error is signaled.
1063 Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is
1064 redefined so that when invoked with a prefix argument on a definition,
1065 it instruments the definition before evaluating it. (The source code
1066 itself is not modified.) If the variable `edebug-all-defs' is
1067 non-`nil', that inverts the meaning of the prefix argument: then
1068 `C-M-x' instruments the definition _unless_ it has a prefix argument.
1069 The default value of `edebug-all-defs' is `nil'. The command `M-x
1070 edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
1072 If `edebug-all-defs' is non-`nil', then the commands `eval-region',
1073 `eval-current-buffer', and `eval-buffer' also instrument any
1074 definitions they evaluate. Similarly, `edebug-all-forms' controls
1075 whether `eval-region' should instrument _any_ form, even non-defining
1076 forms. This doesn't apply to loading or evaluations in the minibuffer.
1077 The command `M-x edebug-all-forms' toggles this option.
1079 Another command, `M-x edebug-eval-top-level-form', is available to
1080 instrument any top-level form regardless of the value of
1081 `edebug-all-defs' or `edebug-all-forms'.
1083 Just before Edebug instruments any code, it calls any functions in
1084 the variable `edebug-setup-hook' and resets its value to `nil'. You
1085 could use this to load up Edebug specifications associated with a
1086 package you are using but only when you also use Edebug. For example,
1087 `my-specs.el' may be loaded automatically when you use `my-package'
1088 with Edebug by including the following code in `my-package.el'.
1090 (add-hook 'edebug-setup-hook
1091 (function (lambda () (require 'my-specs))))
1093 While Edebug is active, the command `I' (`edebug-instrument-callee')
1094 instruments the definition of the function or macro called by the list
1095 form after point, if is not already instrumented. If the location of
1096 the definition is not known to Edebug, this command cannot be used.
1097 After loading Edebug, `eval-region' records the position of every
1098 definition it evaluates, even if not instrumenting it. Also see the
1099 command `i' (*Note Jumping::) which steps into the callee.
1101 Edebug knows how to instrument all the standard special forms, an
1102 interactive form with an expression argument, anonymous lambda
1103 expressions, and other defining forms. (Specifications for macros
1104 defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.)
1105 Edebug cannot know what a user-defined macro will do with the arguments
1106 of a macro call so you must tell it. See *Note Instrumenting Macro
1107 Calls:: for the details.
1109 Note that a couple ways remain to evaluate expressions without
1110 instrumenting them. Loading a file via the `load' subroutine does not
1111 instrument expressions for Edebug. Evaluations in the minibuffer via
1112 `eval-expression' (`M-ESC') are not instrumented.
1114 To remove instrumentation from a definition, simply reevaluate it
1115 with one of the non-instrumenting commands, or reload the file.
1117 See *Note Edebug Eval:: for other evaluation functions available
1121 File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
1123 Edebug Execution Modes
1124 ----------------------
1126 Edebug supports several execution modes for running the program you
1127 are debugging. We call these alternatives "Edebug execution modes"; do
1128 not confuse them with major or minor modes. The current Edebug
1129 execution mode determines how Edebug displays the progress of the
1130 evaluation, whether it stops at each stop point, or continues to the
1131 next breakpoint, for example.
1133 Normally, you specify the Edebug execution mode by typing a command
1134 to continue the program in a certain mode. Here is a table of these
1135 commands. All except for `S' resume execution of the program, at least
1136 for a certain distance.
1139 Stop: don't execute any more of the program for now, just wait for
1140 more Edebug commands (`edebug-stop').
1143 Step: stop at the next stop point encountered (`edebug-step-mode').
1146 Next: stop at the next stop point encountered after an expression
1147 (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note
1151 Trace: pause one second at each Edebug stop point
1152 (`edebug-trace-mode').
1155 Rapid trace: update at each stop point, but don't actually pause
1156 (`edebug-Trace-fast-mode').
1159 Go: run until the next breakpoint (`edebug-go-mode'). *Note
1163 Continue: pause for one second at each breakpoint, but don't stop
1164 (`edebug-continue-mode').
1167 Rapid continue: update at each breakpoint, but don't actually pause
1168 (`edebug-Continue-fast-mode').
1171 Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You
1172 can still stop the program by hitting any key.
1174 In general, the execution modes earlier in the above list run the
1175 program more slowly or stop sooner.
1177 When you enter a new Edebug level, the initial execution mode comes
1178 from the value of the variable `edebug-initial-mode'. By default, this
1179 specifies `step' mode. Note that you may reenter the same Edebug level
1180 several times if, for example, an instrumented function is called
1181 several times from one command.
1183 While executing or tracing, you can interrupt the execution by typing
1184 any Edebug command. Edebug stops the program at the next stop point and
1185 then executes the command that you typed. For example, typing `t'
1186 during execution switches to trace mode at the next stop point. You can
1187 use `S' to stop execution without doing anything else.
1189 If your function happens to read input, a character you hit
1190 intending to interrupt execution may be read by the function instead.
1191 You can avoid such unintended results by paying attention to when your
1192 program wants input.
1194 Keyboard macros containing Edebug commands do not work; when you exit
1195 from Edebug, to resume the program, whether you are defining or
1196 executing a keyboard macro is forgotten. Also, defining or executing a
1197 keyboard macro outside of Edebug does not affect the command loop inside
1198 Edebug. This is usually an advantage. But see
1199 `edebug-continue-kbd-macro'.