@comment -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1992, 1993, 1994, 1998, 1999 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
-@c This file is intended to be used as a section within the Emacs Lisp
-@c Reference Manual. It may also be used by an independent Edebug User
-@c Manual, edebug.tex, in which case the Edebug node below should be used
+@c This file can also be used by an independent Edebug User
+@c Manual in which case the Edebug node below should be used
@c with the following links to the Bugs section and to the top level:
@c , Bugs and Todo List, Top, Top
-@node Edebug,, Compilation Errors, Debugging
+@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
@cindex Edebug mode
Display expression results and evaluate expressions as if outside of
Edebug.
-@item
-Automatically reevaluate a list of expressions and
+@item
+Automatically re-evaluate a list of expressions and
display their results each time Edebug updates the display.
@item
* Jumping:: Commands to jump to a specified place.
* Misc: Edebug Misc. Miscellaneous commands.
* Breakpoints:: Setting breakpoints to make the program stop.
-* Trapping Errors:: trapping errors with Edebug.
+* Trapping Errors:: Trapping errors with Edebug.
* Views: Edebug Views. Views inside and outside of Edebug.
-* Eval: Edebug Eval. Evaluating expressions within 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.
@ref{Instrumenting}, for alternative ways to instrument code.
Once a function is instrumented, any call to the function activates
-Edebug. Activating Edebug may stop execution and let you step through
-the function, or it may update the display and continue execution while
-checking for debugging commands, depending on which Edebug execution
-mode you have selected. The default execution mode is step, which does
-stop execution. @xref{Edebug Execution Modes}.
+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}. This buffer is temporarily read-only.
+code buffer}, and it is temporarily read-only.
An arrow at the left margin indicates the line where the function is
executing. Point initially shows where within the line the function is
executing, but 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 normally see. Point is at the
-open-parenthesis before @code{if}.
+execute @code{(fac 3)}, here is what you would normally see. Point is
+at the open-parenthesis before @code{if}.
@example
(defun fac (n)
@cindex stop points
The places within a function where Edebug can stop execution are called
@dfn{stop points}. These occur both before and after each subexpression
-that is a list, and also after each variable reference.
-Here we show with periods the stop points found in the function
+that is a list, and also after each variable reference.
+Here we use periods to show the stop points in the function
@code{fac}:
@example
@end example
When Edebug stops execution after an expression, it displays the
-expression's value in the echo area.
+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
argument on a definition, it instruments the definition before
evaluating it. (The source code itself is not modified.) If the
variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
-meaning of the prefix argument: then @kbd{C-M-x} instruments 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 @code{nil}. The command @kbd{M-x
edebug-all-defs} toggles the value of the variable
@code{edebug-all-defs}.
-@findex edebug-all-forms
-@findex eval-region (Edebug)
-@findex eval-current-buffer (Edebug)
+@findex eval-region @r{(Edebug)}
+@findex eval-current-buffer @r{(Edebug)}
If @code{edebug-all-defs} is non-@code{nil}, then the commands
@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
also instrument any definitions they evaluate. Similarly,
edebug-all-forms} toggles this option.
@findex 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 value of
-@code{edebug-all-defs} or @code{edebug-all-forms}.
-
-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 @code{nil}.
-You can use this to load up Edebug specifications associated with a
-package you are using, but only when you also use Edebug.
+ Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
+instrument any top-level form regardless of the values of
+@code{edebug-all-defs} and @code{edebug-all-forms}.
-While Edebug is active, the command @kbd{I}
+ 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; after loading Edebug, @code{eval-region}
-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.
+source for that function; for this reading, after loading Edebug,
+@code{eval-region} 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.
@cindex special forms (Edebug)
@cindex interactive commands (Edebug)
@cindex anonymous lambda expressions (Edebug)
@cindex Common Lisp (Edebug)
-@pindex cl.el (Edebug)
+@pindex cl.el @r{(Edebug)}
@pindex cl-specs.el
- Edebug knows how to instrument all the standard special forms, an
-interactive form with an expression argument, anonymous lambda
-expressions, and other defining forms. Edebug cannot know what a
-user-defined macro will do with the arguments of a macro call, so you
-must tell it; @xref{Instrumenting Macro Calls}, for details.
-
-@findex eval-expression (Edebug)
- To remove instrumentation from a definition, simply reevaluate its
+ Edebug knows how to instrument all the standard special forms,
+@code{interactive} 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; see @ref{Instrumenting
+Macro Calls}, 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
+@code{nil}. You can use this to load Edebug specifications
+(@pxref{Instrumenting Macro Calls}) associated with a package you are
+using, but only when you use Edebug.
+
+@findex 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
@code{load}, and from the minibuffer with @code{eval-expression}
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
+commands; all except for @kbd{S} resume execution of the program, at
least for a certain distance.
@table @kbd
@item S
-Stop: don't execute any more of the program for now, just wait for more
+Stop: don't execute any more of the program, but wait for more
Edebug commands (@code{edebug-stop}).
@item @key{SPC}
@ref{Edebug Misc}.
@item t
-Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
+Trace: pause (normally one second) at each Edebug stop point
+(@code{edebug-trace-mode}).
@item T
Rapid trace: update the display at each stop point, but don't actually
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. But see the
+inside Edebug. This is usually an advantage. See also the
@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
When you enter a new Edebug level, the initial execution mode comes from
several times if, for example, an instrumented function is called
several times from one command.
+@defopt edebug-sit-for-seconds
+This option specifies how many seconds to wait between execution steps
+in trace mode. The default is 1 second.
+@end defopt
@node Jumping
@subsection Jumping
execution. @xref{Breakpoints}, for the details on breakpoints.
These commands 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.
+as that can bypass the temporary breakpoint where you expected the
+program to stop.
@table @kbd
@item h
@end table
The @kbd{h} command proceeds to the stop point near the current location
-if point, using a temporary breakpoint. See @ref{Breakpoints}, for more
-about breakpoints.
+of point, using a temporary breakpoint. See @ref{Breakpoints}, for more
+information about breakpoints.
The @kbd{f} command runs the program forward over one expression. More
precisely, it sets a temporary breakpoint at the position that
more elements, then the place to stop is after the containing
expression.
-Be careful that the position @kbd{C-M-f} finds is a place that the
-program will really get to; this may not be true in a
-@code{cond}, for example.
+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.
-The @kbd{f} command does @code{forward-sexp} starting at point, rather
-than at the stop point, for flexibility. If you want to execute one
-expression @emph{from the current stop point}, type @kbd{w} first, to
+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
debugging.
@item Q
-Like @kbd{q} but don't stop even for protected code
+Like @kbd{q}, but don't stop even for protected code
(@code{top-level-nonstop}).
@item r
execution.
@end table
-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 @kbd{q} or abort one recursive edit level with
-@kbd{C-]}. You can display a backtrace of all the
-pending evaluations with @kbd{d}.
+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}.
@node Breakpoints
@subsection Breakpoints
@cindex breakpoints
-Edebug's step mode stops execution at the next stop point reached.
+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.
While using Edebug, you can specify @dfn{breakpoints} in the program you
-are testing: points where execution should stop. You can set a
+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
@item 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).
+breakpoint is temporary---it turns off the first time it stops the
+program.
@item u
-Unset the breakpoint (if any) at the stop point at or after
+Unset the breakpoint (if any) at the stop point at or after
point (@code{edebug-unset-breakpoint}).
@item x @var{condition} @key{RET}
breakpoint is temporary.
@item B
-Move point to the next breakpoint in the definition
+Move point to the next breakpoint in the current definition
(@code{edebug-next-breakpoint}).
@end table
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.
-Reevaluating or reinstrumenting a definition forgets all its breakpoints.
+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
the previous condition expression in the minibuffer so you can edit it.
You can make a conditional or unconditional breakpoint
-@dfn{temporary} by using a prefix arg with the command to set the
+@dfn{temporary} 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
+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
point in the buffer.
@menu
-* Global Break Condition:: Breaking on an event.
+* Global Break Condition:: Breaking on an event.
* Source Breakpoints:: Embedding breakpoints in source code.
@end menu
@cindex 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 the global break condition at every stop point; if it
evaluates to a non-@code{nil} 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.
@findex edebug-set-global-break-condition
-@vindex edebug-global-break-condition
- You can set or edit the condition expression, stored in
-@code{edebug-global-break-condition}, using the @kbd{X} command
-(@code{edebug-set-global-break-condition}).
+ The condition expression is stored in
+@code{edebug-global-break-condition}. You can specify a new expression
+using the @kbd{X} command (@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
@findex edebug
@cindex source breakpoints
All breakpoints in a definition are forgotten each time you
-reinstrument it. 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, insert the first
-line as shown below to stop when the argument reaches zero:
+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:
@example
(defun fac (n)
1))
@end example
-When the @code{fac} definition is instrumented and the function is
+ 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,
+ If no instrumented code is being executed when @code{edebug} is called,
that function calls @code{debug}.
@c This may not be a good idea anymore.
@node Trapping Errors
@subsection Trapping Errors
-Emacs normally displays an error message when an error is signaled and
-not handled with @code{condition-case}. While Edebug is active, 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}.
+ 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
+ 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, within which the error actually
+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}).
+case, you might want to display a full backtrace (@pxref{Edebug Misc}).
@c Edebug should be changed for the following: -- dan
-If you change @code{debug-on-error} or @code{debug-on-quit} while
+ 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.
@node Edebug Views
@subsection Edebug Views
-These Edebug commands let you view aspects of the buffer and window
-status that obtained before entry to Edebug. The outside window
+ 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.
pause for @var{n} seconds instead.
@item w
-Move point back to the current stop point (@code{edebug-where}) in the
-source code buffer. Also, 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.
+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.
@item W
@c Its function is not simply to forget the saved configuration -- dan
source code buffer, you must use @kbd{C-x X W} from the global keymap.
@end table
-You can view the outside window configuration with @kbd{v} or just
+ 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 with @kbd{w} from a source code buffer.
-Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
+ 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
@node Edebug Eval
@subsection Evaluation
-While within Edebug, you can evaluate expressions ``as if'' Edebug were
-not running. Edebug tries to be invisible to the expression's
+ 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 things that Edebug explicitly
-saves and restores. @xref{The Outside Context}, for details on this
-process.
+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.
@table @kbd
@item e @var{exp} @key{RET}
@end table
@cindex lexical binding (Edebug)
-Edebug supports evaluation of expressions containing references to
+ Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in
@file{cl.el} (version 2.03 or later): @code{lexical-let},
@code{macrolet}, and @code{symbol-macrolet}.
-
@node Eval List
@subsection Evaluation List Buffer
-You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+ You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
evaluate expressions interactively. You can also set up the
@dfn{evaluation list} of expressions to be evaluated automatically each
time Edebug updates the display.
(@code{edebug-visit-eval-list}).
@end table
-In the @samp{*edebug*} buffer you can use the commands of Lisp
+ 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:
@table @kbd
-@item LFD
+@item C-j
Evaluate the expression before point, in the outside context, and insert
the value in the buffer (@code{edebug-eval-print-last-sexp}).
(@code{edebug-where}).
@end table
-You can evaluate expressions in the evaluation list window with
-@kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+ You can evaluate expressions in the evaluation list window with
+@kbd{C-j} 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
+ 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.
+consisting of expressions to be evaluated each time execution stops.
@cindex evaluation list group
-To do this, write one or more @dfn{evaluation list groups} in the
+ 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
+ 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.)
-Be careful not to add expressions that execute instrumented code since
-that would cause an infinite loop.
-@c There ought to be a way to fix this.
-
-Each entry to Edebug redisplays the evaluation list by inserting each
+ 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
+ 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
+ Here is an example of what the evaluation list window looks like after
several expressions have been added to it:
@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
@kbd{C-c C-u}. To add a new expression to the evaluation list, insert
-the expression at a suitable place, and insert a new comment line. (You
-need not insert dashes in the comment line---its contents don't matter.)
-Then type @kbd{C-c C-u}.
+the expression at a suitable place, insert a new comment line, then type
+@kbd{C-c 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.
-
@node Printing in Edebug
@subsection Printing in Edebug
If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.
-@vindex edebug-print-length
-@vindex edebug-print-level
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
and @code{edebug-print-level} specify the values to use within Edebug.)
@xref{Output Variables}.
- You can also print circular structures and structures that share
-elements more informatively by using the @file{cust-print} package.
+@defopt edebug-print-length
+If non-@code{nil}, Edebug binds @code{print-length} to this value while
+printing results. The default value is @code{50}.
+@end defopt
- To load @file{cust-print} and activate custom printing only for
-Edebug, simply use the command @kbd{M-x edebug-install-custom-print}.
-To restore the standard print functions, use @kbd{M-x
-edebug-uninstall-custom-print}.
+@defopt edebug-print-level
+If non-@code{nil}, Edebug binds @code{print-level} to this value while
+printing results. The default value is @code{50}.
+@end defopt
+
+ You can also print circular structures and structures that share
+elements more informatively by binding @code{print-circle}
+to a non-@code{nil} value.
Here is an example of code that creates a circular structure:
@example
(setq a '(x y))
-(setcar a a))
+(setcar a a)
@end example
@noindent
Custom printing prints this as @samp{Result: #1=(#1# y)}. The
@samp{#1=} notation labels the structure that follows it with the label
-@samp{1}, and the @samp{#1#} notation references the previously labelled
+@samp{1}, and the @samp{#1#} notation references the previously labeled
structure. This notation is used for any shared elements of lists or
vectors.
+@defopt edebug-print-circle
+If non-@code{nil}, Edebug binds @code{print-circle} to this value while
+printing results. The default value is @code{nil}.
+@end defopt
+
Other programs can also use custom printing; see @file{cust-print.el}
for details.
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 looks like
-@samp{::::@{} followed by the function name and argument values. A
-function exit record looks like @samp{::::@}} followed by the function
+lines to the trace buffer. A function entry record consists of
+@samp{::::@{}, 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
@defmac edebug-tracing string body@dots{}
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. All the arguments are evaluated.
+to put in the trace buffer. All the arguments are evaluated, and
@code{edebug-tracing} returns the value of the last form in @var{body}.
@end defmac
It also appends a newline to separate entries.
@end defun
- @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
-buffer even if Edebug is not active.
-
- Adding text to the trace buffer also scrolls its window to show the
-last lines inserted.
+ @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.
@node Coverage Testing
@subsection Coverage Testing
@cindex frequency counts
@cindex performance analysis
Edebug provides rudimentary coverage testing and display of execution
-frequency. All execution of an instrumented function accumulates
-frequency counts, both before and after evaluation of each instrumented
-expression, even if the execution mode is Go-nonstop. Coverage testing
-is more expensive, so it is only done if @code{edebug-test-coverage} is
-non-@code{nil}. The command @kbd{M-x edebug-display-freq-count}
-displays both the frequency data and the coverage data (if recorded).
+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
+@code{edebug-test-coverage} is non-@code{nil}. 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.
+
+@kindex C-x X =
+@findex 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.
@deffn 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 @kbd{(} before an expression or the @kbd{)} after
-an expression, or on the last character of a symbol. Values do not appear if
-they are equal to the previous count on the same line.
+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
-This is the only coverage information that Edebug records.
+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,
-reinstrument it.
+simply reinstrument it with @code{eval-defun}.
@end deffn
For example, after evaluating @code{(fac 5)} with a source
@example
(defun fac (n)
(if (= n 0) (edebug))
-;#6 1 0 =5
+;#6 1 0 =5
(if (< 0 n)
-;#5 =
+;#5 =
(* n (fac (1- n)))
-;# 5 0
+;# 5 0
1))
-;# 0
+;# 0
@end example
The comment lines show that @code{fac} was called 6 times. The
program.
@itemize @bullet
-@item
+@item
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
-incremented one time to reduce Edebug's impact on the stack.
-You could, however, still run out of stack space when using Edebug.
+incremented once to reduce Edebug's impact on the stack. You could,
+however, still run out of stack space when using Edebug.
-@item
+@item
The state of keyboard macro execution is saved and restored. While
Edebug is active, @code{executing-macro} is bound to
@code{edebug-continue-kbd-macro}.
@c This paragraph is not filled, because LaLiberte's conversion script
@c 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
+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 comes back into Edebug at a breakpoint or after
-stepping without pausing or reading input in between. In such cases,
+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.
-What you see is the same window configuration as the last time Edebug
-was active, with no interruption.
+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, but some of these are deliberately not restored if an
-error or quit signal occurs.
+following data (though some of them are deliberately not restored if an
+error or quit signal occurs).
@itemize @bullet
-@item
+@item
@cindex 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.
-@item
+@item
@cindex window configuration (Edebug)
The outside window configuration is saved and restored if
@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}).
@code{overlay-arrow-string} are saved and restored. So you can safely
invoke Edebug from the recursive edit elsewhere in the same buffer.
-@item
+@item
@code{cursor-in-echo-area} is locally bound to @code{nil} so that
the cursor shows up in the window.
@end itemize
by the @code{recursive-edit}, but Edebug temporarily restores them during
evaluations.
-@item
+@item
The state of keyboard macro definition is saved and restored. While
Edebug is active, @code{defining-kbd-macro} is bound to
@code{edebug-continue-kbd-macro}.
@node Instrumenting Macro Calls
@subsection Instrumenting Macro Calls
-When Edebug instruments an expression that calls a Lisp macro, it needs
-additional advice to do the job properly. This is because there is no
-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.) You must
-explain the format of calls to each macro to enable Edebug to handle it.
-To do this, use @code{def-edebug-spec} to define the format of
-calls to a given macro.
+ 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 an @code{edebug} declaration to the macro
+definition. Here is a simple example that shows the specification for
+the @code{for} example macro (@pxref{Argument Evaluation}).
+
+@example
+(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 (edebug symbolp "from" form "to" form "do" &rest form))
+ ...)
+@end example
+
+ 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
+@code{edebug} 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.
@deffn Macro def-edebug-spec macro specification
Specify which expressions of a call to macro @var{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.
+evaluated. @var{specification} should be the edebug specification.
+It is not evaluated.
-The @var{macro} argument may actually be any symbol, not just a macro
+The @var{macro} argument can actually be any symbol, not just a macro
name.
@end deffn
-Here is a simple example that defines the specification for the
-@code{for} macro described in the Emacs Lisp Reference Manual, followed
-by an alternative, equivalent specification.
-
-@example
-(def-edebug-spec for
- (symbolp "from" form "to" form "do" &rest form))
-
-(def-edebug-spec for
- (symbolp ['from form] ['to form] ['do body]))
-@end example
-
Here is a table of the possibilities for @var{specification} and how each
directs processing of arguments.
@item 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 for another macro.
+found. This allows you to inherit the specification from another macro.
@item a list
The elements of the list describe the types of the arguments of a
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 only apply to the remainder of the
+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
@table @code
@item sexp
-A single Lisp object, not unevaluated.
-@c "unevaluated expression" is not meaningful, because
-@c an expression is a Lisp object intended for evaluation.
+A single unevaluated Lisp object, which is not instrumented.
+@c an "expression" is not necessarily intended for evaluation.
@item form
A single evaluated expression, which is instrumented.
A lambda expression with no quoting.
@item &optional
-@kindex &optional @r{(Edebug)}
+@c @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.
+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 @var{specs}@dots{}]}. To specify that several
[@var{specs}@dots{}]}. See the @code{defun} example below.
@item &rest
-@kindex &rest @r{(Edebug)}
+@c @kindex &rest @r{(Edebug)}
All following elements in the specification list are repeated zero or
-more times. All the elements need not match in the last repetition,
-however.
+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 @var{specs}@dots{}]}.
To specify several elements that must all match on every repetition, use
@code{&rest [@var{specs}@dots{}]}.
@item &or
-@kindex &or @r{(Edebug)}
+@c @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.
@code{[@dots{}]}.
@item ¬
-@kindex ¬ @r{(Edebug)}
+@c @kindex ¬ @r{(Edebug)}
Each of the following elements is matched as alternatives as if by using
@code{&or}, but if any of them match, the specification fails. If none
of them match, nothing is matched, but the @code{¬} specification
succeeds.
-@item &define
-@kindex &define @r{(Edebug)}
+@item &define
+@c @kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form. The defining
-form itself is not instrumented (i.e. Edebug does not stop before and
+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.
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
+grouping or an indirect specification, e.g., @code{(spec . [(more
specs@dots{})])}) whose elements match the non-dotted list arguments.
This is useful in recursive specifications such as in the backquote
example below. Also see the description of a @code{nil} specification
@c Need to document extensions with &symbol and :symbol
-Here is a list of additional specifications that may only appear after
+Here is a list of additional specifications that may appear only after
@code{&define}. See the @code{defun} example below.
@table @code
@item name
-The argument, a symbol, is the name of the defining form.
+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.
@item arg
The argument, a symbol, is the name of an argument of the defining form.
-However, lambda list keywords (symbols starting with @samp{@code{&}})
+However, lambda-list keywords (symbols starting with @samp{&})
are not allowed.
@item lambda-list
@end table
@node Backtracking
-@subsubsection Backtracking
+@subsubsection Backtracking in Specifications
@cindex backtracking
@cindex syntax error (Edebug)
matched by some element in the specification, and every required element
in the specification must match some argument.
-Backtracking is disabled for the remainder of a sublist or group when
-certain conditions occur, described below. Backtracking is reenabled
-when a new alternative is established by @code{&optional}, @code{&rest},
-or @code{&or}. It is also reenabled initially when processing a
-sublist or group specification or an indirect specification.
-
-You might want to disable backtracking to commit to some alternative so
-that Edebug can provide a more specific syntax error message. Normally,
-if no alternative matches, Edebug reports that none matched, but if one
-alternative is committed to, Edebug can report how it failed to match.
-
-First, backtracking is disabled while matching any of the form
-specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
+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
+@code{&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
@code{def-body}). These specifications will match any form so any error
must be in the form itself rather than at a higher level.
-Second, backtracking is disabled after successfully matching a quoted
+Backtracking is also disabled after successfully matching a quoted
symbol or string specification, since this usually indicates a
-recognized construct. If you have a set of alternative constructs that
+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.,
@code{["foo" &or [first case] [second case] ...]}.
-Third, backtracking may be explicitly disabled by using the
-@code{gate} specification. This is useful when you know that
-no higher alternatives may apply.
+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.
@node Specification Examples
@subsubsection Specification Examples
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 value. In the specification below, notice the @code{gate}
+optional expression. In the specification below, notice the @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.
@example
@smallexample
(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
-(def-edebug-spec defun
- (&define name lambda-list
+(def-edebug-spec defun
+ (&define name lambda-list
[&optional stringp] ; @r{Match the doc string, if present.}
[&optional ("interactive" interactive)]
def-body))
variable to @code{nil}.
If the value is a list, only the listed windows are saved and
-restored.
+restored.
You can use the @kbd{W} command in Edebug to change this variable
interactively. @xref{Edebug Display Update}.
@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
@code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
-The default value is @code{step}.
+The default value is @code{step}.
@xref{Edebug Execution Modes}.
@end defopt
@defopt edebug-trace
-@findex edebug-print-trace-before
-@findex edebug-print-trace-after
Non-@code{nil} means display a trace of 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.
+function entry or exit per line, indented by the recursion level.
-The default value is @code{nil}.
+The default value is @code{nil}.
-Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
+Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@end defopt
-@defopt edebug-test-coverage
+@defopt edebug-test-coverage
If non-@code{nil}, Edebug tests coverage of all expressions debugged.
-This is done by comparing the result of each expression
-with the previous result. Coverage is considered OK if two different
-results are found. So to sufficiently test the coverage of your code,
-try to execute it under conditions that evaluate all expressions more
-than once, and produce different results for each expression.
-
-Use @kbd{M-x edebug-display-freq-count} to display the frequency count
-and coverage information for a definition.
@xref{Coverage Testing}.
@end defopt
-@defopt edebug-continue-kbd-macro
+@defopt edebug-continue-kbd-macro
If non-@code{nil}, continue defining or executing any keyboard macro
that is executing outside of Edebug. Use this with caution since it is not
debugged.
@xref{Edebug Execution Modes}.
@end defopt
-@defopt edebug-print-length
-If non-@code{nil}, bind @code{print-length} to this while printing
-results in Edebug. The default value is @code{50}.
-@xref{Printing in Edebug}.
-@end defopt
-
-@defopt edebug-print-level
-If non-@code{nil}, bind @code{print-level} to this while printing
-results in Edebug. The default value is @code{50}.
-@end defopt
-
-@defopt edebug-print-circle
-If non-@code{nil}, bind @code{print-circle} to this while printing
-results in Edebug. The default value is @code{nil}.
-@end defopt
-
@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
@code{debug-on-error} was previously @code{nil}. @xref{Trapping
@c A new command is not precisely true, but that is close enough -- dan
@defopt edebug-global-break-condition
-If non-@code{nil}, an expression to test for at every stop point.
-If the result is non-nil, then break. Errors are ignored.
+If non-@code{nil}, an expression to test for at every stop point. If
+the result is non-@code{nil}, then break. Errors are ignored.
@xref{Global Break Condition}.
@end defopt
+
+@ignore
+ arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
+@end ignore