-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
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
happen in process filter functions and sentinels. Therefore, these
errors also can invoke the debugger. *Note Processes::.
+ - 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.
+
- 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
(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
(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
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