[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to edebug.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to edebug.texi |
|
Date: |
Thu, 06 Sep 2007 04:10:40 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:10:40
Index: edebug.texi
===================================================================
RCS file: edebug.texi
diff -N edebug.texi
--- edebug.texi 7 Apr 2007 02:06:21 -0000 1.40
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,1582 +0,0 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003,
2004,
address@hidden 2005, 2006, 2007 Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
-
address@hidden This file can also be used by an independent Edebug User
address@hidden Manual in which case the Edebug node below should be used
address@hidden with the following links to the Bugs section and to the top
level:
-
address@hidden , Bugs and Todo List, Top, Top
-
address@hidden Edebug, Syntax Errors, Debugger, Debugging
address@hidden Edebug
address@hidden Edebug debugging facility
-
- Edebug is a source-level debugger for Emacs Lisp programs with which
-you can:
-
address@hidden @bullet
address@hidden
-Step through evaluation, stopping before and after each expression.
-
address@hidden
-Set conditional or unconditional breakpoints.
-
address@hidden
-Stop when a specified condition is true (the global break event).
-
address@hidden
-Trace slow or fast, stopping briefly at each stop point, or
-at each breakpoint.
-
address@hidden
-Display expression results and evaluate expressions as if outside of
-Edebug.
-
address@hidden
-Automatically re-evaluate a list of expressions and
-display their results each time Edebug updates the display.
-
address@hidden
-Output trace info on function enter and exit.
-
address@hidden
-Stop when an error occurs.
-
address@hidden
-Display a backtrace, omitting Edebug's own frames.
-
address@hidden
-Specify argument evaluation for macros and defining forms.
-
address@hidden
-Obtain rudimentary coverage testing and frequency counts.
address@hidden itemize
-
-The first three sections below should tell you enough about Edebug to
-enable you to use it.
-
address@hidden
-* Using Edebug:: Introduction to use of Edebug.
-* Instrumenting:: You must instrument your code
- in order to debug it with Edebug.
-* Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
-* Jumping:: Commands to jump to a specified place.
-* Misc: Edebug Misc. Miscellaneous commands.
-* Breaks:: Setting breakpoints to make the program stop.
-* Trapping Errors:: Trapping errors with Edebug.
-* Views: Edebug Views. Views inside and outside of Edebug.
-* Eval: Edebug Eval. Evaluating expressions within Edebug.
-* Eval List:: Expressions whose values are displayed
- each time you enter Edebug.
-* Printing in Edebug:: Customization of printing.
-* Trace Buffer:: How to produce trace output in a buffer.
-* Coverage Testing:: How to test evaluation coverage.
-* The Outside Context:: Data that Edebug saves and restores.
-* Edebug and Macros:: Specifying how to handle macro calls.
-* Options: Edebug Options. Option variables for customizing Edebug.
address@hidden menu
-
address@hidden Using Edebug
address@hidden Using Edebug
-
- To debug a Lisp program with Edebug, you must first @dfn{instrument}
-the Lisp code that you want to debug. A simple way to do this is to
-first move point into the definition of a function or macro and then do
address@hidden C-M-x} (@code{eval-defun} with a prefix argument). See
address@hidden, for alternative ways to instrument code.
-
- Once a function is instrumented, any call to the function activates
-Edebug. Depending on which Edebug execution mode you have selected,
-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. The default execution mode is step,
-which stops execution. @xref{Edebug Execution Modes}.
-
- Within Edebug, you normally view an Emacs buffer showing the source of
-the Lisp code you are debugging. This is referred to as the @dfn{source
-code buffer}, and it is temporarily read-only.
-
- An arrow in the left fringe indicates the line where the function is
-executing. Point initially shows where within the line the function is
-executing, but this ceases to be true if you move point yourself.
-
- If you instrument the definition of @code{fac} (shown below) and then
-execute @code{(fac 3)}, here is what you would normally see. Point is
-at the open-parenthesis before @code{if}.
-
address@hidden
-(defun fac (n)
-=>@point{}(if (< 0 n)
- (* n (fac (1- n)))
- 1))
address@hidden example
-
address@hidden stop points
-The places within a function where Edebug can stop execution are called
address@hidden points}. These occur both before and after each subexpression
-that is a list, and also after each variable reference.
-Here we use periods to show the stop points in the function
address@hidden:
-
address@hidden
-(defun fac (n)
- .(if .(< 0 n.).
- .(* n. .(fac .(1- n.).).).
- 1).)
address@hidden example
-
-The special commands of Edebug are available in the source code buffer
-in addition to the commands of Emacs Lisp mode. For example, you can
-type the Edebug command @key{SPC} to execute until the next stop point.
-If you type @key{SPC} once after entry to @code{fac}, here is the
-display you will see:
-
address@hidden
-(defun fac (n)
-=>(if @point{}(< 0 n)
- (* n (fac (1- n)))
- 1))
address@hidden example
-
-When Edebug stops execution after an expression, it displays the
-expression's value in the echo area.
-
-Other frequently used commands are @kbd{b} to set a breakpoint at a stop
-point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
-exit Edebug and return to the top-level command loop. Type @kbd{?} to
-display a list of all Edebug commands.
-
address@hidden Instrumenting
address@hidden Instrumenting for Edebug
-
- In order to use Edebug to debug Lisp code, you must first
address@hidden the code. Instrumenting code inserts additional code
-into it, to invoke Edebug at the proper places.
-
address@hidden C-M-x
address@hidden eval-defun (Edebug)
- When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
-prefix argument on a function definition, it instruments the
-definition before evaluating it. (This does not modify the source
-code itself.) If the variable @code{edebug-all-defs} is
address@hidden, that inverts the meaning of the prefix argument: in
-this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
-a prefix argument. The default value of @code{edebug-all-defs} is
address@hidden The command @kbd{M-x edebug-all-defs} toggles the value
-of the variable @code{edebug-all-defs}.
-
address@hidden eval-region @r{(Edebug)}
address@hidden eval-buffer @r{(Edebug)}
address@hidden eval-current-buffer @r{(Edebug)}
- If @code{edebug-all-defs} is address@hidden, then the commands
address@hidden, @code{eval-current-buffer}, and @code{eval-buffer}
-also instrument any definitions they evaluate. Similarly,
address@hidden controls whether @code{eval-region} should
-instrument @emph{any} form, even non-defining forms. This doesn't apply
-to loading or evaluations in the minibuffer. The command @kbd{M-x
-edebug-all-forms} toggles this option.
-
address@hidden edebug-eval-top-level-form
- Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
-instrument any top-level form regardless of the values of
address@hidden and @code{edebug-all-forms}.
-
- While Edebug is active, the command @kbd{I}
-(@code{edebug-instrument-callee}) instruments the definition of the
-function or macro called by the list form after point, if is not already
-instrumented. This is possible only if Edebug knows where to find the
-source for that function; for this reading, after loading Edebug,
address@hidden records the position of every definition it
-evaluates, even if not instrumenting it. See also the @kbd{i} command
-(@pxref{Jumping}), which steps into the call after instrumenting the
-function.
-
- Edebug knows how to instrument all the standard special forms,
address@hidden forms with an expression argument, anonymous lambda
-expressions, and other defining forms. However, Edebug cannot determine
-on its own what a user-defined macro will do with the arguments of a
-macro call, so you must provide that information using Edebug
-specifications; see @ref{Edebug and Macros}, for details.
-
- When Edebug is about to instrument code for the first time in a
-session, it runs the hook @code{edebug-setup-hook}, then sets it to
address@hidden You can use this to load Edebug specifications
-associated with a package you are using, but only when you use Edebug.
-
address@hidden eval-expression @r{(Edebug)}
- To remove instrumentation from a definition, simply re-evaluate its
-definition in a way that does not instrument. There are two ways of
-evaluating forms that never instrument them: from a file with
address@hidden, and from the minibuffer with @code{eval-expression}
-(@kbd{M-:}).
-
- If Edebug detects a syntax error while instrumenting, it leaves point
-at the erroneous code and signals an @code{invalid-read-syntax} error.
-
- @xref{Edebug Eval}, for other evaluation functions available
-inside of Edebug.
-
address@hidden Edebug Execution Modes
address@hidden Edebug Execution Modes
-
address@hidden Edebug execution modes
-Edebug supports several execution modes for running the program you are
-debugging. We call these alternatives @dfn{Edebug execution modes}; do
-not confuse them with major or minor modes. The current Edebug execution mode
-determines how far Edebug continues execution before stopping---whether
-it stops at each stop point, or continues to the next breakpoint, for
-example---and how much Edebug displays the progress of the evaluation
-before it stops.
-
-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 @kbd{S} resume execution of the program, at
-least for a certain distance.
-
address@hidden @kbd
address@hidden S
-Stop: don't execute any more of the program, but wait for more
-Edebug commands (@code{edebug-stop}).
-
address@hidden @key{SPC}
-Step: stop at the next stop point encountered (@code{edebug-step-mode}).
-
address@hidden n
-Next: stop at the next stop point encountered after an expression
-(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
address@hidden
-
address@hidden t
-Trace: pause (normally one second) at each Edebug stop point
-(@code{edebug-trace-mode}).
-
address@hidden T
-Rapid trace: update the display at each stop point, but don't actually
-pause (@code{edebug-Trace-fast-mode}).
-
address@hidden g
-Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
-
address@hidden c
-Continue: pause one second at each breakpoint, and then continue
-(@code{edebug-continue-mode}).
-
address@hidden C
-Rapid continue: move point to each breakpoint, but don't pause
-(@code{edebug-Continue-fast-mode}).
-
address@hidden G
-Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
-can still stop the program by typing @kbd{S}, or any editing command.
address@hidden table
-
-In general, the execution modes earlier in the above list run the
-program more slowly or stop sooner than the modes later in the list.
-
-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 you typed. For example, typing @kbd{t} during
-execution switches to trace mode at the next stop point. You can use
address@hidden to stop execution without doing anything else.
-
-If your function happens to read input, a character you type 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.
-
address@hidden keyboard macros (Edebug)
-Keyboard macros containing the commands in this section do not
-completely work: exiting from Edebug, to resume the program, loses track
-of the keyboard macro. This is not easy to fix. Also, defining or
-executing a keyboard macro outside of Edebug does not affect commands
-inside Edebug. This is usually an advantage. See also the
address@hidden option (@pxref{Edebug Options}).
-
-When you enter a new Edebug level, the initial execution mode comes
-from the value of the variable @code{edebug-initial-mode}.
-(@xref{Edebug Options}.) 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.
-
address@hidden edebug-sit-for-seconds
-This option specifies how many seconds to wait between execution steps
-in trace mode. The default is 1 second.
address@hidden defopt
-
address@hidden Jumping
address@hidden Jumping
-
- The commands described in this section execute until they reach a
-specified location. All except @kbd{i} make a temporary breakpoint to
-establish the place to stop, then switch to go mode. Any other
-breakpoint reached before the intended stop point will also stop
-execution. @xref{Breakpoints}, for the details on breakpoints.
-
- These commands may fail to work as expected in case of nonlocal exit,
-as that can bypass the temporary breakpoint where you expected the
-program to stop.
-
address@hidden @kbd
address@hidden h
-Proceed to the stop point near where point is (@code{edebug-goto-here}).
-
address@hidden f
-Run the program for one expression
-(@code{edebug-forward-sexp}).
-
address@hidden o
-Run the program until the end of the containing sexp.
-
address@hidden i
-Step into the function or macro called by the form after point.
address@hidden table
-
-The @kbd{h} command proceeds to the stop point at or after the current
-location of point, using a temporary breakpoint.
-
-The @kbd{f} command runs the program forward over one expression. More
-precisely, it sets a temporary breakpoint at the position that
address@hidden would reach, then executes in go mode so that the program
-will stop at breakpoints.
-
-With a prefix argument @var{n}, the temporary breakpoint is placed
address@hidden sexps beyond point. If the containing list ends before @var{n}
-more elements, then the place to stop is after the containing
-expression.
-
-You must check that the position @kbd{C-M-f} finds is a place that the
-program will really get to. In @code{cond}, for example, this may not
-be true.
-
-For flexibility, the @kbd{f} command does @code{forward-sexp} starting
-at point, rather than at the stop point. If you want to execute one
-expression @emph{from the current stop point}, first type @kbd{w}, to
-move point there, and then type @kbd{f}.
-
-The @kbd{o} command continues ``out of'' an expression. It places a
-temporary breakpoint at the end of the sexp containing point. If the
-containing sexp is a function definition itself, @kbd{o} 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.
-
-The @kbd{i} command steps into the function or macro called by the list
-form after point, and stops at its first stop point. Note that the form
-need not be the one about to be evaluated. But if the form is a
-function call about to be evaluated, remember to use this command before
-any of the arguments are evaluated, since otherwise it will be too late.
-
-The @kbd{i} command instruments the function or macro it's supposed to
-step into, if it isn't instrumented already. This is convenient, but keep
-in mind that the function or macro remains instrumented unless you explicitly
-arrange to deinstrument it.
-
address@hidden Edebug Misc
address@hidden Miscellaneous Edebug Commands
-
- Some miscellaneous Edebug commands are described here.
-
address@hidden @kbd
address@hidden ?
-Display the help message for Edebug (@code{edebug-help}).
-
address@hidden C-]
-Abort one level back to the previous command level
-(@code{abort-recursive-edit}).
-
address@hidden q
-Return to the top level editor command loop (@code{top-level}). This
-exits all recursive editing levels, including all levels of Edebug
-activity. However, instrumented code protected with
address@hidden or @code{condition-case} forms may resume
-debugging.
-
address@hidden Q
-Like @kbd{q}, but don't stop even for protected code
-(@code{top-level-nonstop}).
-
address@hidden r
-Redisplay the most recently known expression result in the echo area
-(@code{edebug-previous-result}).
-
address@hidden d
-Display a backtrace, excluding Edebug's own functions for clarity
-(@code{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.
address@hidden table
-
-You can invoke commands from Edebug that activate Edebug again
-recursively. Whenever Edebug is active, you can quit to the top level
-with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
-display a backtrace of all the pending evaluations with @kbd{d}.
-
address@hidden Breaks
address@hidden Breaks
-
-Edebug's step mode stops execution when the next stop point is reached.
-There are three other ways to stop Edebug execution once it has started:
-breakpoints, the global break condition, and source breakpoints.
-
address@hidden
-* Breakpoints:: Breakpoints at stop points.
-* Global Break Condition:: Breaking on an event.
-* Source Breakpoints:: Embedding breakpoints in source code.
address@hidden menu
-
address@hidden Breakpoints
address@hidden Edebug Breakpoints
-
address@hidden breakpoints (Edebug)
-While using Edebug, you can specify @dfn{breakpoints} in the program you
-are testing: these are places where execution should stop. You can set a
-breakpoint at any stop point, as defined in @ref{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:
-
address@hidden @kbd
address@hidden b
-Set a breakpoint at the stop point at or after point
-(@code{edebug-set-breakpoint}). If you use a prefix argument, the
-breakpoint is temporary---it turns off the first time it stops the
-program.
-
address@hidden u
-Unset the breakpoint (if any) at the stop point at or after
-point (@code{edebug-unset-breakpoint}).
-
address@hidden x @var{condition} @key{RET}
-Set a conditional breakpoint which stops the program only if
-evaluating @var{condition} produces a address@hidden value
-(@code{edebug-set-conditional-breakpoint}). With a prefix argument,
-the breakpoint is temporary.
-
address@hidden B
-Move point to the next breakpoint in the current definition
-(@code{edebug-next-breakpoint}).
address@hidden table
-
-While in Edebug, you can set a breakpoint with @kbd{b} and unset one
-with @kbd{u}. First move point to the Edebug stop point of your choice,
-then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
-Unsetting a breakpoint where none has been set has no effect.
-
-Re-evaluating or reinstrumenting a definition removes all of its
-previous breakpoints.
-
-A @dfn{conditional breakpoint} tests a condition each time the program
-gets there. Any errors that occur as a result of evaluating the
-condition are ignored, as if the result were @code{nil}. To set a
-conditional breakpoint, use @kbd{x}, and specify the condition
-expression in the minibuffer. Setting a conditional breakpoint at a
-stop point that has a previously established conditional breakpoint puts
-the previous condition expression in the minibuffer so you can edit it.
-
-You can make a conditional or unconditional breakpoint
address@hidden by using a prefix argument with the command to set the
-breakpoint. When a temporary breakpoint stops the program, it is
-automatically unset.
-
-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 the @kbd{B} command, which
-moves point to the next breakpoint following point, within the same
-function, or to the first breakpoint if there are no following
-breakpoints. This command does not continue execution---it just moves
-point in the buffer.
-
address@hidden Global Break Condition
address@hidden Global Break Condition
-
address@hidden stopping on events
address@hidden global break condition
- A @dfn{global break condition} stops execution when a specified
-condition is satisfied, no matter where that may occur. Edebug
-evaluates the global break condition at every stop point; if it
-evaluates to a address@hidden value, then execution stops or pauses
-depending on the execution mode, as if a breakpoint had been hit. If
-evaluating the condition gets an error, execution does not stop.
-
address@hidden edebug-set-global-break-condition
- The condition expression is stored in
address@hidden You can specify a new expression
-using the @kbd{X} command from the source code buffer while Edebug is
-active, or using @kbd{C-x X X} from any buffer at any time, as long as
-Edebug is loaded (@code{edebug-set-global-break-condition}).
-
- The global break condition is the simplest way to find where in your
-code some event occurs, but it makes code run much more slowly. So you
-should reset the condition to @code{nil} when not using it.
-
address@hidden Source Breakpoints
address@hidden Source Breakpoints
-
address@hidden edebug
address@hidden source breakpoints
- All breakpoints in a definition are forgotten each time you
-reinstrument it. If you wish to make a breakpoint that won't be
-forgotten, you can write a @dfn{source breakpoint}, which is simply a
-call to the function @code{edebug} in your source code. You can, of
-course, make such a call conditional. For example, in the @code{fac}
-function, you can insert the first line as shown below, to stop when the
-argument reaches zero:
-
address@hidden
-(defun fac (n)
- (if (= n 0) (edebug))
- (if (< 0 n)
- (* n (fac (1- n)))
- 1))
address@hidden example
-
- When the @code{fac} definition is instrumented and the function is
-called, the call to @code{edebug} acts as a breakpoint. Depending on
-the execution mode, Edebug stops or pauses there.
-
- If no instrumented code is being executed when @code{edebug} is called,
-that function calls @code{debug}.
address@hidden This may not be a good idea anymore.
-
address@hidden Trapping Errors
address@hidden Trapping Errors
-
- Emacs normally displays an error message when an error is signaled and
-not handled with @code{condition-case}. While Edebug is active and
-executing instrumented code, it normally responds to all unhandled
-errors. You can customize this with the options @code{edebug-on-error}
-and @code{edebug-on-quit}; see @ref{Edebug Options}.
-
- When Edebug responds to an error, it shows the last stop point
-encountered before the error. This may be the location of a call to a
-function which was not instrumented, and within which the error actually
-occurred. For an unbound variable error, the last known stop point
-might be quite distant from the offending variable reference. In that
-case, you might want to display a full backtrace (@pxref{Edebug Misc}).
-
address@hidden Edebug should be changed for the following: -- dan
- If you change @code{debug-on-error} or @code{debug-on-quit} while
-Edebug is active, these changes will be forgotten when Edebug becomes
-inactive. Furthermore, during Edebug's recursive edit, these variables
-are bound to the values they had outside of Edebug.
-
address@hidden Edebug Views
address@hidden Edebug Views
-
- These Edebug commands let you view aspects of the buffer and window
-status as they were before entry to Edebug. The outside window
-configuration is the collection of windows and contents that were in
-effect outside of Edebug.
-
address@hidden @kbd
address@hidden v
-Switch to viewing the outside window configuration
-(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
-
address@hidden p
-Temporarily display the outside current buffer with point at its
-outside position (@code{edebug-bounce-point}), pausing for one second
-before returning to Edebug. With a prefix argument @var{n}, pause for
address@hidden seconds instead.
-
address@hidden w
-Move point back to the current stop point in the source code buffer
-(@code{edebug-where}).
-
-If you use this command in a different window displaying the same
-buffer, that window will be used instead to display the current
-definition in the future.
-
address@hidden W
address@hidden Its function is not simply to forget the saved configuration --
dan
-Toggle whether Edebug saves and restores the outside window
-configuration (@code{edebug-toggle-save-windows}).
-
-With a prefix argument, @code{W} only toggles saving and restoring of
-the selected window. To specify a window that is not displaying the
-source code buffer, you must use @kbd{C-x X W} from the global keymap.
address@hidden table
-
- You can view the outside window configuration with @kbd{v} or just
-bounce to the point in the current buffer with @kbd{p}, even if
-it is not normally displayed.
-
- After moving point, you may wish to jump back to the stop point.
-You can do that with @kbd{w} from a source code buffer. You can jump
-back to the stop point in the source code buffer from any buffer using
address@hidden X w}.
-
- Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
-saved outside window configuration---so that even if you turn saving
-back @emph{on}, the current window configuration remains unchanged when
-you next exit Edebug (by continuing the program). However, the
-automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
-conflict with the buffers you wish to see unless you have enough windows
-open.
-
address@hidden Edebug Eval
address@hidden Evaluation
-
- While within Edebug, you can evaluate expressions ``as if'' Edebug
-were not running. Edebug tries to be invisible to the expression's
-evaluation and printing. Evaluation of expressions that cause side
-effects will work as expected, except for changes to data that Edebug
-explicitly saves and restores. @xref{The Outside Context}, for details
-on this process.
-
address@hidden @kbd
address@hidden e @var{exp} @key{RET}
-Evaluate expression @var{exp} in the context outside of Edebug
-(@code{edebug-eval-expression}). That is, Edebug tries to minimize its
-interference with the evaluation.
-
address@hidden M-: @var{exp} @key{RET}
-Evaluate expression @var{exp} in the context of Edebug itself.
-
address@hidden C-x C-e
-Evaluate the expression before point, in the context outside of Edebug
-(@code{edebug-eval-last-sexp}).
address@hidden table
-
address@hidden lexical binding (Edebug)
- Edebug supports evaluation of expressions containing references to
-lexically bound symbols created by the following constructs in
address@hidden (version 2.03 or later): @code{lexical-let},
address@hidden, and @code{symbol-macrolet}.
-
address@hidden Eval List
address@hidden Evaluation List Buffer
-
- You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
-evaluate expressions interactively. You can also set up the
address@hidden list} of expressions to be evaluated automatically each
-time Edebug updates the display.
-
address@hidden @kbd
address@hidden E
-Switch to the evaluation list buffer @samp{*edebug*}
-(@code{edebug-visit-eval-list}).
address@hidden table
-
- In the @samp{*edebug*} buffer you can use the commands of Lisp
-Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
-Manual}) as well as these special commands:
-
address@hidden @kbd
address@hidden C-j
-Evaluate the expression before point, in the outside context, and insert
-the value in the buffer (@code{edebug-eval-print-last-sexp}).
-
address@hidden C-x C-e
-Evaluate the expression before point, in the context outside of Edebug
-(@code{edebug-eval-last-sexp}).
-
address@hidden C-c C-u
-Build a new evaluation list from the contents of the buffer
-(@code{edebug-update-eval-list}).
-
address@hidden C-c C-d
-Delete the evaluation list group that point is in
-(@code{edebug-delete-eval-item}).
-
address@hidden C-c C-w
-Switch back to the source code buffer at the current stop point
-(@code{edebug-where}).
address@hidden table
-
- You can evaluate expressions in the evaluation list window with
address@hidden or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
-but they are evaluated in the context outside of Edebug.
-
- The expressions you enter interactively (and their results) are lost
-when you continue execution; but you can set up an @dfn{evaluation list}
-consisting of expressions to be evaluated each time execution stops.
-
address@hidden evaluation list group
- To do this, write one or more @dfn{evaluation list groups} in the
-evaluation list buffer. An evaluation list group consists of one or
-more Lisp expressions. Groups are separated by comment lines.
-
- The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
-evaluation list, scanning the buffer and using the first expression of
-each group. (The idea is that the second expression of the group is the
-value previously computed and displayed.)
-
- Each entry to Edebug redisplays the evaluation list by inserting each
-expression in the buffer, followed by its current value. It also
-inserts comment lines so that each expression becomes its own group.
-Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
-the evaluation list is effectively unchanged.
-
- If an error occurs during an evaluation from the evaluation list, the
-error message is displayed in a string as if it were the result.
-Therefore, expressions that use variables not currently valid do not
-interrupt your debugging.
-
- Here is an example of what the evaluation list window looks like after
-several expressions have been added to it:
-
address@hidden
-(current-buffer)
-#<buffer *scratch*>
-;---------------------------------------------------------------
-(selected-window)
-#<window 16 on *scratch*>
-;---------------------------------------------------------------
-(point)
-196
-;---------------------------------------------------------------
-bad-var
-"Symbol's value as variable is void: bad-var"
-;---------------------------------------------------------------
-(recursion-depth)
-0
-;---------------------------------------------------------------
-this-command
-eval-last-sexp
-;---------------------------------------------------------------
address@hidden smallexample
-
-To delete a group, move point into it and type @kbd{C-c C-d}, or simply
-delete the text for the group and update the evaluation list with
address@hidden C-u}. To add a new expression to the evaluation list, insert
-the expression at a suitable place, insert a new comment line, then type
address@hidden C-u}. You need not insert dashes in the comment line---its
-contents don't matter.
-
-After selecting @samp{*edebug*}, you can return to the source code
-buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
-you continue execution, and recreated next time it is needed.
-
address@hidden Printing in Edebug
address@hidden Printing in Edebug
-
address@hidden printing (Edebug)
address@hidden printing circular structures
address@hidden cust-print
- If an expression in your program produces a value containing circular
-list structure, you may get an error when Edebug attempts to print it.
-
- One way to cope with circular structure is to set @code{print-length}
-or @code{print-level} to truncate the printing. Edebug does this for
-you; it binds @code{print-length} and @code{print-level} to 50 if they
-were @code{nil}. (Actually, the variables @code{edebug-print-length}
-and @code{edebug-print-level} specify the values to use within Edebug.)
address@hidden Variables}.
-
address@hidden edebug-print-length
-If address@hidden, Edebug binds @code{print-length} to this value while
-printing results. The default value is @code{50}.
address@hidden defopt
-
address@hidden edebug-print-level
-If address@hidden, Edebug binds @code{print-level} to this value while
-printing results. The default value is @code{50}.
address@hidden defopt
-
- You can also print circular structures and structures that share
-elements more informatively by binding @code{print-circle}
-to a address@hidden value.
-
- Here is an example of code that creates a circular structure:
-
address@hidden
-(setq a '(x y))
-(setcar a a)
address@hidden example
-
address@hidden
-Custom printing prints this as @samp{Result: #1=(#1# y)}. The
address@hidden notation labels the structure that follows it with the label
address@hidden, and the @samp{#1#} notation references the previously labeled
-structure. This notation is used for any shared elements of lists or
-vectors.
-
address@hidden edebug-print-circle
-If address@hidden, Edebug binds @code{print-circle} to this value while
-printing results. The default value is @code{t}.
address@hidden defopt
-
- Other programs can also use custom printing; see @file{cust-print.el}
-for details.
-
address@hidden Trace Buffer
address@hidden Trace Buffer
address@hidden trace buffer
-
- Edebug can record an execution trace, storing it in a buffer named
address@hidden This is a log of function calls and returns,
-showing the function names and their arguments and values. To enable
-trace recording, set @code{edebug-trace} to a address@hidden value.
-
- Making a trace buffer is not the same thing as using trace execution
-mode (@pxref{Edebug Execution Modes}).
-
- When trace recording is enabled, each function entry and exit adds
-lines to the trace buffer. A function entry record consists of
address@hidden::::@{}, followed by the function name and argument values. A
-function exit record consists of @samp{::::@}}, followed by the function
-name and result of the function.
-
- The number of @samp{:}s in an entry shows its recursion depth. You
-can use the braces in the trace buffer to find the matching beginning or
-end of function calls.
-
address@hidden edebug-print-trace-before
address@hidden edebug-print-trace-after
- You can customize trace recording for function entry and exit by
-redefining the functions @code{edebug-print-trace-before} and
address@hidden
-
address@hidden edebug-tracing string address@hidden
-This macro requests additional trace information around the execution
-of the @var{body} forms. The argument @var{string} specifies text
-to put in the trace buffer, after the @address@hidden or @address@hidden All
-the arguments are evaluated, and @code{edebug-tracing} returns the
-value of the last form in @var{body}.
address@hidden defmac
-
address@hidden edebug-trace format-string &rest format-args
-This function inserts text in the trace buffer. It computes the text
-with @code{(apply 'format @var{format-string} @var{format-args})}.
-It also appends a newline to separate entries.
address@hidden defun
-
- @code{edebug-tracing} and @code{edebug-trace} insert lines in the
-trace buffer whenever they are called, even if Edebug is not active.
-Adding text to the trace buffer also scrolls its window to show the last
-lines inserted.
-
address@hidden Coverage Testing
address@hidden Coverage Testing
-
address@hidden coverage testing (Edebug)
address@hidden frequency counts
address@hidden performance analysis
- Edebug provides rudimentary coverage testing and display of execution
-frequency.
-
- Coverage testing works by comparing the result of each expression with
-the previous result; each form in the program is considered ``covered''
-if it has returned two different values since you began testing coverage
-in the current Emacs session. Thus, to do coverage testing on your
-program, execute it under various conditions and note whether it behaves
-correctly; Edebug will tell you when you have tried enough different
-conditions that each form has returned two different values.
-
- Coverage testing makes execution slower, so it is only done if
address@hidden is address@hidden Frequency counting is
-performed for all execution of an instrumented function, even if the
-execution mode is Go-nonstop, and regardless of whether coverage testing
-is enabled.
-
address@hidden C-x X =
address@hidden edebug-temp-display-freq-count
- Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
-the coverage information and the frequency counts for a definition.
-Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
-information temporarily, only until you type another key.
-
address@hidden Command edebug-display-freq-count
-This command displays the frequency count data for each line of the
-current definition.
-
-The frequency counts appear as comment lines after each line of code,
-and you can undo all insertions with one @code{undo} command. The
-counts appear under the @samp{(} before an expression or the @samp{)}
-after an expression, or on the last character of a variable. To
-simplify the display, a count is not shown if it is equal to the
-count of an earlier expression on the same line.
-
-The character @samp{=} following the count for an expression says that
-the expression has returned the same value each time it was evaluated.
-In other words, it is not yet ``covered'' for coverage testing purposes.
-
-To clear the frequency count and coverage data for a definition,
-simply reinstrument it with @code{eval-defun}.
address@hidden deffn
-
-For example, after evaluating @code{(fac 5)} with a source
-breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
-the breakpoint is reached, the frequency data looks like this:
-
address@hidden
-(defun fac (n)
- (if (= n 0) (edebug))
-;#6 1 = =5
- (if (< 0 n)
-;#5 =
- (* n (fac (1- n)))
-;# 5 0
- 1))
-;# 0
address@hidden example
-
-The comment lines show that @code{fac} was called 6 times. The
-first @code{if} statement returned 5 times with the same result each
-time; the same is true of the condition on the second @code{if}.
-The recursive call of @code{fac} did not return at all.
-
-
address@hidden The Outside Context
address@hidden The Outside Context
-
-Edebug tries to be transparent to the program you are debugging, but it
-does not succeed completely. Edebug also tries to be transparent when
-you evaluate expressions with @kbd{e} or with the evaluation list
-buffer, by temporarily restoring the outside context. This section
-explains precisely what context Edebug restores, and how Edebug fails to
-be completely transparent.
-
address@hidden
-* Checking Whether to Stop:: When Edebug decides what to do.
-* Edebug Display Update:: When Edebug updates the display.
-* Edebug Recursive Edit:: When Edebug stops execution.
address@hidden menu
-
address@hidden Checking Whether to Stop
address@hidden Checking Whether to Stop
-
-Whenever Edebug is entered, it needs to save and restore certain data
-before even deciding whether to make trace information or stop the
-program.
-
address@hidden @bullet
address@hidden
address@hidden and @code{max-specpdl-size} are both
-incremented once to reduce Edebug's impact on the stack. You could,
-however, still run out of stack space when using Edebug.
-
address@hidden
-The state of keyboard macro execution is saved and restored. While
-Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
-unless @code{edebug-continue-kbd-macro} is address@hidden
address@hidden itemize
-
-
address@hidden Edebug Display Update
address@hidden Edebug Display Update
-
address@hidden This paragraph is not filled, because LaLiberte's conversion
script
address@hidden needs an xref to be on just one line.
-When Edebug needs to display something (e.g., in trace mode), it saves
-the current window configuration from ``outside'' Edebug
-(@pxref{Window Configurations}). When you exit Edebug (by continuing
-the program), it restores the previous window configuration.
-
-Emacs redisplays only when it pauses. Usually, when you continue
-execution, the program re-enters Edebug at a breakpoint or after
-stepping, without pausing or reading input in between. In such cases,
-Emacs never gets a chance to redisplay the ``outside'' configuration.
-Consequently, what you see is the same window configuration as the last
-time Edebug was active, with no interruption.
-
-Entry to Edebug for displaying something also saves and restores the
-following data (though some of them are deliberately not restored if an
-error or quit signal occurs).
-
address@hidden @bullet
address@hidden
address@hidden current buffer point and mark (Edebug)
-Which buffer is current, and the positions of point and the mark in the
-current buffer, are saved and restored.
-
address@hidden
address@hidden window configuration (Edebug)
-The outside window configuration is saved and restored if
address@hidden is address@hidden (@pxref{Edebug Options}).
-
-The window configuration is not restored on error or quit, but the
-outside selected window @emph{is} reselected even on error or quit in
-case a @code{save-excursion} is active. If the value of
address@hidden is a list, only the listed windows are saved
-and restored.
-
-The window start and horizontal scrolling of the source code buffer are
-not restored, however, so that the display remains coherent within Edebug.
-
address@hidden
-The value of point in each displayed buffer is saved and restored if
address@hidden is address@hidden
-
address@hidden
-The variables @code{overlay-arrow-position} and
address@hidden are saved and restored. So you can safely
-invoke Edebug from the recursive edit elsewhere in the same buffer.
-
address@hidden
address@hidden is locally bound to @code{nil} so that
-the cursor shows up in the window.
address@hidden itemize
-
address@hidden Edebug Recursive Edit
address@hidden Edebug Recursive Edit
-
-When Edebug is entered and actually reads commands from the user, it
-saves (and later restores) these additional data:
-
address@hidden @bullet
address@hidden
-The current match data. @xref{Match Data}.
-
address@hidden
-The variables @code{last-command}, @code{this-command},
address@hidden, @code{last-input-char},
address@hidden, @code{last-command-event},
address@hidden, @code{last-nonmenu-event}, and
address@hidden Commands used within Edebug do not affect these
-variables outside of Edebug.
-
-Executing commands within Edebug can change the key sequence that
-would be returned by @code{this-command-keys}, and there is no way to
-reset the key sequence from Lisp.
-
-Edebug cannot save and restore the value of
address@hidden Entering Edebug while this variable has a
-nontrivial value can interfere with execution of the program you are
-debugging.
-
address@hidden
-Complex commands executed while in Edebug are added to the variable
address@hidden In rare cases this can alter execution.
-
address@hidden
-Within Edebug, the recursion depth appears one deeper than the recursion
-depth outside Edebug. This is not true of the automatically updated
-evaluation list window.
-
address@hidden
address@hidden and @code{standard-input} are bound to @code{nil}
-by the @code{recursive-edit}, but Edebug temporarily restores them during
-evaluations.
-
address@hidden
-The state of keyboard macro definition is saved and restored. While
-Edebug is active, @code{defining-kbd-macro} is bound to
address@hidden
address@hidden itemize
-
address@hidden Edebug and Macros
address@hidden Edebug and Macros
-
-To make Edebug properly instrument expressions that call macros, some
-extra care is needed. This subsection explains the details.
-
address@hidden
-* Instrumenting Macro Calls:: The basic problem.
-* Specification List:: How to specify complex patterns of evaluation.
-* Backtracking:: What Edebug does when matching fails.
-* Specification Examples:: To help understand specifications.
address@hidden menu
-
address@hidden Instrumenting Macro Calls
address@hidden Instrumenting Macro Calls
-
- When Edebug instruments an expression that calls a Lisp macro, it needs
-additional information about the macro to do the job properly. This is
-because there is no a-priori way to tell which subexpressions of the
-macro call are forms to be evaluated. (Evaluation may occur explicitly
-in the macro body, or when the resulting expansion is evaluated, or any
-time later.)
-
- Therefore, you must define an Edebug specification for each macro
-that Edebug will encounter, to explain the format of calls to that
-macro. To do this, add a @code{debug} declaration to the macro
-definition. Here is a simple example that shows the specification for
-the @code{for} example macro (@pxref{Argument Evaluation}).
-
address@hidden
-(defmacro for (var from init to final do &rest body)
- "Execute a simple \"for\" loop.
-For example, (for i from 1 to 10 do (print i))."
- (declare (debug (symbolp "from" form "to" form "do" &rest form)))
- ...)
address@hidden smallexample
-
- The Edebug specification says which parts of a call to the macro are
-forms to be evaluated. For simple macros, the @var{specification}
-often looks very similar to the formal argument list of the macro
-definition, but specifications are much more general than macro
-arguments. @xref{Defining Macros}, for more explanation of
-the @code{declare} form.
-
- You can also define an edebug specification for a macro separately
-from the macro definition with @code{def-edebug-spec}. Adding
address@hidden declarations is preferred, and more convenient, for macro
-definitions in Lisp, but @code{def-edebug-spec} makes it possible to
-define Edebug specifications for special forms implemented in C.
-
address@hidden Macro def-edebug-spec macro specification
-Specify which expressions of a call to macro @var{macro} are forms to be
-evaluated. @var{specification} should be the edebug specification.
-Neither argument is evaluated.
-
-The @var{macro} argument can actually be any symbol, not just a macro
-name.
address@hidden deffn
-
-Here is a table of the possibilities for @var{specification} and how each
-directs processing of arguments.
-
address@hidden @asis
address@hidden @code{t}
-All arguments are instrumented for evaluation.
-
address@hidden @code{0}
-None of the arguments is instrumented.
-
address@hidden a symbol
-The symbol must have an Edebug specification which is used instead.
-This indirection is repeated until another kind of specification is
-found. This allows you to inherit the specification from another macro.
-
address@hidden a list
-The elements of the list describe the types of the arguments of a
-calling form. The possible elements of a specification list are
-described in the following sections.
address@hidden table
-
address@hidden edebug-eval-macro-args
-If a macro has no Edebug specification, neither through a @code{debug}
-declaration nor through a @code{def-edebug-spec} call, the variable
address@hidden comes into play. If it is @code{nil},
-the default, none of the arguments is instrumented for evaluation.
-If it is address@hidden, all arguments are instrumented.
-
address@hidden Specification List
address@hidden Specification List
-
address@hidden Edebug specification list
-A @dfn{specification list} is required for an Edebug specification if
-some arguments of a macro call are evaluated while others are not. Some
-elements in a specification list match one or more arguments, but others
-modify the processing of all following elements. The latter, called
address@hidden keywords}, are symbols beginning with @samp{&} (such
-as @code{&optional}).
-
-A specification list may contain sublists which match arguments that are
-themselves lists, or it may contain vectors used for grouping. Sublists
-and groups thus subdivide the specification list into a hierarchy of
-levels. Specification keywords apply only to the remainder of the
-sublist or group they are contained in.
-
-When a specification list involves alternatives or repetition, matching
-it against an actual macro call may require backtracking.
address@hidden, for more details.
-
-Edebug specifications provide the power of regular expression matching,
-plus some context-free grammar constructs: the matching of sublists with
-balanced parentheses, recursive processing of forms, and recursion via
-indirect specifications.
-
-Here's a table of the possible elements of a specification list, with
-their meanings (see @ref{Specification Examples}, for the referenced
-examples):
-
address@hidden @code
address@hidden sexp
-A single unevaluated Lisp object, which is not instrumented.
address@hidden an "expression" is not necessarily intended for evaluation.
-
address@hidden form
-A single evaluated expression, which is instrumented.
-
address@hidden place
address@hidden edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
-
address@hidden body
-Short for @code{&rest form}. See @code{&rest} below.
-
address@hidden function-form
-A function form: either a quoted function symbol, a quoted lambda
-expression, or a form (that should evaluate to a function symbol or
-lambda expression). This is useful when an argument that's a lambda
-expression might be quoted with @code{quote} rather than
address@hidden, since it instruments the body of the lambda expression
-either way.
-
address@hidden lambda-expr
-A lambda expression with no quoting.
-
address@hidden &optional
address@hidden @kindex &optional @r{(Edebug)}
-All following elements in the specification list are optional; as soon
-as one does not match, Edebug stops matching at this level.
-
-To make just a few elements optional followed by non-optional elements,
-use @code{[&optional @address@hidden To specify that several
-elements must all match or none, use @code{&optional
address@hidden@dots{}]}. See the @code{defun} example.
-
address@hidden &rest
address@hidden @kindex &rest @r{(Edebug)}
-All following elements in the specification list are repeated zero or
-more times. In the last repetition, however, it is not a problem if the
-expression runs out before matching all of the elements of the
-specification list.
-
-To repeat only a few elements, use @code{[&rest @address@hidden
-To specify several elements that must all match on every repetition, use
address@hidden&rest address@hidden@dots{}]}.
-
address@hidden &or
address@hidden @kindex &or @r{(Edebug)}
-Each of the following elements in the specification list is an
-alternative. One of the alternatives must match, or the @code{&or}
-specification fails.
-
-Each list element following @code{&or} is a single alternative. To
-group two or more list elements as a single alternative, enclose them in
address@hidden@dots{}]}.
-
address@hidden ¬
address@hidden @kindex ¬ @r{(Edebug)}
-Each of the following elements is matched as alternatives as if by using
address@hidden&or}, but if any of them match, the specification fails. If none
-of them match, nothing is matched, but the @code{¬} specification
-succeeds.
-
address@hidden &define
address@hidden @kindex &define @r{(Edebug)}
-Indicates that the specification is for a defining form. The defining
-form itself is not instrumented (that is, Edebug does not stop before and
-after the defining form), but forms inside it typically will be
-instrumented. The @code{&define} keyword should be the first element in
-a list specification.
-
address@hidden nil
-This is successful when there are no more arguments to match at the
-current argument list level; otherwise it fails. See sublist
-specifications and the backquote example.
-
address@hidden gate
address@hidden preventing backtracking
-No argument is matched but backtracking through the gate is disabled
-while matching the remainder of the specifications at this level. This
-is primarily used to generate more specific syntax error messages. See
address@hidden, for more details. Also see the @code{let} example.
-
address@hidden @var{other-symbol}
address@hidden indirect specifications
-Any other symbol in a specification list may be a predicate or an
-indirect specification.
-
-If the symbol has an Edebug specification, this @dfn{indirect
-specification} should be either a list specification that is used in
-place of the symbol, or a function that is called to process the
-arguments. The specification may be defined with @code{def-edebug-spec}
-just as for macros. See the @code{defun} example.
-
-Otherwise, the symbol should be a predicate. The predicate is called
-with the argument and the specification fails if the predicate returns
address@hidden In either case, that argument is not instrumented.
-
-Some suitable predicates include @code{symbolp}, @code{integerp},
address@hidden, @code{vectorp}, and @code{atom}.
-
address@hidden address@hidden@dots{}]
address@hidden address@hidden (Edebug)
-A vector of elements groups the elements into a single @dfn{group
-specification}. Its meaning has nothing to do with vectors.
-
address@hidden "@var{string}"
-The argument should be a symbol named @var{string}. This specification
-is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
-of @var{symbol} is the @var{string}, but the string form is preferred.
-
address@hidden (vector @address@hidden)
-The argument should be a vector whose elements must match the
address@hidden in the specification. See the backquote example.
-
address@hidden (@address@hidden)
-Any other list is a @dfn{sublist specification} and the argument must be
-a list whose elements match the specification @var{elements}.
-
address@hidden dotted lists (Edebug)
-A sublist specification may be a dotted list and the corresponding list
-argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
-dotted list specification may be another sublist specification (via a
-grouping or an indirect specification, e.g., @code{(spec . [(more
address@hidden)])}) whose elements match the non-dotted list arguments.
-This is useful in recursive specifications such as in the backquote
-example. Also see the description of a @code{nil} specification
-above for terminating such recursion.
-
-Note that a sublist specification written as @code{(specs . nil)}
-is equivalent to @code{(specs)}, and @code{(specs .
-(address@hidden))} is equivalent to @code{(specs
address@hidden)}.
address@hidden table
-
address@hidden Need to document extensions with &symbol and :symbol
-
-Here is a list of additional specifications that may appear only after
address@hidden&define}. See the @code{defun} example.
-
address@hidden @code
address@hidden name
-The argument, a symbol, is the name of the defining form.
-
-A defining form is not required to have a name field; and it may have
-multiple name fields.
-
address@hidden :name
-This construct does not actually match an argument. The element
-following @code{:name} should be a symbol; it is used as an additional
-name component for the definition. You can use this to add a unique,
-static component to the name of the definition. It may be used more
-than once.
-
address@hidden arg
-The argument, a symbol, is the name of an argument of the defining form.
-However, lambda-list keywords (symbols starting with @samp{&})
-are not allowed.
-
address@hidden lambda-list
address@hidden lambda-list (Edebug)
-This matches a lambda list---the argument list of a lambda expression.
-
address@hidden def-body
-The argument is the body of code in a definition. This is like
address@hidden, described above, but a definition body must be instrumented
-with a different Edebug call that looks up information associated with
-the definition. Use @code{def-body} for the highest level list of forms
-within the definition.
-
address@hidden def-form
-The argument is a single, highest-level form in a definition. This is
-like @code{def-body}, except use this to match a single form rather than
-a list of forms. As a special case, @code{def-form} also means that
-tracing information is not output when the form is executed. See the
address@hidden example.
address@hidden table
-
address@hidden Backtracking
address@hidden Backtracking in Specifications
-
address@hidden backtracking
address@hidden syntax error (Edebug)
-If a specification fails to match at some point, this does not
-necessarily mean a syntax error will be signaled; instead,
address@hidden will take place until all alternatives have been
-exhausted. Eventually every element of the argument list must be
-matched by some element in the specification, and every required element
-in the specification must match some argument.
-
-When a syntax error is detected, it might not be reported until much
-later after higher-level alternatives have been exhausted, and with the
-point positioned further from the real error. But if backtracking is
-disabled when an error occurs, it can be reported immediately. Note
-that backtracking is also reenabled automatically in several situations;
-it is reenabled when a new alternative is established by
address@hidden&optional}, @code{&rest}, or @code{&or}, or at the start of
-processing a sublist, group, or indirect specification. The effect of
-enabling or disabling backtracking is limited to the remainder of the
-level currently being processed and lower levels.
-
-Backtracking is disabled while matching any of the
-form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
address@hidden). These specifications will match any form so any error
-must be in the form itself rather than at a higher level.
-
-Backtracking is also disabled after successfully matching a quoted
-symbol or string specification, since this usually indicates a
-recognized construct. But if you have a set of alternative constructs that
-all begin with the same symbol, you can usually work around this
-constraint by factoring the symbol out of the alternatives, e.g.,
address@hidden"foo" &or [first case] [second case] ...]}.
-
-Most needs are satisfied by these two ways that backtracking is
-automatically disabled, but occasionally it is useful to explicitly
-disable backtracking by using the @code{gate} specification. This is
-useful when you know that no higher alternatives could apply. See the
-example of the @code{let} specification.
-
address@hidden Specification Examples
address@hidden Specification Examples
-
-It may be easier to understand Edebug specifications by studying
-the examples provided here.
-
-A @code{let} special form has a sequence of bindings and a body. Each
-of the bindings is either a symbol or a sublist with a symbol and
-optional expression. In the specification below, notice the @code{gate}
-inside of the sublist to prevent backtracking once a sublist is found.
-
address@hidden
-(def-edebug-spec let
- ((&rest
- &or symbolp (gate symbolp &optional form))
- body))
address@hidden example
-
-Edebug uses the following specifications for @code{defun} and
address@hidden and the associated argument list and @code{interactive}
-specifications. It is necessary to handle interactive forms specially
-since an expression argument is actually evaluated outside of the
-function body.
-
address@hidden
-(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
-(def-edebug-spec defun
- (&define name lambda-list
- [&optional stringp] ; @r{Match the doc string, if present.}
- [&optional ("interactive" interactive)]
- def-body))
-
-(def-edebug-spec lambda-list
- (([&rest arg]
- [&optional ["&optional" arg &rest arg]]
- &optional ["&rest" arg]
- )))
-
-(def-edebug-spec interactive
- (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
address@hidden smallexample
-
-The specification for backquote below illustrates how to match
-dotted lists and use @code{nil} to terminate recursion. It also
-illustrates how components of a vector may be matched. (The actual
-specification defined by Edebug does not support dotted lists because
-doing so causes very deep recursion that could fail.)
-
address@hidden
-(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
-
-(def-edebug-spec backquote-form
- (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
- (backquote-form . [&or nil backquote-form])
- (vector &rest backquote-form)
- sexp))
address@hidden smallexample
-
-
address@hidden Edebug Options
address@hidden Edebug Options
-
- These options affect the behavior of Edebug:
-
address@hidden edebug-setup-hook
-Functions to call before Edebug is used. Each time it is set to a new
-value, Edebug will call those functions once and then
address@hidden is reset to @code{nil}. You could use this to
-load up Edebug specifications associated with a package you are using
-but only when you also use Edebug.
address@hidden
address@hidden defopt
-
address@hidden edebug-all-defs
-If this is address@hidden, normal evaluation of defining forms such as
address@hidden and @code{defmacro} instruments them for Edebug. This
-applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
-and @code{eval-current-buffer}.
-
-Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
-option. @xref{Instrumenting}.
address@hidden defopt
-
address@hidden edebug-all-forms
-If this is address@hidden, the commands @code{eval-defun},
address@hidden, @code{eval-buffer}, and @code{eval-current-buffer}
-instrument all forms, even those that don't define anything.
-This doesn't apply to loading or evaluations in the minibuffer.
-
-Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
-option. @xref{Instrumenting}.
address@hidden defopt
-
address@hidden edebug-save-windows
-If this is address@hidden, Edebug saves and restores the window
-configuration. That takes some time, so if your program does not care
-what happens to the window configurations, it is better to set this
-variable to @code{nil}.
-
-If the value is a list, only the listed windows are saved and
-restored.
-
-You can use the @kbd{W} command in Edebug to change this variable
-interactively. @xref{Edebug Display Update}.
address@hidden defopt
-
address@hidden edebug-save-displayed-buffer-points
-If this is address@hidden, Edebug saves and restores point in all
-displayed buffers.
-
-Saving and restoring point in other buffers is necessary if you are
-debugging code that changes the point of a buffer which is displayed in
-a non-selected window. If Edebug or the user then selects the window,
-point in that buffer will move to the window's value of point.
-
-Saving and restoring point in all buffers is expensive, since it
-requires selecting each window twice, so enable this only if you need
-it. @xref{Edebug Display Update}.
address@hidden defopt
-
address@hidden edebug-initial-mode
-If this variable is address@hidden, it specifies the initial execution
-mode for Edebug when it is first activated. Possible values are
address@hidden, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
address@hidden, @code{continue}, and @code{Continue-fast}.
-
-The default value is @code{step}.
address@hidden Execution Modes}.
address@hidden defopt
-
address@hidden edebug-trace
-If this is address@hidden, trace each function entry and exit.
-Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
-function entry or exit per line, indented by the recursion level.
-
-Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
address@hidden defopt
-
address@hidden edebug-test-coverage
-If address@hidden, Edebug tests coverage of all expressions debugged.
address@hidden Testing}.
address@hidden defopt
-
address@hidden edebug-continue-kbd-macro
-If address@hidden, continue defining or executing any keyboard macro
-that is executing outside of Edebug. Use this with caution since it is not
-debugged.
address@hidden Execution Modes}.
address@hidden defopt
-
address@hidden edebug-on-error
-Edebug binds @code{debug-on-error} to this value, if
address@hidden was previously @code{nil}. @xref{Trapping
-Errors}.
address@hidden defopt
-
address@hidden edebug-on-quit
-Edebug binds @code{debug-on-quit} to this value, if
address@hidden was previously @code{nil}. @xref{Trapping
-Errors}.
address@hidden defopt
-
- If you change the values of @code{edebug-on-error} or
address@hidden while Edebug is active, their values won't be used
-until the @emph{next} time Edebug is invoked via a new command.
address@hidden Not necessarily a deeper command level.
address@hidden A new command is not precisely true, but that is close enough --
dan
-
address@hidden edebug-global-break-condition
-If address@hidden, an expression to test for at every stop point. If
-the result is address@hidden, then break. Errors are ignored.
address@hidden Break Condition}.
address@hidden defopt
-
address@hidden
- arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
address@hidden ignore
- [Emacs-diffs] Changes to edebug.texi,
Glenn Morris <=