-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Disassembly, Next: Different Behavior, Prev: Compiled-Function Objects, Up: Byte Compilation
+
+Disassembled Byte-Code
+======================
+
+ People do not write byte-code; that job is left to the byte compiler.
+But we provide a disassembler to satisfy a cat-like curiosity. The
+disassembler converts the byte-compiled code into humanly readable form.
+
+ The byte-code interpreter is implemented as a simple stack machine.
+It pushes values onto a stack of its own, then pops them off to use them
+in calculations whose results are themselves pushed back on the stack.
+When a byte-code function returns, it pops a value off the stack and
+returns it as the value of the function.
+
+ In addition to the stack, byte-code functions can use, bind, and set
+ordinary Lisp variables, by transferring values between variables and
+the stack.
+
+ - Command: disassemble object &optional stream
+ This function prints the disassembled code for OBJECT. If STREAM
+ is supplied, then output goes there. Otherwise, the disassembled
+ code is printed to the stream `standard-output'. The argument
+ OBJECT can be a function name or a lambda expression.
+
+ As a special exception, if this function is used interactively, it
+ outputs to a buffer named `*Disassemble*'.
+
+ Here are two examples of using the `disassemble' function. We have
+added explanatory comments to help you relate the byte-code to the Lisp
+source; these do not appear in the output of `disassemble'.
+
+ (defun factorial (integer)
+ "Compute factorial of an integer."
+ (if (= 1 integer) 1
+ (* integer (factorial (1- integer)))))
+ => factorial
+
+ (factorial 4)
+ => 24
+
+ (disassemble 'factorial)
+ -| byte-code for factorial:
+ doc: Compute factorial of an integer.
+ args: (integer)
+
+ 0 varref integer ; Get value of `integer'
+ ; from the environment
+ ; and push the value
+ ; onto the stack.
+
+ 1 constant 1 ; Push 1 onto stack.
+
+ 2 eqlsign ; Pop top two values off stack,
+ ; compare them,
+ ; and push result onto stack.
+
+ 3 goto-if-nil 1 ; Pop and test top of stack;
+ ; if `nil',
+ ; go to label 1 (which is also byte 7),
+ ; else continue.
+
+ 5 constant 1 ; Push 1 onto top of stack.
+
+ 6 return ; Return the top element
+ ; of the stack.
+
+ 7:1 varref integer ; Push value of `integer' onto stack.
+
+ 8 constant factorial ; Push `factorial' onto stack.
+
+ 9 varref integer ; Push value of `integer' onto stack.
+
+ 10 sub1 ; Pop `integer', decrement value,
+ ; push new value onto stack.
+
+ ; Stack now contains:
+ ; - decremented value of `integer'
+ ; - `factorial'
+ ; - value of `integer'
+
+ 15 call 1 ; Call function `factorial' using
+ ; the first (i.e., the top) element
+ ; of the stack as the argument;
+ ; push returned value onto stack.
+
+ ; Stack now contains:
+ ; - result of recursive
+ ; call to `factorial'
+ ; - value of `integer'
+
+ 12 mult ; Pop top two values off the stack,
+ ; multiply them,
+ ; pushing the result onto the stack.
+
+ 13 return ; Return the top element
+ ; of the stack.
+ => nil
+
+ The `silly-loop' function is somewhat more complex:
+
+ (defun silly-loop (n)
+ "Return time before and after N iterations of a loop."
+ (let ((t1 (current-time-string)))
+ (while (> (setq n (1- n))
+ 0))
+ (list t1 (current-time-string))))
+ => silly-loop
+
+ (disassemble 'silly-loop)
+ -| byte-code for silly-loop:
+ doc: Return time before and after N iterations of a loop.
+ args: (n)
+
+ 0 constant current-time-string ; Push
+ ; `current-time-string'
+ ; onto top of stack.
+
+ 1 call 0 ; Call `current-time-string'
+ ; with no argument,
+ ; pushing result onto stack.
+
+ 2 varbind t1 ; Pop stack and bind `t1'
+ ; to popped value.
+
+ 3:1 varref n ; Get value of `n' from
+ ; the environment and push
+ ; the value onto the stack.
+
+ 4 sub1 ; Subtract 1 from top of stack.
+
+ 5 dup ; Duplicate the top of the stack;
+ ; i.e., copy the top of
+ ; the stack and push the
+ ; copy onto the stack.
+
+ 6 varset n ; Pop the top of the stack,
+ ; and set `n' to the value.
+
+ ; In effect, the sequence `dup varset'
+ ; copies the top of the stack
+ ; into the value of `n'
+ ; without popping it.
+
+ 7 constant 0 ; Push 0 onto stack.
+
+ 8 gtr ; Pop top two values off stack,
+ ; test if N is greater than 0
+ ; and push result onto stack.
+
+ 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0
+ ; (this exits the while loop).
+ ; else pop top of stack
+ ; and continue
+
+ 11 varref t1 ; Push value of `t1' onto stack.
+
+ 12 constant current-time-string ; Push
+ ; `current-time-string'
+ ; onto top of stack.
+
+ 13 call 0 ; Call `current-time-string' again.
+
+ 14 unbind 1 ; Unbind `t1' in local environment.
+
+ 15 list2 ; Pop top two elements off stack,
+ ; create a list of them,
+ ; and push list onto stack.
+
+ 16 return ; Return the top element of the stack.
+
+ => nil
+
+\1f
+File: lispref.info, Node: Different Behavior, Prev: Disassembly, Up: Byte Compilation
+
+Different Behavior
+==================
+
+ The intent is that compiled byte-code and the corresponding code
+executed by the Lisp interpreter produce identical results. However,
+there are some circumstances where the results will differ.
+
+ * Arithmetic operations may be rearranged for efficiency or
+ compile-time evaluation. When floating point numbers are
+ involved, this may produce different values or an overflow.
+
+ * Some arithmetic operations may be optimized away. For example, the
+ expression `(+ x)' may be optimized to simply `x'. If the value
+ of `x' is a marker, then the value will be a marker instead of an
+ integer. If the value of `x' is a cons cell, then the interpreter
+ will issue an error, while the bytecode will not.
+
+ If you're trying to use `(+ OBJECT 0)' to convert OBJECT to
+ integer, consider using an explicit conversion function, which is
+ clearer and guaranteed to work. Instead of `(+ MARKER 0)', use
+ `(marker-position MARKER)'. Instead of `(+ CHAR 0)', use
+ `(char-int CHAR)'.
+
+ For maximal equivalence between interpreted and compiled code, the
+variables `byte-compile-delete-errors' and `byte-compile-optimize' can
+be set to `nil', but this is not recommended.
+
+\1f
+File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top
+
+Debugging Lisp Programs
+***********************
+
+ There are three ways to investigate a problem in an XEmacs Lisp
+program, depending on what you are doing with the program when the
+problem appears.
+
+ * If the problem occurs when you run the program, you can use a Lisp
+ debugger (either the default debugger or Edebug) to investigate
+ what is happening during execution.
+
+ * If the problem is syntactic, so that Lisp cannot even read the
+ program, you can use the XEmacs facilities for editing Lisp to
+ localize it.
+
+ * If the problem occurs when trying to compile the program with the
+ byte compiler, you need to know how to examine the compiler's
+ input buffer.
+
+* Menu:
+
+* Debugger:: How the XEmacs Lisp debugger is implemented.
+* Syntax Errors:: How to find syntax errors.
+* Compilation Errors:: How to find errors that show up in byte compilation.
+* Edebug:: A source-level XEmacs Lisp debugger.
+
+ Another useful debugging tool is the dribble file. When a dribble
+file is open, XEmacs copies all keyboard input characters to that file.
+Afterward, you can examine the file to find out what input was used.
+*Note Terminal Input::.
+
+ For debugging problems in terminal descriptions, the
+`open-termscript' function can be useful. *Note Terminal Output::.
+
+\1f
+File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging
+
+The Lisp Debugger
+=================
+
+ The "Lisp debugger" provides the ability to suspend evaluation of a
+form. While evaluation is suspended (a state that is commonly known as
+a "break"), you may examine the run time stack, examine the values of
+local or global variables, or change those values. Since a break is a
+recursive edit, all the usual editing facilities of XEmacs are
+available; you can even run programs that will enter the debugger
+recursively. *Note Recursive Editing::.
+
+* Menu:
+
+* Error Debugging:: Entering the debugger when an error happens.
+* Infinite Loops:: Stopping and debugging a program that doesn't exit.
+* Function Debugging:: Entering it when a certain function is called.
+* Explicit Debug:: Entering it at a certain point in the program.
+* Using Debugger:: What the debugger does; what you see while in it.
+* Debugger Commands:: Commands used while in the debugger.
+* Invoking the Debugger:: How to call the function `debug'.
+* Internals of Debugger:: Subroutines of the debugger, and global variables.
+
+\1f
File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger
Entering the Debugger on an Error
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
+ - 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.
(debug (quote debug))
(if (zerop n) 1 (* n (fact (1- n)))))
- - Command: cancel-debug-on-entry FUNCTION-NAME
+ - Command: cancel-debug-on-entry &optional 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
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::.).
+implicit `progn' (*note Sequencing::).
\1f
File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
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
+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.
Here we describe fully the function used to invoke the debugger.
- - Function: debug &rest DEBUGGER-ARGS
+ - 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
was called. The convention for arguments is detailed in the
description of `debug'.
- - Command: backtrace &optional STREAM DETAILED
+ - 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
(list 'testing (backtrace))))))))
=> nil
-
+
----------- Buffer: backtrace-output ------------
backtrace()
(list ...computing arguments...)
The `d' command in the debugger works by setting this variable.
- - Function: backtrace-debug LEVEL FLAG
+ - 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
another global variable is that the data will never carry over to a
subsequent command invocation.
- - Function: backtrace-frame FRAME-NUMBER
+ - 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.
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
+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.
* 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.
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.
+`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
+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.
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