@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, 2005 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 Manual 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
Display expression results and evaluate expressions as if outside of
Edebug.
-@item
+@item
Automatically re-evaluate a list of expressions and
display their results each time Edebug updates the display.
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.
@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.
+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
(defun fac (n)
.(if .(< 0 n.).
- .(* n. .(fac (1- n.).).).
+ .(* n. .(fac .(1- n.).).).
1).)
@end 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
@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-current-buffer @r{(Edebug)}
@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
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
+in trace mode. The default is 1 second.
+@end defopt
@node Jumping
@subsection Jumping
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}
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
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
printing results. The default value is @code{50}.
@end defopt
-@defopt edebug-print-level
+@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
structure. This notation is used for any shared elements of lists or
vectors.
-@defopt edebug-print-circle
+@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}
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.
+@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
@example
(defun fac (n)
(if (= n 0) (edebug))
-;#6 1 0 =5
+;#6 1 = =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 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.
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}.
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, use @code{def-edebug-spec}.
+ Therefore, you must define an Edebug specification for each macro
+that Edebug will encounter, to explain the format of calls to that
+macro. To do this, add a @code{debug} declaration to the macro
+definition. Here is a simple example that shows the specification for
+the @code{for} example macro (@pxref{Argument Evaluation}).
+
+@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 (debug 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{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. 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 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} example macro (@pxref{Argument Evaluation}), 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.
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. In the last repetition, however, it is not a problem if the
expression runs out before matching all of the elements of the
@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 (that is, Edebug does not stop before and
after the defining form), but forms inside it typically will be
@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.
exhausted. Eventually every element of the argument list must be
matched by some element in the specification, and every required element
in the specification must match some argument.
-
+
When a syntax error is detected, it might not be reported until much
later after higher-level alternatives have been exhausted, and with the
point positioned further from the real error. But if backtracking is
constraint by factoring the symbol out of the alternatives, e.g.,
@code{["foo" &or [first case] [second case] ...]}.
-Most needs are satisfied by these two ways that bactracking is
+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
@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
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 @ref{Trace Buffer}.
@end defopt
-@defopt edebug-test-coverage
+@defopt edebug-test-coverage
If non-@code{nil}, Edebug tests coverage of all expressions debugged.
@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.
@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