+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger
-
-Entering the Debugger on an Error
----------------------------------
-
- The most important time to enter the debugger is when a Lisp error
-happens. This allows you to investigate the immediate causes of the
-error.
-
- However, entry to the debugger is not a normal consequence of an
-error. Many commands frequently get Lisp errors when invoked in
-inappropriate contexts (such as `C-f' at the end of the buffer) and
-during ordinary editing it would be very unpleasant to enter the
-debugger each time this happens. If you want errors to enter the
-debugger, set the variable `debug-on-error' to non-`nil'.
-
- - User Option: debug-on-error
- This variable determines whether the debugger is called when an
- error is signaled and not handled. If `debug-on-error' is `t', all
- errors call the debugger. If it is `nil', none call the debugger.
-
- The value can also be a list of error conditions that should call
- the debugger. For example, if you set it to the list
- `(void-variable)', then only errors about a variable that has no
- value invoke the debugger.
-
- When this variable is non-`nil', Emacs does not catch errors that
- happen in process filter functions and sentinels. Therefore, these
- errors also can invoke the debugger. *Note Processes::.
-
- - User Option: debug-ignored-errors
- This variable specifies certain kinds of errors that should not
- enter the debugger. Its value is a list of error condition
- symbols and/or regular expressions. If the error has any of those
- condition symbols, or if the error message matches any of the
- regular expressions, then that error does not enter the debugger,
- regardless of the value of `debug-on-error'.
-
- The normal value of this variable lists several errors that happen
- often during editing but rarely result from bugs in Lisp programs.
-
- To debug an error that happens during loading of the `.emacs' file,
-use the option `-debug-init', which binds `debug-on-error' to `t' while
-`.emacs' is loaded and inhibits use of `condition-case' to catch init
-file errors.
-
- If your `.emacs' file sets `debug-on-error', the effect may not last
-past the end of loading `.emacs'. (This is an undesirable byproduct of
-the code that implements the `-debug-init' command line option.) The
-best way to make `.emacs' set `debug-on-error' permanently is with
-`after-init-hook', like this:
-
- (add-hook 'after-init-hook
- '(lambda () (setq debug-on-error t)))
-
- - User Option: debug-on-signal
- This variable is similar to `debug-on-error' but breaks whenever
- an error is signalled, regardless of whether it would be handled.
-
-\1f
-File: lispref.info, Node: Infinite Loops, Next: Function Debugging, Prev: Error Debugging, Up: Debugger
-
-Debugging Infinite Loops
-------------------------
-
- When a program loops infinitely and fails to return, your first
-problem is to stop the loop. On most operating systems, you can do this
-with `C-g', which causes quit.
-
- Ordinary quitting gives no information about why the program was
-looping. To get more information, you can set the variable
-`debug-on-quit' to non-`nil'. Quitting with `C-g' is not considered an
-error, and `debug-on-error' has no effect on the handling of `C-g'.
-Likewise, `debug-on-quit' has no effect on errors.
-
- Once you have the debugger running in the middle of the infinite
-loop, you can proceed from the debugger using the stepping commands.
-If you step through the entire loop, you will probably get enough
-information to solve the problem.
-
- - User Option: debug-on-quit
- This variable determines whether the debugger is called when `quit'
- is signaled and not handled. If `debug-on-quit' is non-`nil',
- then the debugger is called whenever you quit (that is, type
- `C-g'). If `debug-on-quit' is `nil', then the debugger is not
- called when you quit. *Note Quitting::.
-
-\1f
-File: lispref.info, Node: Function Debugging, Next: Explicit Debug, Prev: Infinite Loops, Up: Debugger
-
-Entering the Debugger on a Function Call
-----------------------------------------
-
- To investigate a problem that happens in the middle of a program, one
-useful technique is to enter the debugger whenever a certain function is
-called. You can do this to the function in which the problem occurs,
-and then step through the function, or you can do this to a function
-called shortly before the problem, step quickly over the call to that
-function, and then step through its caller.
-
- - Command: debug-on-entry FUNCTION-NAME
- This function requests FUNCTION-NAME to invoke the debugger each
- time it is called. It works by inserting the form `(debug
- 'debug)' into the function definition as the first form.
-
- Any function defined as Lisp code may be set to break on entry,
- regardless of whether it is interpreted code or compiled code. If
- the function is a command, it will enter the debugger when called
- from Lisp and when called interactively (after the reading of the
- arguments). You can't debug primitive functions (i.e., those
- written in C) this way.
-
- When `debug-on-entry' is called interactively, it prompts for
- FUNCTION-NAME in the minibuffer.
-
- If the function is already set up to invoke the debugger on entry,
- `debug-on-entry' does nothing.
-
- *Please note:* if you redefine a function after using
- `debug-on-entry' on it, the code to enter the debugger is lost.
-
- `debug-on-entry' returns FUNCTION-NAME.
-
- (defun fact (n)
- (if (zerop n) 1
- (* n (fact (1- n)))))
- => fact
- (debug-on-entry 'fact)
- => fact
- (fact 3)
-
- ------ Buffer: *Backtrace* ------
- Entering:
- * fact(3)
- eval-region(4870 4878 t)
- byte-code("...")
- eval-last-sexp(nil)
- (let ...)
- eval-insert-last-sexp(nil)
- * call-interactively(eval-insert-last-sexp)
- ------ Buffer: *Backtrace* ------
-
- (symbol-function 'fact)
- => (lambda (n)
- (debug (quote debug))
- (if (zerop n) 1 (* n (fact (1- n)))))
-
- - Command: cancel-debug-on-entry FUNCTION-NAME
- This function undoes the effect of `debug-on-entry' on
- FUNCTION-NAME. When called interactively, it prompts for
- FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the
- empty string, it cancels debugging for all functions.
-
- If `cancel-debug-on-entry' is called more than once on the same
- function, the second call does nothing. `cancel-debug-on-entry'
- returns FUNCTION-NAME.
-
-\1f
-File: lispref.info, Node: Explicit Debug, Next: Using Debugger, Prev: Function Debugging, Up: Debugger
-
-Explicit Entry to the Debugger
-------------------------------
-
- You can cause the debugger to be called at a certain point in your
-program by writing the expression `(debug)' at that point. To do this,
-visit the source file, insert the text `(debug)' at the proper place,
-and type `C-M-x'. Be sure to undo this insertion before you save the
-file!
-
- The place where you insert `(debug)' must be a place where an
-additional form can be evaluated and its value ignored. (If the value
-of `(debug)' isn't ignored, it will alter the execution of the
-program!) The most common suitable places are inside a `progn' or an
-implicit `progn' (*note Sequencing::.).
-
-\1f
-File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
-
-Using the Debugger
-------------------
-
- When the debugger is entered, it displays the previously selected
-buffer in one window and a buffer named `*Backtrace*' in another
-window. The backtrace buffer contains one line for each level of Lisp
-function execution currently going on. At the beginning of this buffer
-is a message describing the reason that the debugger was invoked (such
-as the error message and associated data, if it was invoked due to an
-error).
-
- The backtrace buffer is read-only and uses a special major mode,
-Debugger mode, in which letters are defined as debugger commands. The
-usual XEmacs editing commands are available; thus, you can switch
-windows to examine the buffer that was being edited at the time of the
-error, switch buffers, visit files, or do any other sort of editing.
-However, the debugger is a recursive editing level (*note Recursive
-Editing::.) and it is wise to go back to the backtrace buffer and exit
-the debugger (with the `q' command) when you are finished with it.
-Exiting the debugger gets out of the recursive edit and kills the
-backtrace buffer.
-
- The backtrace buffer shows you the functions that are executing and
-their argument values. It also allows you to specify a stack frame by
-moving point to the line describing that frame. (A stack frame is the
-place where the Lisp interpreter records information about a particular
-invocation of a function.) The frame whose line point is on is
-considered the "current frame". Some of the debugger commands operate
-on the current frame.
-
- The debugger itself must be run byte-compiled, since it makes
-assumptions about how many stack frames are used for the debugger
-itself. These assumptions are false if the debugger is running
-interpreted.
-
-\1f
-File: lispref.info, Node: Debugger Commands, Next: Invoking the Debugger, Prev: Using Debugger, Up: Debugger
-
-Debugger Commands
------------------
-
- Inside the debugger (in Debugger mode), these special commands are
-available in addition to the usual cursor motion commands. (Keep in
-mind that all the usual facilities of XEmacs, such as switching windows
-or buffers, are still available.)
-
- The most important use of debugger commands is for stepping through
-code, so that you can see how control flows. The debugger can step
-through the control structures of an interpreted function, but cannot do
-so in a byte-compiled function. If you would like to step through a
-byte-compiled function, replace it with an interpreted definition of the
-same function. (To do this, visit the source file for the function and
-type `C-M-x' on its definition.)
-
- Here is a list of Debugger mode commands:
-
-`c'
- Exit the debugger and continue execution. This resumes execution
- of the program as if the debugger had never been entered (aside
- from the effect of any variables or data structures you may have
- changed while inside the debugger).
-
- Continuing when an error or quit was signalled will cause the
- normal action of the signalling to take place. If you do not want
- this to happen, but instead want the program execution to continue
- as if the call to `signal' did not occur, use the `r' command.
-
-`d'
- Continue execution, but enter the debugger the next time any Lisp
- function is called. This allows you to step through the
- subexpressions of an expression, seeing what values the
- subexpressions compute, and what else they do.
-
- The stack frame made for the function call which enters the
- debugger in this way will be flagged automatically so that the
- debugger will be called again when the frame is exited. You can
- use the `u' command to cancel this flag.
-
-`b'
- Flag the current frame so that the debugger will be entered when
- the frame is exited. Frames flagged in this way are marked with
- stars in the backtrace buffer.
-
-`u'
- Don't enter the debugger when the current frame is exited. This
- cancels a `b' command on that frame.
-
-`e'
- Read a Lisp expression in the minibuffer, evaluate it, and print
- the value in the echo area. The debugger alters certain important
- variables, and the current buffer, as part of its operation; `e'
- temporarily restores their outside-the-debugger values so you can
- examine them. This makes the debugger more transparent. By
- contrast, `M-:' does nothing special in the debugger; it shows you
- the variable values within the debugger.
-
-`q'
- Terminate the program being debugged; return to top-level XEmacs
- command execution.
-
- If the debugger was entered due to a `C-g' but you really want to
- quit, and not debug, use the `q' command.
-
-`r'
- Return a value from the debugger. The value is computed by
- reading an expression with the minibuffer and evaluating it.
-
- The `r' command is useful when the debugger was invoked due to exit
- from a Lisp call frame (as requested with `b'); then the value
- specified in the `r' command is used as the value of that frame.
- It is also useful if you call `debug' and use its return value.
-
- If the debugger was entered at the beginning of a function call,
- `r' has the same effect as `c', and the specified return value
- does not matter.
-
- If the debugger was entered through a call to `signal' (i.e. as a
- result of an error or quit), then returning a value will cause the
- call to `signal' itself to return, rather than throwing to
- top-level or invoking a handler, as is normal. This allows you to
- correct an error (e.g. the type of an argument was wrong) or
- continue from a `debug-on-quit' as if it never happened.
-
- Note that some errors (e.g. any error signalled using the `error'
- function, and many errors signalled from a primitive function) are
- not continuable. If you return a value from them and continue
- execution, then the error will immediately be signalled again.
- Other errors (e.g. wrong-type-argument errors) will be continually
- resignalled until the problem is corrected.
-
-\1f
-File: lispref.info, Node: Invoking the Debugger, Next: Internals of Debugger, Prev: Debugger Commands, Up: Debugger
-
-Invoking the Debugger
----------------------
-
- Here we describe fully the function used to invoke the debugger.
-
- - Function: debug &rest DEBUGGER-ARGS
- This function enters the debugger. It switches buffers to a buffer
- named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
- recursive entry to the debugger, etc.), and fills it with
- information about the stack of Lisp function calls. It then
- enters a recursive edit, showing the backtrace buffer in Debugger
- mode.
-
- The Debugger mode `c' and `r' commands exit the recursive edit;
- then `debug' switches back to the previous buffer and returns to
- whatever called `debug'. This is the only way the function
- `debug' can return to its caller.
-
- If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
- if it is not one of the special values in the table below), then
- `debug' displays the rest of its arguments at the top of the
- `*Backtrace*' buffer. This mechanism is used to display a message
- to the user.
-
- However, if the first argument passed to `debug' is one of the
- following special values, then it has special significance.
- Normally, these values are passed to `debug' only by the internals
- of XEmacs and the debugger, and not by programmers calling `debug'.
-
- The special values are:
-
- `lambda'
- A first argument of `lambda' means `debug' was called because
- of entry to a function when `debug-on-next-call' was
- non-`nil'. The debugger displays `Entering:' as a line of
- text at the top of the buffer.
-
- `debug'
- `debug' as first argument indicates a call to `debug' because
- of entry to a function that was set to debug on entry. The
- debugger displays `Entering:', just as in the `lambda' case.
- It also marks the stack frame for that function so that it
- will invoke the debugger when exited.
-
- `t'
- When the first argument is `t', this indicates a call to
- `debug' due to evaluation of a list form when
- `debug-on-next-call' is non-`nil'. The debugger displays the
- following as the top line in the buffer:
-
- Beginning evaluation of function call form:
-
- `exit'
- When the first argument is `exit', it indicates the exit of a
- stack frame previously marked to invoke the debugger on exit.
- The second argument given to `debug' in this case is the
- value being returned from the frame. The debugger displays
- `Return value:' on the top line of the buffer, followed by
- the value being returned.
-
- `error'
- When the first argument is `error', the debugger indicates
- that it is being entered because an error or `quit' was
- signaled and not handled, by displaying `Signaling:' followed
- by the error signaled and any arguments to `signal'. For
- example,
-
- (let ((debug-on-error t))
- (/ 1 0))
-
- ------ Buffer: *Backtrace* ------
- Signaling: (arith-error)
- /(1 0)
- ...
- ------ Buffer: *Backtrace* ------
-
- If an error was signaled, presumably the variable
- `debug-on-error' is non-`nil'. If `quit' was signaled, then
- presumably the variable `debug-on-quit' is non-`nil'.
-
- `nil'
- Use `nil' as the first of the DEBUGGER-ARGS when you want to
- enter the debugger explicitly. The rest of the DEBUGGER-ARGS
- are printed on the top line of the buffer. You can use this
- feature to display messages--for example, to remind yourself
- of the conditions under which `debug' is called.
-
-\1f
-File: lispref.info, Node: Internals of Debugger, Prev: Invoking the Debugger, Up: Debugger
-
-Internals of the Debugger
--------------------------
-
- This section describes functions and variables used internally by the
-debugger.
-
- - Variable: debugger
- The value of this variable is the function to call to invoke the
- debugger. Its value must be a function of any number of arguments
- (or, more typically, the name of a function). Presumably this
- function will enter some kind of debugger. The default value of
- the variable is `debug'.
-
- The first argument that Lisp hands to the function indicates why it
- was called. The convention for arguments is detailed in the
- description of `debug'.
-
- - Command: backtrace &optional STREAM DETAILED
- This function prints a trace of Lisp function calls currently
- active. This is the function used by `debug' to fill up the
- `*Backtrace*' buffer. It is written in C, since it must have
- access to the stack to determine which function calls are active.
- The return value is always `nil'.
-
- The backtrace is normally printed to `standard-output', but this
- can be changed by specifying a value for STREAM. If DETAILED is
- non-`nil', the backtrace also shows places where currently active
- variable bindings, catches, condition-cases, and unwind-protects
- were made as well as function calls.
-
- In the following example, a Lisp expression calls `backtrace'
- explicitly. This prints the backtrace to the stream
- `standard-output': in this case, to the buffer `backtrace-output'.
- Each line of the backtrace represents one function call. The
- line shows the values of the function's arguments if they are all
- known. If they are still being computed, the line says so. The
- arguments of special forms are elided.
-
- (with-output-to-temp-buffer "backtrace-output"
- (let ((var 1))
- (save-excursion
- (setq var (eval '(progn
- (1+ var)
- (list 'testing (backtrace))))))))
-
- => nil
-
- ----------- Buffer: backtrace-output ------------
- backtrace()
- (list ...computing arguments...)
- (progn ...)
- eval((progn (1+ var) (list (quote testing) (backtrace))))
- (setq ...)
- (save-excursion ...)
- (let ...)
- (with-output-to-temp-buffer ...)
- eval-region(1973 2142 #<buffer *scratch*>)
- byte-code("... for eval-print-last-sexp ...")
- eval-print-last-sexp(nil)
- * call-interactively(eval-print-last-sexp)
- ----------- Buffer: backtrace-output ------------
-
- The character `*' indicates a frame whose debug-on-exit flag is
- set.
-
- - Variable: debug-on-next-call
- If this variable is non-`nil', it says to call the debugger before
- the next `eval', `apply' or `funcall'. Entering the debugger sets
- `debug-on-next-call' to `nil'.
-
- The `d' command in the debugger works by setting this variable.
-
- - Function: backtrace-debug LEVEL FLAG
- This function sets the debug-on-exit flag of the stack frame LEVEL
- levels down the stack, giving it the value FLAG. If FLAG is
- non-`nil', this will cause the debugger to be entered when that
- frame later exits. Even a nonlocal exit through that frame will
- enter the debugger.
-
- This function is used only by the debugger.
-
- - Variable: command-debug-status
- This variable records the debugging status of the current
- interactive command. Each time a command is called interactively,
- this variable is bound to `nil'. The debugger can set this
- variable to leave information for future debugger invocations
- during the same command.
-
- The advantage, for the debugger, of using this variable rather than
- another global variable is that the data will never carry over to a
- subsequent command invocation.
-
- - Function: backtrace-frame FRAME-NUMBER
- The function `backtrace-frame' is intended for use in Lisp
- debuggers. It returns information about what computation is
- happening in the stack frame FRAME-NUMBER levels down.
-
- If that frame has not evaluated the arguments yet (or is a special
- form), the value is `(nil FUNCTION ARG-FORMS...)'.
-
- If that frame has evaluated its arguments and called its function
- already, the value is `(t FUNCTION ARG-VALUES...)'.
-
- In the return value, FUNCTION is whatever was supplied as the CAR
- of the evaluated list, or a `lambda' expression in the case of a
- macro call. If the function has a `&rest' argument, that is
- represented as the tail of the list ARG-VALUES.
-
- If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.
-
-\1f
-File: lispref.info, Node: Syntax Errors, Next: Compilation Errors, Prev: Debugger, Up: Debugging
-
-Debugging Invalid Lisp Syntax
-=============================
-
- The Lisp reader reports invalid syntax, but cannot say where the real
-problem is. For example, the error "End of file during parsing" in
-evaluating an expression indicates an excess of open parentheses (or
-square brackets). The reader detects this imbalance at the end of the
-file, but it cannot figure out where the close parenthesis should have
-been. Likewise, "Invalid read syntax: ")"" indicates an excess close
-parenthesis or missing open parenthesis, but does not say where the
-missing parenthesis belongs. How, then, to find what to change?
-
- If the problem is not simply an imbalance of parentheses, a useful
-technique is to try `C-M-e' at the beginning of each defun, and see if
-it goes to the place where that defun appears to end. If it does not,
-there is a problem in that defun.
-
- However, unmatched parentheses are the most common syntax errors in
-Lisp, and we can give further advice for those cases.
-
-* Menu:
-
-* Excess Open:: How to find a spurious open paren or missing close.
-* Excess Close:: How to find a spurious close paren or missing open.
-
-\1f
-File: lispref.info, Node: Excess Open, Next: Excess Close, Up: Syntax Errors
-
-Excess Open Parentheses
------------------------
-
- The first step is to find the defun that is unbalanced. If there is
-an excess open parenthesis, the way to do this is to insert a close
-parenthesis at the end of the file and type `C-M-b' (`backward-sexp').
-This will move you to the beginning of the defun that is unbalanced.
-(Then type `C-<SPC> C-_ C-u C-<SPC>' to set the mark there, undo the
-insertion of the close parenthesis, and finally return to the mark.)
-
- The next step is to determine precisely what is wrong. There is no
-way to be sure of this except to study the program, but often the
-existing indentation is a clue to where the parentheses should have
-been. The easiest way to use this clue is to reindent with `C-M-q' and
-see what moves.
-
- Before you do this, make sure the defun has enough close parentheses.
-Otherwise, `C-M-q' will get an error, or will reindent all the rest of
-the file until the end. So move to the end of the defun and insert a
-close parenthesis there. Don't use `C-M-e' to move there, since that
-too will fail to work until the defun is balanced.
-
- Now you can go to the beginning of the defun and type `C-M-q'.
-Usually all the lines from a certain point to the end of the function
-will shift to the right. There is probably a missing close parenthesis,
-or a superfluous open parenthesis, near that point. (However, don't
-assume this is true; study the code to make sure.) Once you have found
-the discrepancy, undo the `C-M-q' with `C-_', since the old indentation
-is probably appropriate to the intended parentheses.
-
- After you think you have fixed the problem, use `C-M-q' again. If
-the old indentation actually fit the intended nesting of parentheses,
-and you have put back those parentheses, `C-M-q' should not change
-anything.
-
-\1f
-File: lispref.info, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors
-
-Excess Close Parentheses
-------------------------
-
- To deal with an excess close parenthesis, first insert an open
-parenthesis at the beginning of the file, back up over it, and type
-`C-M-f' to find the end of the unbalanced defun. (Then type `C-<SPC>
-C-_ C-u C-<SPC>' to set the mark there, undo the insertion of the open
-parenthesis, and finally return to the mark.)
-
- Then find the actual matching close parenthesis by typing `C-M-f' at
-the beginning of the defun. This will leave you somewhere short of the
-place where the defun ought to end. It is possible that you will find
-a spurious close parenthesis in that vicinity.
-
- If you don't see a problem at that point, the next thing to do is to
-type `C-M-q' at the beginning of the defun. A range of lines will
-probably shift left; if so, the missing open parenthesis or spurious
-close parenthesis is probably near the first of those lines. (However,
-don't assume this is true; study the code to make sure.) Once you have
-found the discrepancy, undo the `C-M-q' with `C-_', since the old
-indentation is probably appropriate to the intended parentheses.
-
- After you think you have fixed the problem, use `C-M-q' again. If
-the old indentation actually fit the intended nesting of parentheses,
-and you have put back those parentheses, `C-M-q' should not change
-anything.
-
-\1f
-File: lispref.info, Node: Compilation Errors, Next: Edebug, Prev: Syntax Errors, Up: Debugging
-
-Debugging Problems in Compilation
-=================================
-
- When an error happens during byte compilation, it is normally due to
-invalid syntax in the program you are compiling. The compiler prints a
-suitable error message in the `*Compile-Log*' buffer, and then stops.
-The message may state a function name in which the error was found, or
-it may not. Either way, here is how to find out where in the file the
-error occurred.
-
- What you should do is switch to the buffer ` *Compiler Input*'.
-(Note that the buffer name starts with a space, so it does not show up
-in `M-x list-buffers'.) This buffer contains the program being
-compiled, and point shows how far the byte compiler was able to read.
-
- If the error was due to invalid Lisp syntax, point shows exactly
-where the invalid syntax was *detected*. The cause of the error is not
-necessarily near by! Use the techniques in the previous section to find
-the error.
-
- If the error was detected while compiling a form that had been read
-successfully, then point is located at the end of the form. In this
-case, this technique can't localize the error precisely, but can still
-show you which function to check.
-
-\1f
-File: lispref.info, Node: Edebug, Prev: Compilation Errors, Up: Top
-
-Edebug
-======
-
- Edebug is a source-level debugger for XEmacs Lisp programs that
-provides the following features:
-
- * Step through evaluation, stopping before and after each expression.
-
- * Set conditional or unconditional breakpoints, install embedded
- breakpoints, or a global break event.
-
- * Trace slow or fast stopping briefly at each stop point, or each
- breakpoint.
-
- * Display expression results and evaluate expressions as if outside
- of Edebug. Interface with the custom printing package for
- printing circular structures.
-
- * Automatically reevaluate a list of expressions and display their
- results each time Edebug updates the display.
-
- * Output trace info on function enter and exit.
-
- * Errors stop before the source causing the error.
-
- * Display backtrace without Edebug calls.
-
- * Allow specification of argument evaluation for macros and defining
- forms.
-
- * Provide rudimentary coverage testing and display of frequency
- counts.
-
- The first three sections should tell you enough about Edebug to
-enable you to use it.
-
-* Menu:
-
-* Using Edebug:: Introduction to use of Edebug.
-* Instrumenting:: You must first instrument code.
-* Edebug Execution Modes:: Execution modes, stopping more or less often.
-* Jumping:: Commands to jump to a specified place.
-* Edebug Misc:: Miscellaneous commands.
-* Breakpoints:: Setting breakpoints to make the program stop.
-* Trapping Errors:: trapping errors with Edebug.
-* Edebug Views:: Views inside and outside of Edebug.
-* Edebug Eval:: Evaluating expressions within Edebug.
-* Eval List:: Automatic expression evaluation.
-* Reading in Edebug:: Customization of reading.
-* Printing in Edebug:: Customization of printing.
-* Tracing:: How to produce tracing output.
-* Coverage Testing:: How to test evaluation coverage.
-* The Outside Context:: Data that Edebug saves and restores.
-* Instrumenting Macro Calls:: Specifying how to handle macro calls.
-* Edebug Options:: Option variables for customizing Edebug.
-
-\1f
-File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug
-
-Using Edebug
-------------
-
- To debug an XEmacs Lisp program with Edebug, you must first
-"instrument" the Lisp code that you want to debug. If you want to just
-try it now, load `edebug.el', move point into a definition and do `C-u
-C-M-x' (`eval-defun' with a prefix argument). See *Note
-Instrumenting:: for alternative ways to instrument code.
-
- Once a function is instrumented, any call to the function activates
-Edebug. Activating Edebug may stop execution and let you step through
-the function, or it may update the display and continue execution while
-checking for debugging commands, depending on the selected Edebug
-execution mode. The initial execution mode is `step', by default,
-which does stop execution. *Note Edebug Execution Modes::.
-
- Within Edebug, you normally view an XEmacs buffer showing the source
-of the Lisp function you are debugging. This is referred to as the
-"source code buffer"--but note that it is not always the same buffer
-depending on which function is currently being executed.
-
- An arrow at the left margin indicates the line where the function is
-executing. Point initially shows where within the line the function is
-executing, but you can move point yourself.
-
- If you instrument the definition of `fac' (shown below) and then
-execute `(fac 3)', here is what you normally see. Point is at the
-open-parenthesis before `if'.
-
- (defun fac (n)
- =>-!-(if (< 0 n)
- (* n (fac (1- n)))
- 1))
-
- The places within a function where Edebug can stop execution are
-called "stop points". These occur both before and after each
-subexpression that is a list, and also after each variable reference.
-Here we show with periods the stop points found in the function `fac':
-
- (defun fac (n)
- .(if .(< 0 n.).
- .(* n. .(fac (1- n.).).).
- 1).)
-
- While the source code buffer is selected, the special commands of
-Edebug are available in it, in addition to the commands of XEmacs Lisp
-mode. (The buffer is temporarily made read-only, however.) For
-example, you can type the Edebug command <SPC> to execute until the
-next stop point. If you type <SPC> once after entry to `fac', here is
-the display you will see:
-
- (defun fac (n)
- =>(if -!-(< 0 n)
- (* n (fac (1- n)))
- 1))
-
- When Edebug stops execution after an expression, it displays the
-expression's value in the echo area.
-
- Other frequently used commands are `b' to set a breakpoint at a stop
-point, `g' to execute until a breakpoint is reached, and `q' to exit to
-the top-level command loop. Type `?' to display a list of all Edebug
-commands.
-
-\1f
-File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug
-
-Instrumenting for Edebug
-------------------------
-
- In order to use Edebug to debug Lisp code, you must first
-"instrument" the code. Instrumenting a form inserts additional code
-into it which invokes Edebug at the proper places. Furthermore, if
-Edebug detects a syntax error while instrumenting, point is left at the
-erroneous code and an `invalid-read-syntax' error is signaled.
-
- Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is
-redefined so that when invoked with a prefix argument on a definition,
-it instruments the definition before evaluating it. (The source code
-itself is not modified.) If the variable `edebug-all-defs' is
-non-`nil', that inverts the meaning of the prefix argument: then
-`C-M-x' instruments the definition *unless* it has a prefix argument.
-The default value of `edebug-all-defs' is `nil'. The command `M-x
-edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
-
- If `edebug-all-defs' is non-`nil', then the commands `eval-region',
-`eval-current-buffer', and `eval-buffer' also instrument any
-definitions they evaluate. Similarly, `edebug-all-forms' controls
-whether `eval-region' should instrument *any* form, even non-defining
-forms. This doesn't apply to loading or evaluations in the minibuffer.
-The command `M-x edebug-all-forms' toggles this option.
-
- Another command, `M-x edebug-eval-top-level-form', is available to
-instrument any top-level form regardless of the value of
-`edebug-all-defs' or `edebug-all-forms'.
-
- Just before Edebug instruments any code, it calls any functions in
-the variable `edebug-setup-hook' and resets its value to `nil'. You
-could use this to load up Edebug specifications associated with a
-package you are using but only when you also use Edebug. For example,
-`my-specs.el' may be loaded automatically when you use `my-package'
-with Edebug by including the following code in `my-package.el'.
-
- (add-hook 'edebug-setup-hook
- (function (lambda () (require 'my-specs))))
-
- While Edebug is active, the command `I' (`edebug-instrument-callee')
-instruments the definition of the function or macro called by the list
-form after point, if is not already instrumented. If the location of
-the definition is not known to Edebug, this command cannot be used.
-After loading Edebug, `eval-region' records the position of every
-definition it evaluates, even if not instrumenting it. Also see the
-command `i' (*Note Jumping::) which steps into the callee.
-
- Edebug knows how to instrument all the standard special forms, an
-interactive form with an expression argument, anonymous lambda
-expressions, and other defining forms. (Specifications for macros
-defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.)
-Edebug cannot know what a user-defined macro will do with the arguments
-of a macro call so you must tell it. See *Note Instrumenting Macro
-Calls:: for the details.
-
- Note that a couple ways remain to evaluate expressions without
-instrumenting them. Loading a file via the `load' subroutine does not
-instrument expressions for Edebug. Evaluations in the minibuffer via
-`eval-expression' (`M-ESC') are not instrumented.
-
- To remove instrumentation from a definition, simply reevaluate it
-with one of the non-instrumenting commands, or reload the file.
-
- See *Note Edebug Eval:: for other evaluation functions available
-inside of Edebug.
-
-\1f
-File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
-
-Edebug Execution Modes
-----------------------
-
- Edebug supports several execution modes for running the program you
-are debugging. We call these alternatives "Edebug execution modes"; do
-not confuse them with major or minor modes. The current Edebug
-execution mode determines how Edebug displays the progress of the
-evaluation, whether it stops at each stop point, or continues to the
-next breakpoint, for example.
-
- Normally, you specify the Edebug execution mode by typing a command
-to continue the program in a certain mode. Here is a table of these
-commands. All except for `S' resume execution of the program, at least
-for a certain distance.
-
-`S'
- Stop: don't execute any more of the program for now, just wait for
- more Edebug commands (`edebug-stop').
-
-`<SPC>'
- Step: stop at the next stop point encountered (`edebug-step-mode').
-
-`n'
- Next: stop at the next stop point encountered after an expression
- (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note
- Edebug Misc::.
-
-`t'
- Trace: pause one second at each Edebug stop point
- (`edebug-trace-mode').
-
-`T'
- Rapid trace: update at each stop point, but don't actually pause
- (`edebug-Trace-fast-mode').
-
-`g'
- Go: run until the next breakpoint (`edebug-go-mode'). *Note
- Breakpoints::.
-
-`c'
- Continue: pause for one second at each breakpoint, but don't stop
- (`edebug-continue-mode').
-
-`C'
- Rapid continue: update at each breakpoint, but don't actually pause
- (`edebug-Continue-fast-mode').
-
-`G'
- Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You
- can still stop the program by hitting any key.
-
- In general, the execution modes earlier in the above list run the
-program more slowly or stop sooner.
-
- When you enter a new Edebug level, the initial execution mode comes
-from the value of the variable `edebug-initial-mode'. By default, this
-specifies `step' mode. Note that you may reenter the same Edebug level
-several times if, for example, an instrumented function is called
-several times from one command.
-
- While executing or tracing, you can interrupt the execution by typing
-any Edebug command. Edebug stops the program at the next stop point and
-then executes the command that you typed. For example, typing `t'
-during execution switches to trace mode at the next stop point. You can
-use `S' to stop execution without doing anything else.
-
- If your function happens to read input, a character you hit
-intending to interrupt execution may be read by the function instead.
-You can avoid such unintended results by paying attention to when your
-program wants input.
-
- Keyboard macros containing Edebug commands do not work; when you exit
-from Edebug, to resume the program, whether you are defining or
-executing a keyboard macro is forgotten. Also, defining or executing a
-keyboard macro outside of Edebug does not affect the command loop inside
-Edebug. This is usually an advantage. But see
-`edebug-continue-kbd-macro'.
-
-\1f
-File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug
-
-Jumping
--------
-
- Commands described here let you jump to a specified location. All,
-except `i', use temporary breakpoints to establish the stop point and
-then switch to `go' mode. Any other breakpoint reached before the
-intended stop point will also stop execution. See *Note Breakpoints::
-for the details on breakpoints.
-
-`f'
- Run the program forward over one expression
- (`edebug-forward-sexp'). More precisely, set a temporary
- breakpoint at the position that `C-M-f' would reach, then execute
- in `go' mode so that the program will stop at breakpoints.
-
- With a prefix argument N, the temporary breakpoint is placed N
- sexps beyond point. If the containing list ends before N more
- elements, then the place to stop is after the containing
- expression.
-
- Be careful that the position `C-M-f' finds is a place that the
- program will really get to; this may not be true in a `cond', for
- example.
-
- This command does `forward-sexp' starting at point rather than the
- stop point. If you want to execute one expression from the
- current stop point, type `w' first, to move point there.
-
-`o'
- Continue "out of" an expression (`edebug-step-out'). It places a
- temporary breakpoint at the end of the sexp containing point.
-
- If the containing sexp is a function definition itself, it
- continues until just before the last sexp in the definition. If
- that is where you are now, it returns from the function and then
- stops. In other words, this command does not exit the currently
- executing function unless you are positioned after the last sexp.
-
-`I'
- Step into the function or macro after point after first ensuring
- that it is instrumented. It does this by calling
- `edebug-on-entry' and then switching to `go' mode.
-
- Although the automatic instrumentation is convenient, it is not
- later automatically uninstrumented.
-
-`h'
- Proceed to the stop point near where point is using a temporary
- breakpoint (`edebug-goto-here').
-
- All the commands in this section may fail to work as expected in case
-of nonlocal exit, because a nonlocal exit can bypass the temporary
-breakpoint where you expected the program to stop.
-
-\1f
-File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug
-
-Miscellaneous
--------------
-
- Some miscellaneous commands are described here.
-
-`?'
- Display the help message for Edebug (`edebug-help').
-
-`C-]'
- Abort one level back to the previous command level
- (`abort-recursive-edit').
-
-`q'
- Return to the top level editor command loop (`top-level'). This
- exits all recursive editing levels, including all levels of Edebug
- activity. However, instrumented code protected with
- `unwind-protect' or `condition-case' forms may resume debugging.
-
-`Q'
- Like `q' but don't stop even for protected code
- (`top-level-nonstop').
-
-`r'
- Redisplay the most recently known expression result in the echo
- area (`edebug-previous-result').
-
-`d'
- Display a backtrace, excluding Edebug's own functions for clarity
- (`edebug-backtrace').
-
- You cannot use debugger commands in the backtrace buffer in Edebug
- as you would in the standard debugger.
-
- The backtrace buffer is killed automatically when you continue
- execution.
-
- From the Edebug recursive edit, you may invoke commands that activate
-Edebug again recursively. Any time Edebug is active, you can quit to
-the top level with `q' or abort one recursive edit level with `C-]'.
-You can display a backtrace of all the pending evaluations with `d'.
-
-\1f
-File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug
-
-Breakpoints
------------
-
- There are three more ways to stop execution once it has started:
-breakpoints, the global break condition, and embedded breakpoints.
-
- While using Edebug, you can specify "breakpoints" in the program you
-are testing: points where execution should stop. You can set a
-breakpoint at any stop point, as defined in *Note Using Edebug::. For
-setting and unsetting breakpoints, the stop point that is affected is
-the first one at or after point in the source code buffer. Here are the
-Edebug commands for breakpoints:
-
-`b'
- Set a breakpoint at the stop point at or after point
- (`edebug-set-breakpoint'). If you use a prefix argument, the
- breakpoint is temporary (it turns off the first time it stops the
- program).
-
-`u'
- Unset the breakpoint (if any) at the stop point at or after the
- current point (`edebug-unset-breakpoint').
-
-`x CONDITION <RET>'
- Set a conditional breakpoint which stops the program only if
- CONDITION evaluates to a non-`nil' value
- (`edebug-set-conditional-breakpoint'). If you use a prefix
- argument, the breakpoint is temporary (it turns off the first time
- it stops the program).
-
-`B'
- Move point to the next breakpoint in the definition
- (`edebug-next-breakpoint').
-
- While in Edebug, you can set a breakpoint with `b' and unset one
-with `u'. First you must move point to a position at or before the
-desired Edebug stop point, then hit the key to change the breakpoint.
-Unsetting a breakpoint that has not been set does nothing.
-
- Reevaluating or reinstrumenting a definition clears all its
-breakpoints.
-
- A "conditional breakpoint" tests a condition each time the program
-gets there. To set a conditional breakpoint, use `x', and specify the
-condition expression in the minibuffer. Setting a conditional
-breakpoint at a stop point that already has a conditional breakpoint
-puts the current condition expression in the minibuffer so you can edit
-it.
-
- You can make both conditional and unconditional breakpoints
-"temporary" by using a prefix arg to the command to set the breakpoint.
-After breaking at a temporary breakpoint, it is automatically cleared.
-
- Edebug always stops or pauses at a breakpoint except when the Edebug
-mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely.
-
- To find out where your breakpoints are, use `B', which moves point
-to the next breakpoint in the definition following point, or to the
-first breakpoint if there are no following breakpoints. This command
-does not continue execution--it just moves point in the buffer.
-
-* Menu:
-
-* Global Break Condition:: Breaking on an event.
-* Embedded Breakpoints:: Embedding breakpoints in code.
-
-\1f
-File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints
-
-Global Break Condition
-......................
-
- In contrast to breaking when execution reaches specified locations,
-you can also cause a break when a certain event occurs. The "global
-break condition" is a condition that is repeatedly evaluated at every
-stop point. If it evaluates to a non-`nil' value, then execution is
-stopped or paused depending on the execution mode, just like a
-breakpoint. Any errors that might occur as a result of evaluating the
-condition are ignored, as if the result were `nil'.
-
- You can set or edit the condition expression, stored in
-`edebug-global-break-condition', using `X'
-(`edebug-set-global-break-condition').
-
- Using the global break condition is perhaps the fastest way to find
-where in your code some event occurs, but since it is rather expensive
-you should reset the condition to `nil' when not in use.
-
-\1f
-File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints
-
-Embedded Breakpoints
-....................
-
- Since all breakpoints in a definition are cleared each time you
-reinstrument it, you might rather create an "embedded breakpoint" which
-is simply a call to the function `edebug'. You can, of course, make
-such a call conditional. For example, in the `fac' function, insert
-the first line as shown below to stop when the argument reaches zero:
-
- (defun fac (n)
- (if (= n 0) (edebug))
- (if (< 0 n)
- (* n (fac (1- n)))
- 1))
-
- When the `fac' definition is instrumented and the function is
-called, Edebug will stop before the call to `edebug'. Depending on the
-execution mode, Edebug will stop or pause.
-
- However, if no instrumented code is being executed, calling `edebug'
-will instead invoke `debug'. Calling `debug' will always invoke the
-standard backtrace debugger.
-
projects / chise / xemacs-chise.git- / blobdiff