@comment -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1992, 1993, 1994, 1998, 1999 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c This file can also be used by an independent Edebug User
@c , Bugs and Todo List, Top, Top
-@node Edebug,, Compilation Errors, Debugging
+@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
@cindex Edebug mode
* 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)
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
+Here we use periods to show the stop points in the function
@code{fac}:
@example
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-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)
@pindex cl-specs.el
Edebug knows how to instrument all the standard special forms,
@code{interactive} forms 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; see @ref{Instrumenting Macro Calls}, for details.
+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 arrange to load Edebug specifications
+@code{nil}. You can use this to load Edebug specifications
(@pxref{Instrumenting Macro Calls}) associated with a package you are
-using, but actually load them only if you use Edebug.
+using, but only when you use Edebug.
@findex eval-expression @r{(Edebug)}
To remove instrumentation from a definition, simply re-evaluate its
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}
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
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
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
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 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
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
@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
@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)
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
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
@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}
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
@xref{Output Variables}.
@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}.
+If non-@code{nil}, Edebug binds @code{print-length} to this value while
+printing results. The default value is @code{50}.
@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}.
+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 using the @file{cust-print} package.
-
- 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}.
+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:
vectors.
@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}.
+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}
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. Coverage testing works by comparing the result of each
-expression with the previous result; coverage is considered OK if two
-different results are found. Thus, 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. Coverage testing makes execution slower, so it is only done
-if @code{edebug-test-coverage} is non-@code{nil}. Whether or not
-coverage testing is enabled, frequency counting is performed for all
-execution of an instrumented function, even if the execution mode is
-Go-nonstop.
-
-Use @kbd{M-x edebug-display-freq-count} to display both the
+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.
+
+ Use @kbd{M-x edebug-display-freq-count} to display both the
coverage information and the frequency counts for a definition.
@deffn Command edebug-display-freq-count
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.
+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}.
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
@end deffn
Here is a simple example that defines the specification for the
-@code{for} example macro (@code{Argument Evaluation}), followed by an
+@code{for} example macro (@pxref{Argument Evaluation}), followed by an
alternative, equivalent specification.
@example
@table @code
@item sexp
-A single unevaluated expression, which is not instrumented.
+A single unevaluated Lisp object, which is not instrumented.
@c an "expression" is not necessarily intended for evaluation.
@item form
@item &rest
@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