@comment -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1992-1994, 1998-1999, 2001-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1992-1994, 1998-1999, 2001-2013 Free Software
+@c 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, Syntax Errors, Debugger, Debugging
+@node Edebug
@section Edebug
@cindex Edebug debugging facility
@node Instrumenting
@subsection Instrumenting for Edebug
+@cindex instrumenting for Edebug
In order to use Edebug to debug Lisp code, you must first
@dfn{instrument} the code. Instrumenting code inserts additional code
edebug-all-forms} toggles this option.
@findex edebug-eval-top-level-form
+@findex edebug-defun
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}.
+@code{edebug-defun} is an alias for @code{edebug-eval-top-level-form}.
While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
If Edebug detects a syntax error while instrumenting, it leaves point
at the erroneous code and signals an @code{invalid-read-syntax} error.
+@c FIXME? I can't see that it "leaves point at the erroneous code".
@xref{Edebug Eval}, for other evaluation functions available
inside of Edebug.
@item S
Stop: don't execute any more of the program, but wait for more
Edebug commands (@code{edebug-stop}).
+@c FIXME Does not work. http://debbugs.gnu.org/9764
@item @key{SPC}
Step: stop at the next stop point encountered (@code{edebug-step-mode}).
Run the program until the end of the containing sexp (@code{edebug-step-out}).
@item i
-Step into the function or macro called by the form after point.
+Step into the function or macro called by the form after point
+(@code{edebug-step-in}).
@end table
The @kbd{h} command proceeds to the stop point at or after the current
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
+automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may
conflict with the buffers you wish to see unless you have enough windows
open.
@node Edebug Eval
@subsection Evaluation
- While within Edebug, you can evaluate expressions ``as if'' Edebug
+ 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
lexically bound symbols created by the following constructs in
@file{cl.el}: @code{lexical-let}, @code{macrolet}, and
@code{symbol-macrolet}.
+@c FIXME? What about lexical-binding = t?
@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 @file{*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.
@table @kbd
@item E
-Switch to the evaluation list buffer @samp{*edebug*}
+Switch to the evaluation list buffer @file{*edebug*}
(@code{edebug-visit-eval-list}).
@end table
- In the @samp{*edebug*} buffer you can use the commands of Lisp
+ In the @file{*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:
@end table
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*};
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*};
but they are evaluated in the context outside of Edebug.
The expressions you enter interactively (and their results) are lost
@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
+After selecting @file{*edebug*}, you can return to the source code
+buffer with @kbd{C-c C-w}. The @file{*edebug*} buffer is killed when
you continue execution, and recreated next time it is needed.
@node Printing in Edebug
@cindex trace buffer
Edebug can record an execution trace, storing it in a buffer named
-@samp{*edebug-trace*}. This is a log of function calls and returns,
+@file{*edebug-trace*}. 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 non-@code{nil} value.
@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
-(@pxref{Window Configurations}). When you exit Edebug (by continuing
-the program), it restores the previous window configuration.
+(@pxref{Window Configurations}). When you exit Edebug, 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
@item
The variables @code{last-command}, @code{this-command},
-@code{last-input-event}, @code{last-command-event},
+@code{last-command-event}, @code{last-input-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.
+@code{track-mouse}. Commands in 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
arguments. @xref{Defining Macros}, for more explanation of
the @code{declare} form.
+@c See, e.g., http://debbugs.gnu.org/10577
+@c FIXME Maybe there should be an Edebug option to get it to
+@c automatically load the entire source file containing the function
+@c being instrumented. That would avoid this.
+ Take care to ensure that the specifications are known to Edebug when
+you instrument code. If you are instrumenting a function from a file
+that uses @code{eval-when-compile} to require another file containing
+macro definitions, you may need to explicitly load that file.
+
You can also define an edebug specification for a macro separately
from the macro definition with @code{def-edebug-spec}. Adding
@code{debug} declarations is preferred, and more convenient, for macro
@dfn{specification keywords}, are symbols beginning with @samp{&} (such
as @code{&optional}).
-A specification list may contain sublists which match arguments that are
+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
A single evaluated expression, which is instrumented.
@item place
-@c I can't see that this index entry is useful without any explanation.
-@c @findex edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
+A generalized variable. @xref{Generalized Variables}.
@item body
Short for @code{&rest form}. See @code{&rest} below.
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,
+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.
of them match, nothing is matched, but the @code{¬} specification
succeeds.
+@c FIXME &key?
+
@item &define
@c @kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form. The defining
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
-@code{nil}, and the argument is not instrumented.
+with the argument, and if the predicate returns @code{nil}, the
+specification fails and the argument is not instrumented.
Some suitable predicates include @code{symbolp}, @code{integerp},
@code{stringp}, @code{vectorp}, and @code{atom}.
optional expression. In the specification below, notice the @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.
-@c FIXME? The actual definition in edebug.el does not have a gate.
+@ignore
+@c FIXME? The actual definition in edebug.el looks like this (and always
+@c has AFAICS). In fact, nothing in edebug.el uses gate. So maybe
+@c this is just an example for illustration?
+(def-edebug-spec let
+ ((&rest
+ &or (symbolp &optional form) symbolp)
+ body))
+@end ignore
@example
(def-edebug-spec let
((&rest
@defopt 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
-@code{edebug-setup-hook} is reset to @code{nil}. You could use this to
-load up Edebug specifications associated with a package you are using
+reset @code{edebug-setup-hook} 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.
@xref{Instrumenting}.
@end defopt
@defopt edebug-trace
If this is non-@code{nil}, trace each function entry and exit.
-Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
+Tracing output is displayed in a buffer named @file{*edebug-trace*}, one
function entry or exit per line, indented by the recursion level.
Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@xref{Edebug Execution Modes}.
@end defopt
-@c FIXME edebug-unwrap-results
+@defopt edebug-unwrap-results
+If non-@code{nil}, Edebug tries to remove any of its own
+instrumentation when showing the results of expressions. This is
+relevant when debugging macros where the results of expressions are
+themselves instrumented expressions. As a very artificial example,
+suppose that the example function @code{fac} has been instrumented,
+and consider a macro of the form:
+
+@c FIXME find a less silly example.
+@smallexample
+(defmacro test () "Edebug example."
+ (if (symbol-function 'fac)
+ @dots{}))
+@end smallexample
+
+If you instrument the @code{test} macro and step through it, then by
+default the result of the @code{symbol-function} call has numerous
+@code{edebug-after} and @code{edebug-before} forms, which can make it
+difficult to see the ``actual'' result. If
+@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
+these forms from the result.
+@end defopt
@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
HCoop / bpt / emacs.git / blobdiff