@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 Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
+@c 2005, 2006, 2007 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
@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
-@cindex Edebug mode
+@cindex Edebug debugging facility
-@cindex Edebug
Edebug is a source-level debugger for Emacs Lisp programs with which
you can:
* Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
* Jumping:: Commands to jump to a specified place.
* Misc: Edebug Misc. Miscellaneous commands.
-* Breakpoints:: Setting breakpoints to make the program stop.
+* 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.
* 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.
-* Instrumenting Macro Calls:: Specifying how to handle macro calls.
+* Edebug and Macros:: Specifying how to handle macro calls.
* Options: Edebug Options. Option variables for customizing Edebug.
@end menu
the Lisp code you are debugging. This is referred to as the @dfn{source
code buffer}, and it is temporarily read-only.
- An arrow at the left margin indicates the line where the function is
+ 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.
@example
(defun fac (n)
.(if .(< 0 n.).
- .(* n. .(fac (1- n.).).).
+ .(* n. .(fac .(1- n.).).).
1).)
@end example
@kindex C-M-x
@findex eval-defun (Edebug)
- Once you have loaded Edebug, the command @kbd{C-M-x}
-(@code{eval-defun}) is redefined so that when invoked with a prefix
-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: 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}.
+ 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
+non-@code{nil}, 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
+@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value
+of the variable @code{edebug-all-defs}.
@findex eval-region @r{(Edebug)}
+@findex eval-buffer @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}
(@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 @r{(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. 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.
+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
@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.
+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
@item n
Next: stop at the next stop point encountered after an expression
(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
-@ref{Edebug Misc}.
+@ref{Jumping}.
@item t
Trace: pause (normally one second) at each Edebug stop point
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
-the value of the variable @code{edebug-initial-mode}. By default, this
-specifies step mode. Note that you may reenter the same Edebug level
-several times if, for example, an instrumented function is called
-several times from one command.
+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.
@defopt edebug-sit-for-seconds
This option specifies how many seconds to wait between execution steps
Proceed to the stop point near where point is (@code{edebug-goto-here}).
@item f
-Run the program forward over one expression
+Run the program for one expression
(@code{edebug-forward-sexp}).
@item o
Step into the function or macro called by the form after point.
@end table
-The @kbd{h} command proceeds to the stop point near the current location
-of point, using a temporary breakpoint. See @ref{Breakpoints}, for more
-information about breakpoints.
+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
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
+@node Breaks
+@subsection Breaks
-@cindex breakpoints
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.
+@menu
+* Breakpoints:: Breakpoints at stop points.
+* Global Break Condition:: Breaking on an event.
+* Source Breakpoints:: Embedding breakpoints in source code.
+@end menu
+
+@node Breakpoints
+@subsubsection Edebug Breakpoints
+
+@cindex 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
@item x @var{condition} @key{RET}
Set a conditional breakpoint which stops the program only if
-@var{condition} evaluates to a non-@code{nil} value
-(@code{edebug-set-conditional-breakpoint}). With a prefix argument, the
-breakpoint is temporary.
+evaluating @var{condition} produces a non-@code{nil} value
+(@code{edebug-set-conditional-breakpoint}). With a prefix argument,
+the breakpoint is temporary.
@item B
Move point to the next breakpoint in the current definition
breakpoints. This command does not continue execution---it just moves
point in the buffer.
-@menu
-* Global Break Condition:: Breaking on an event.
-* Source Breakpoints:: Embedding breakpoints in source code.
-@end menu
-
-
@node Global Break Condition
@subsubsection Global Break Condition
@findex 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}).
+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
@table @kbd
@item v
-Temporarily view the outside window configuration
-(@code{edebug-view-outside}).
+Switch to viewing the outside window configuration
+(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
@item p
-Temporarily display the outside current buffer with point at its outside
-position (@code{edebug-bounce-point}). With a prefix argument @var{n},
-pause for @var{n} seconds instead.
+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
+@var{n} seconds instead.
@item w
Move point back to the current stop point in the source code buffer
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.
+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
+@kbd{C-x 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
@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}.
+printing results. The default value is @code{t}.
@end defopt
Other programs can also use custom printing; see @file{cust-print.el}
@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, and
-@code{edebug-tracing} returns the value of the last form in @var{body}.
+to put in the trace buffer, after the @samp{@{} or @samp{@}}. All
+the arguments are evaluated, and @code{edebug-tracing} returns the
+value of the last form in @var{body}.
@end defmac
@defun edebug-trace format-string &rest format-args
@node Coverage Testing
@subsection Coverage Testing
-@cindex coverage testing
+@cindex coverage testing (Edebug)
@cindex frequency counts
@cindex performance analysis
-Edebug provides rudimentary coverage testing and display of execution
+ Edebug provides rudimentary coverage testing and display of execution
frequency.
Coverage testing works by comparing the result of each expression with
@example
(defun fac (n)
(if (= n 0) (edebug))
-;#6 1 0 =5
+;#6 1 = =5
(if (< 0 n)
;#5 =
(* n (fac (1- n)))
@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}.
-
+Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
+unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
@end itemize
@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{edebug-save-windows} is non-@code{nil} (@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
The current match data. @xref{Match Data}.
@item
-@code{last-command}, @code{this-command}, @code{last-command-char},
-@code{last-input-char}, @code{last-input-event},
-@code{last-command-event}, @code{last-event-frame},
-@code{last-nonmenu-event}, and @code{track-mouse}. Commands used within
-Edebug do not affect these variables outside of Edebug.
+The variables @code{last-command}, @code{this-command},
+@code{last-command-char}, @code{last-input-char},
+@code{last-input-event}, @code{last-command-event},
+@code{last-event-frame}, @code{last-nonmenu-event}, and
+@code{track-mouse}. Commands used within Edebug do not affect these
+variables outside of Edebug.
-The key sequence returned by @code{this-command-keys} is changed by
-executing commands within Edebug and there is no way to reset
-the key sequence from Lisp.
+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
@code{unread-command-events}. Entering Edebug while this variable has a
@code{edebug-continue-kbd-macro}.
@end itemize
+@node Edebug and Macros
+@subsection Edebug and Macros
+
+To make Edebug properly instrument expressions that call macros, some
+extra care is needed. This subsection explains the details.
+
+@menu
+* 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.
+@end menu
+
@node Instrumenting Macro Calls
-@subsection Instrumenting Macro Calls
+@subsubsection 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
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
+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}).
-@example
+@smallexample
(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))
+ (declare (debug (symbolp "from" form "to" form "do" &rest form)))
...)
-@end example
+@end smallexample
The Edebug specification says which parts of a call to the macro are
forms to be evaluated. For simple macros, the @var{specification}
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.
+@code{debug} 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. @var{specification} should be the edebug specification.
-It is not evaluated.
+Neither argument is evaluated.
The @var{macro} argument can actually be any symbol, not just a macro
name.
described in the following sections.
@end table
-@menu
-* Specification List:: How to specify complex patterns of evaluation.
-* Backtracking:: What Edebug does when matching fails.
-* Specification Examples:: To help understand specifications.
-@end menu
-
+@vindex 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
+@code{edebug-eval-macro-args} comes into play. If it is @code{nil},
+the default, none of the arguments is instrumented for evaluation.
+If it is non-@code{nil}, all arguments are instrumented.
@node Specification List
@subsubsection Specification List
indirect specifications.
Here's a table of the possible elements of a specification list, with
-their meanings:
+their meanings (see @ref{Specification Examples}, for the referenced
+examples):
@table @code
@item sexp
To make just a few elements optional followed by non-optional elements,
use @code{[&optional @var{specs}@dots{}]}. To specify that several
elements must all match or none, use @code{&optional
-[@var{specs}@dots{}]}. See the @code{defun} example below.
+[@var{specs}@dots{}]}. See the @code{defun} example.
@item &rest
@c @kindex &rest @r{(Edebug)}
@item 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 below.
+specifications and the backquote example.
@item gate
@cindex 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
-@ref{Backtracking}, for more details. Also see the @code{let} example
-below.
+@ref{Backtracking}, for more details. Also see the @code{let} example.
@item @var{other-symbol}
@cindex indirect specifications
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 below.
+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
@item (vector @var{elements}@dots{})
The argument should be a vector whose elements must match the
-@var{elements} in the specification. See the backquote example below.
+@var{elements} in the specification. See the backquote example.
@item (@var{elements}@dots{})
Any other list is a @dfn{sublist specification} and the argument must be
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
+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)}
@c Need to document extensions with &symbol and :symbol
Here is a list of additional specifications that may appear only after
-@code{&define}. See the @code{defun} example below.
+@code{&define}. See the @code{defun} example.
@table @code
@item name
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
-@code{interactive} example below.
+@code{interactive} example.
@end table
@node Backtracking
Edebug uses the following specifications for @code{defun} and
@code{defmacro} and the associated argument list and @code{interactive}
specifications. It is necessary to handle interactive forms specially
-since an expression argument it is actually evaluated outside of the
+since an expression argument is actually evaluated outside of the
function body.
@smallexample
@end defopt
@defopt edebug-trace
-Non-@code{nil} means display a trace of function entry and exit.
+If this is non-@code{nil}, 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.
-The default value is @code{nil}.
-
Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@end defopt
HCoop / bpt / emacs.git / blobdiff