
@c for Edebug node below when used with edebug.texinfo:
@c @node Edebug, Bugs and Todo List, Top, Top

@node Edebug
@section Edebug
@cindex Edebug mode

  Edebug is a source-level debugger for XEmacs Lisp programs that
provides the following features:

@itemize @bullet
@item
Step through evaluation, stopping before and after each expression.

@item
Set conditional or unconditional breakpoints, install persistent
breakpoints, or a global break event.

@item
Trace slow or fast stopping briefly at each stop point, or
each breakpoint.

@item
Display expression results and evaluate expressions as if outside of
edebug.  Interface with the custom printing package 
for printing circular structures.

@item 
Automatically reevaluate a list of expressions and
display their results each time Edebug updates the display.

@item
Output trace info on function enter and exit.

@item
Errors stop before the source causing the error.

@item
Display backtrace without edebug calls.

@item
Allow specification of argument evaluation for macros and defining forms.

@item
Provide rudimentary coverage testing and display of frequency counts.

@end itemize

The first three sections of this chapter should tell you enough about
Edebug to enable you to use it.

@menu
* Using Edebug::		Introduction to use of Edebug.
* Instrumenting::		You must first instrument code.
* Edebug Execution Modes::	Execution modes, stopping more or less often.
* Jumping::			Commands to jump to a specified place.
* Edebug Misc::			Miscellaneous commands.
* Breakpoints::			Setting breakpoints to make the program stop.
* Views::			Viewing the outside buffer and window status.
* Edebug Eval::			Evaluating expressions within Edebug.
* Eval List::			Automatic expression evaluation.
* Printing::			Printing circular structure in Edebug.
* Coverage Testing::		How to test evaluation coverage.
* The Outside Context::		Data that Edebug saves and restores.
* Macro Calls::			Specifying how to handle macro calls.
* Edebug Options::		Option variables for customizing Edebug.
@end menu

@node Using Edebug
@subsection Using Edebug

  To debug a Emacs Lisp program with Edebug, you must first
@dfn{instrument} the Lisp functions that you want to debug.
@xref{Instrumenting}.

  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 the selected Edebug
execution mode.  The initial execution mode is @code{step}, by default,
which does stop execution.  @xref{Edebug Execution Modes}.

  Within Edebug, you normally view an Emacs buffer showing the source of
the Lisp function you are debugging.  We call this the @dfn{Edebug
buffer}---but note that it is not always the same buffer, and it is not
reserved for Edebug use.

  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) for Edebug and
then execute @code{(fac 3)}, here is what you normally see.  Point is at
the open-parenthesis before @code{if}.

@example
(defun fac (n)
=>@point{}(if (< 0 n)
      (* n (fac (1- n)))
    1))
@end example

@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.  
@c Stop points before variables are optional, under the control of the value of
@c @code{edebug-stop-before-symbols}.  -- this is going away.
Here we show with periods the stop points found in the function
@code{fac}:

@example
(defun fac (n)
  .(if .(< 0 n.).
      .(* n. .(fac (1- n.).).).
    1).)
@end example

While a buffer is the Edebug buffer, the special commands of Edebug are
available in it, instead of many usual editing commands.  Type @kbd{?}
to display a list of Edebug commands.  In particular, you can exit just
the innermost Edebug activation level with @kbd{C-]}, and you can return
all the way to top level with @kbd{q}.

For example, you can type the Edebug command @key{SPC} to execute until
the next stop point.  If you type @key{SPC} once after entry to
@code{fac}, here is the state that you get:

@example
(defun fac (n)
=>(if @point{}(< 0 n)
      (* n (fac (1- n)))
    1))
@end example

When Edebug stops execution after an expression, it displays the
expression's value in the echo area.  Use the @kbd{r} command to display
the value again later.

@vindex debugger
@vindex debug-on-error
@vindex debug-on-quit
If no instrumented code is currently being executed, @code{debug} is run
normally.  But while Edebug is active, it catches all errors (if
@code{debug-on-error} is non-@code{nil}) and quits (if
@code{debug-on-quit} is non-@code{nil}).  When this happens, Edebug
displays the last stop point that it knows about.  This may be the
location of a call to a function which was not instrumented, within
which the error actually occurred.  Note that you can also get a full
backtrace inside of Edebug (see @ref{Edebug Misc}).

@node Instrumenting
@subsection Instrumenting for Edebug

  In order to use Edebug to debug Lisp code, you must first
@dfn{instrument} the code.  Instrumenting a form inserts additional code
into it which invokes Edebug at the proper places.  When instrumenting
any kind of definition (not just @code{defun} or @code{defmacro}), only
the executable expressions inside of the definition are instrumented.
If any syntax error is found while instrumenting, point is left at the
error and an @code{invalid-read-syntax} error is signaled.

@cindex special forms
@cindex interactive forms
@cindex anonymous lambda expressions
  Edebug knows how to instrument all the standard special forms,
interactive forms with or without expression arguments, anonymous lambda
expressions, and other defining forms.  It cannot know what a
user-defined macro will do with the arguments of a macro call so you
must tell it; @pxref{Macro Calls} for the details.

@kindex C-M-x
@findex eval-defun
@findex edebug-all-defs
  Once you have loaded Edebug, the command @kbd{C-M-x}
(@code{eval-defun}) is redefined so that when used with a prefix
argument on a definition, it instruments the definition.  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
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
  If @code{edebug-all-defs} is non-@code{nil}, then the commands
@code{eval-region} and @code{eval-current-buffer} also instrument any
definitions they evaluate.  Similarly, @code{edebug-all-forms} controls
whether @code{eval-region} should instrument @emph{any} form, even
non-defining forms.  The command @kbd{M-x 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}.  Additionally, this command will instrument
top-level forms that are not definitions.

@findex eval-expression
  Loading a file does not instrument expressions for Edebug.
Evaluations in the minibuffer via @code{eval-expression} (@kbd{M-ESC})
are never instrumented.

  To remove instrumentation from a definition, simply reevaluate it with
one of the non-instrumenting commands that evaluate definitions, or
reload the file.

See @ref{Edebug Eval} for discussion of other evaluation functions available
inside of Edebug.

@node Edebug Execution Modes
@subsection Edebug Execution Modes

@cindex Edebug execution modes
Edebug supports several execution modes for running the program you are
debugging.  We call these alternatives @dfn{Edebug execution modes}; do
not confuse them with major modes or minor modes.  The current Edebug
execution mode determines how Edebug displays the progress of the
evaluation, whether it stops at each stop point, or continues to the
next breakpoint, for example.

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
least for a certain distance.

@table @kbd
@item S
Stop: don't execute any more of the program for now, just wait for more
Edebug commands.  (@code{edebug-stop})

@item @key{SPC}
Step: stop at the next stop point encountered. (@code{edebug-step-mode})

@item n
Next: stop at the next stop point encountered after an expression.  Also
see @code{edebug-forward-sexp} in @ref{Edebug Misc}.
(@code{edebug-next-mode})

@item t
Trace: pause one second at each Edebug stop point. (@code{edebug-trace-mode})

@item T
Rapid trace: update at each stop point, but don't actually
pause. (@code{edebug-Trace-fast-mode})

@item g
Go: run until the next breakpoint.  @xref{Breakpoints}. (@code{edebug-go-mode})

@item c
Continue: pause for one second at each breakpoint, but don't stop. (@code{edebug-continue-mode})

@item C
Rapid continue: update at each breakpoint, but don't actually pause.  (@code{edebug-Continue-fast-mode})

@item G
Go non-stop: ignore breakpoints.  You can still stop the program by typing
@kbd{S}. (@code{edebug-Go-nonstop-mode})
@end table

In general, the execution modes earlier in the above list run the
program more slowly or stop sooner.

When you enter a new Edebug level, the mode comes from the value of the
variable @code{edebug-initial-mode}.  By default, this specifies
@dfn{step} mode.  If the mode thus specified does not stop, then the
Edebug level executes the program (or part of it).

While executing or tracing, you can interrupt the execution by typing
any Edebug command.  Edebug stops the program at the next stop point and
then executes the command that you typed.  For example, typing @kbd{t}
during execution switches to trace mode at the next stop point.

You can use the @kbd{S} command to stop execution without doing anything else.

If your function happens to read input, a character you hit intending to
interrupt execution may be read by the function instead.  You can avoid
such unintended results by paying attention to when your program wants
input.

Keyboard macros containing the commands in this section do not
completely work: exiting from Edebug, to resume the program, loses
track of the keyboard macro.  This is not easy to fix.

@node Jumping
@subsection Jumping

Commands described here let you jump to a specified location.
All, except @kbd{i}, use temporary breakpoints to establish the stop
point and then switch to @code{go} mode.  Any other breakpoint reached
before the intended stop point will also stop execution.  See
@ref{Breakpoints} for the details on breakpoints.

@table @kbd
@item f
Run the program forward over one expression.  More precisely, set a
temporary breakpoint at the position that @kbd{C-M-f} would reach,
then execute in @code{go} mode so that the program will stop at breakpoints.

With a prefix argument @var{n}, the temporary breakpoint is placed
@var{n} sexps beyond point.  If the containing list ends before @var{n}
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{condition-case}, for example.

This command does @code{forward-sexp} starting at point rather than the
stop point, thus providing more flexibility.  If you want to execute one
expression from the current stop point, type @kbd{w} first, to move
point there.

(@code{edebug-forward-sexp})

@item o
Continue ``out of'' an expression.  It places a temporary breakpoint at
the end of the sexp containing point.  If the containing sexp is the
definition itself, it continues until just before the returns.  If that
is where you are now, it returns from the function and then stops.

In other words, this command does not exit the currently executing
definition unless you are positioned after the last sexp.

(@code{edebug-step-out})

@item i
Step into the definition of the function or macro about to be called,
whether or not it has been instrumented.  If its location is not known
to Edebug, this command cannot be used.  After loading Edebug,
@code{eval-region} records the position of every definition it
evaluates, even if not instrumented.

Use this command when stopped before the call, since otherwise it is too
late.

This command does not switch to @code{go} mode; instead you must execute
the arguments before stepping into the function manually.  (A future
version will probably do as expected: set a temporary breakpoint on the
first expression in the function and switch to @code{go} mode.)

Although the automatic instrumentation is convenient, one undesirable
side effect of using @code{edebug-step-in} is that it doesn't later
uninstrument the stepped-into function.

@item h
Proceed to the stop point near where point is using a temporary
breakpoint.

(@code{edebug-goto-here})
@end table

All the commands in this section 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.

@node Edebug Misc
@subsection Miscellaneous

Some miscellaneous commands are described here.

@table @kbd
@item ?
Display the help message for Edebug.
(@code{edebug-help})

@item C-]
Abort one level back to the previous command level.
(@code{abort-recursive-edit})

@item q
Return to the top level editor command loop.  This exits all recursive
editing levels, including all levels of Edebug activity.  However,
instrumented code protected with @code{unwind-protect} or
@code{condition-case} forms may resume debugging.
(@code{top-level})

@item Q
Like @kbd{q} but don't stop even for protected code.
(@code{top-level-nonstop}) 

@item r
Redisplay the most recently known expression result in the echo area.
(@code{edebug-previous-result})

@item d
Display a backtrace, excluding Edebug's own functions for clarity.

You cannot use debugger commands in the backtrace buffer in Edebug as
you would in the standard debugger.

The backtrace buffer is killed automatically when you continue
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 currently active
function and macro calls with @kbd{d}.

@node Breakpoints
@subsection Breakpoints

@cindex breakpoints
Three more ways to stop execution once it has started are:
breakpoints, the global break condition, and persistent breakpoints.

@cindex breakpoints
While using Edebug, you can specify @dfn{breakpoints} in the program you
are testing: points 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 Edebug buffer.  Here are the
Edebug commands for breakpoints:

@table @kbd
@item b
Set a breakpoint at the stop point at or after point.  If you use a
prefix argument, the breakpoint is temporary (it turns off the first
time it stops the program). (@code{edebug-set-breakpoint})

@item u
Unset the breakpoint (if any) at the stop point at or after the current
point. (@code{edebug-unset-breakpoint})

@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.  If you use a prefix argument, the
breakpoint is temporary (it turns off the first time it stops the
program). (@code{edebug-set-conditional-breakpoint})

@item B
Move point to the next breakpoint in the current definition.
(@code{edebug-next-breakpoint})
@end table

While in Edebug, you can set a breakpoint with @kbd{b} and unset one
with @kbd{u}.  First you must move point to a position at or before the
desired Edebug stop point, then hit the key to change the breakpoint.
Unsetting a breakpoint that has not been set does nothing.

Reinstrumenting a definition clears all its breakpoints.

A @dfn{conditional breakpoint} tests a condition each time the program
gets there, to decide whether to stop.  To set a conditional breakpoint,
use @kbd{x}, and specify the condition expression in the minibuffer.
Setting a conditional breakpoint again will put the previously entered
expression in the minibuffer.

You can make both conditional and unconditional breakpoints
@dfn{temporary} by using a prefix arg to the command to set the
breakpoint.  After breaking at a temporary breakpoint, it is
automatically cleared.

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
moves point to the next breakpoint in the definition following point, or
to the first breakpoint if there are no following breakpoints.  This
command does not continue execution---it just moves point in the buffer.

@menu
* Global Break Condition::	Breaking on an event. 
* Persistent Breakpoints::	Embedding breakpoints in code.
@end menu

@node Global Break Condition
@subsubsection Global Break Condition

@cindex stopping on events
@cindex global break condition
In contrast to breaking when execution reaches specified locations,
you can also cause a break when a certain event occurs.  The @dfn{global
break condition} is a condition that is repeatedly evaluated at every
stop point.  If it evaluates to a non-@code{nil} value, then execution
is stopped or paused depending on the execution mode, just like a
breakpoint.  Any errors that might occur as a result of evaluating the
condition are ignored, as if the result were @code{nil}.  

@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 @kbd{X}
(@code{edebug-set-global-break-condition}).

Using the global break condition is perhaps the fastest way
to find where in your code some event occurs, but since it is rather
expensive you should reset the condition to @code{nil} when not in use.

@node Persistent Breakpoints
@subsubsection Persistent Breakpoints

@findex edebug
@cindex persistent breakpoints
Since all breakpoints in a definition are cleared each time you
reinstrument it, you might rather install a @dfn{persistent breakpoint}
which is simply a call to the function @code{edebug}.  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:

@example
(defun fac (n)
  (if (= n 0) (edebug))
  (if (< 0 n)
      (* n (fac (1- n)))
    1))
@end example

When the @code{fac} definition is instrumented and the function is called,
edebug will cause a break before the call to @code{edebug}.  Depending on
the execution mode, edebug will stop or pause.

However, if no instrumented code is being executed, calling
@code{edebug} will instead invoke @code{debug}.

@node Views
@subsection Views

These Edebug commands let you view aspects of the buffer and window
status that obtained before entry to Edebug.

@table @kbd
@item v
View the outside window configuration. (@code{edebug-view-outside})

@item p
Temporarily display the outside current buffer with point at its outside
position. If prefix arg is supplied, sit for
that many seconds instead.  (@code{edebug-bounce-point})

@item w
Switch back to the buffer showing the currently executing function, and
move point back to the current stop point. (@code{edebug-where})

@item W
Toggle the @code{edebug-save-windows} variable which indicates whether
the outside window configuration is saved and restored.  Also, each time
it is toggled on, make the outside window configuration the same as
the current window configuration.
(@code{edebug-toggle-save-windows})
@end table

You can view the outside window configuration with @kbd{v} or just
bounce to the current point in the current buffer with @kbd{p}, even if
it is not normally displayed.  After moving point, you may wish to pop
back to the stop point with @kbd{w} from the Edebug buffer.

By using the @kbd{W} command twice, Edebug again saves and restores the
outside window configuration, but to the current configuration.  This is
a convenient way to, for example, add another buffer to be displayed
whenever Edebug is active.  However, the automatic redisplay of
@samp{*edebug*} and @samp{*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 were
not running.  Edebug tries to be invisible to the expression's
evaluation and printing.  See @ref{The Outside Context} for details on
this process.  Also see @ref{Printing} for how to control printing.

@table @kbd
@item e @var{exp} @key{RET}
Evaluate expression @var{exp} in the context outside of Edebug.
That is, Edebug tries to avoid altering the effect of @var{exp}.
(@code{edebug-eval-expression})

@item M-@key{ESC} @var{exp} @key{RET}
Evaluate expression @var{exp} in the context of Edebug itself.

@item C-x C-e
Evaluate the expression before point, in the context outside of Edebug.
(@code{edebug-eval-last-sexp})
@end table

@node Eval List
@subsection Evaluation List Buffer

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.

@table @kbd
@item E
Switch to the evaluation list buffer @samp{*edebug*}.
(@code{edebug-visit-eval-list}) 
@end table

In the @samp{*edebug*} buffer you can use the commands of Lisp
Interaction as well as these special commands:

@table @kbd
@item LFD
Evaluate the expression before point, in the context outside of Edebug,
and insert the value in the buffer.
(@code{edebug-eval-print-last-sexp})

@item C-x C-e
Evaluate the expression before point, in the context outside of Edebug.
(@code{edebug-eval-last-sexp})

@item C-c C-u
Build a new evaluation list from the first expression of each group,
reevaluate and redisplay.  Groups are separated by comment lines.
(@code{edebug-update-eval-list})

@item C-c C-d
Delete the evaluation list group that point is in.
(@code{edebug-delete-eval-item})

@item C-c C-w
Switch back to the Edebug buffer at the current stop point.
(@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*};
but they are evaluated in the context outside of Edebug.

@cindex evaluation list group
The expressions you enter interactively (and their results) are lost
when you continue execution unless you add them to the
evaluation list with @kbd{C-c C-u}.  This command builds a new list from
the first expression of each @dfn{evaluation list group}.  Groups are
separated by comment lines.  Be careful not to add expressions that
execute instrumented code otherwise an infinite loop will result.

When the evaluation list is redisplayed, each expression is displayed
followed by the result of evaluating it, and a comment line.  If an
error occurs during an evaluation, the error message is displayed in a
string as if it were the result.  Therefore expressions that use
variables not currently valid, for example, do not interrupt your
debugging.

Here is an example of what the evaluation list window looks like after
several expressions have been added to it:

@smallexample
(current-buffer)
#<buffer *scratch*>
;---------------------------------------------------------------
(selected-window)
#<window 16 on *scratch*>
;---------------------------------------------------------------
(point)
196
;---------------------------------------------------------------
bad-var
"Symbol's value as variable is void: bad-var"
;---------------------------------------------------------------
(recursion-depth)
0
;---------------------------------------------------------------
this-command
eval-last-sexp
;---------------------------------------------------------------
@end 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}.  When you add a new group, be sure it is separated from
its neighbors by a comment line.

After selecting @samp{*edebug*}, you can return to the source code
buffer (the Edebug buffer) with @kbd{C-c C-w}.  The @code{*edebug*}
buffer is killed when you continue execution, and
recreated next time it is needed.

@c Document Reading and cl-read.

@node Printing
@subsection Printing

@cindex printing circular structures
@cindex cust-print
If some structures that may be printed contain circular references to
other parts of the same structure, you can print them more usefully with
the @file{cust-print} package.

To load the package and activate custom printing only for Edebug, simply
use the command @code{edebug-install-custom-print-funcs}.  
To restore the standard print functions, use
@code{edebug-uninstall-custom-print-funcs}.

While printing results, edebug binds @code{print-length},
@code{print-level}, and @code{print-circle} to
@code{edebug-print-length} (@code{50}), @code{edebug-print-level}
(@code{50}), and @code{edebug-print-circle} (@code{t}) respectively, if
these values are non-@code{nil}.

Here is an example of circular structure printing.  An error will still
be generated when @code{format} executes.

@example
(progn
  (edebug-install-custom-print-funcs)
  (setq a '(1 2))
  (format "%s" (setcar a a)))
@end example


@node Coverage Testing
@subsection Coverage Testing

@cindex coverage testing
@cindex frequency counts
@cindex performance analysis
Edebug provides a rudimentary coverage tester and frequency of execution
display.  Frequency counts are always accumulated, both before and after
evaluation of each instrumented expression, even if the execution mode
is Go-nonstop.  Coverage testing is only done if the option
@code{edebug-test-coverage} is non-@code{nil} because this is relatively
expensive.  Both data sets are displayed by
@code{edebug-display-freq-count}.

@defun edebug-display-freq-count
Display the frequency count data for each line of the current
definition.  The frequency counts are inserted as comment lines after
each line, and you can undo all insertions with one @code{undo} command.
The counts are inserted starting under the @kbd{(} before an expression
or the @kbd{)} after an expression, or on the last char of a symbol.
The counts are only displayed when they differ from previous counts on
the same line.

If coverage is being tested, whenever all known results of an expression
are @code{eq}, the char @kbd{=} will be appended after the count
for that expression.  Note that this is always the case for an
expression only evaluated once.

To clear the frequency count and coverage data for a definition,
reinstrument it.

@end defun

For example, after evaluating @code{(fac 5)} with a persistent
breakpoint, and setting @code{edebug-test-coverage} to @code{t}, the
frequency data is looks like this:

@example
(defun fac (n)
  (if (= n 0) (edebug))
;#6           1      0 =5 
  (if (< 0 n)
;#5         = 
      (* n (fac (1- n)))
;#    5               0  
    1))
;#   0 
@end example


@node The Outside Context
@subsection The Outside Context

Edebug tries to be transparent to the program you are debugging.  In
addition, most evaluations you do within Edebug (see @ref{Edebug Eval})
occur in the same outside context which is temporarily restored for the
evaluation.  But Edebug is not completely successful and this section
explains precisely how it fails.

@c It also tells how Edebug *does* succeed in being transparent, 
@c but perhaps those things should be removed.

@menu
* Just Checking::		When Edebug decides what to do.
* Outside Window Configuration::  When Edebug updates the display.
* Edebug Recursive Edit::	When Edebug stops execution.
* Side Effects::		How Edebug fails to be transparent.
@end menu

@node Just Checking
@subsubsection Just Checking

Whenever Edebug is entered just to think about whether to take some
action, it needs to save and restore certain data.

@itemize @bullet
@item 
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
incremented so that your code should not be impacted by Edebug frames on
the stack.

@item 
The state of keyboard macro execution is saved and cleared out.
@end itemize

@node Outside Window Configuration
@subsubsection Outside Window Configuration

When Edebug needs to display something (e.g., in trace mode), it saves
the current window configuration from ``outside'' Edebug.  When you exit
Edebug (by continuing the program), it restores the previous window
configuration.

XEmacs 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,
XEmacs never gets a chance to redisplay the ``outside'' configuration.
What you see is the window configuration for within Edebug, with no
interruption. 

Entry to Edebug for displaying something also saves and restores the
following data.  (Some of these variables are deliberately not restored
if an error or quit signal occurs.)

@itemize @bullet
@item 
@cindex current buffer point and mark
@cindex point in Edebug buffer
The window configuration proper does not include which buffer is current
or where point and mark are in the current buffer, but Edebug saves and
restores these also.  However, the position of point in the Edebug
buffer is only saved and restored if the outside current buffer is
the same as the Edebug buffer.

@item 
@cindex window configuration
@findex save-excursion
@vindex edebug-save-windows
@cindex window start of Edebug buffer
The outside window configuration, is saved and restored if
@code{edebug-save-windows} is non-@code{nil}.  It is not restored on
error or quit, but the outside selected window @i{is} reselected even on
error or quit in case a @code{save-excursion} is active.  The window
start for the Edebug buffer is not restored, however.

@item
The value of point in each displayed buffer is saved and restored if
@code{edebug-save-displayed-buffer-points} is non-@code{nil}.

@item
The variables @code{overlay-arrow-position} and
@code{overlay-arrow-string} are saved and restored.  This permits
recursive use of Edebug, and use of Edebug while using GUD.

@item 
@code{cursor-in-echo-area} is locally bound to @code{nil} so that
the cursor shows up in the window.
@end itemize

@node Edebug Recursive Edit
@subsubsection Edebug Recursive Edit

When Edebug is entered and actually reads commands from the user, it
saves (and later restores) these additional data:

@itemize @bullet
@item
The current match data, for whichever buffer was current.

@item
@code{last-command}, @code{this-command}, @code{last-command-char}, and
@code{last-input-char}.  Commands used within Edebug do not affect these
variables outside of Edebug.

But note that it is not possible to preserve the status reported by
@code{(this-command-keys)} and the variables @code{unread-command-char}
and @code{unread-command-event}.

@item
@code{standard-output} and @code{standard-input}.
@end itemize

@node Side Effects
@subsubsection Side Effects

Edebug operation unavoidably alters some data in XEmacs, and this
can interfere with debugging certain programs.

@itemize @bullet
@item
Lisp stack usage is increased, but the limits,
@code{max-lisp-eval-depth} and @code{max-specpdl-size}, are also
increased proportionally.

@item
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.

@item
Edebug cannot save and restore the value of @code{unread-command-char}
or @code{unread-command-event}.  Entering Edebug while these variables
have nontrivial values can interfere with execution of the program you
are debugging.

@item
Complex commands executed while in Edebug are added to the variable
@code{command-history}.  In rare cases this can alter execution.

@item
Within Edebug, the recursion depth appears one deeper than the recursion
depth outside Edebug.  This is not true of the automatically updated
evaluation list window.

@item
Horizontal scrolling of the Edebug buffer is not recovered.
@end itemize

@node Macro Calls
@subsection 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 may 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 macro call arguments by using @code{def-edebug-spec} to
define an @dfn{Edebug specification} for each macro.

@deffn Macro def-edebug-spec macro specification
Specify which parts of a call to macro @var{macro} are subexpressions to
be evaluated.  The second argument, @var{specification}, often looks like
the formal macro argument list, but it specifies the structure of the
macro call arguments.

The @var{macro} argument may be any symbol, not just a macro name, as
explained below.
@end deffn

Here is a table of the possibilities for @var{specification} and how each
directs processing of arguments.

@table @bullet

@item @code{t}
All arguments are instrumented for evaluation.

@item @code{0}
None of the arguments is instrumented.

@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.

@item a list
The elements of the list describe the types of the arguments of a
calling form.  The possible elements of a specification list are
described below.
@end table

@menu
* Specification List::		How to specify complex patterns of evaluation.
* Backtracking::		What Edebug does when matching fails.
* Specification Examples::  
@end menu

@node Specification List
@subsubsection Specification List

@cindex edebug specification list
A @dfn{specification list} is required if some arguments of a macro call
are evaluated while others are not.  Some specification elements in a
specification list match one or more arguments, but others modify the
processing of all following specification elements.  The latter, called
@dfn{special specifications}, are symbols beginning with @samp{@code{&}}
(e.g.  @code{&optional}).

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.  Special specifications only apply to the remainder of the
sublist or group they are contained in.  There is an implicit grouping
around each special specification and all following elements in the
sublist or group.

If a specification list fails
at some level, then backtracking may be invoked to find some alternative
at a higher level, or if no alternatives remain, an error will be
signaled.  See @ref{Backtracking} for more details.

@cindex regular expressions
Edebug specifications provide at least the power of regular expression
matching.  Additionally, some context free (i.e. finite state with
stack) constructs are supported: the matching of sublists with balanced
parentheses, recursive processing of forms, and indirect specifications.

Each element of a specification list may be one of the following, with
the corresponding type of argument:

@table @code

@item sexp
A single unevaluated expression.

@item form
A single evaluated expression, which is instrumented.

@item place
A place as in the Common Lisp @code{setf} place argument.  It will be
instrumented just like a form, but the macro is expected to strip the
instrumentation using @code{edebug-unwrap} or @code{edebug-unwrap*}.

@item body
Short for @code{&rest form}.  See @code{&rest} below.

@item function-form
A function form: a quoted function symbol, a quoted lambda expression,
or a form (that should evaluate to a function symbol or lambda
expression).  This is useful when function arguments might be quoted
with @code{quote} rather than @code{function} since the body of a lambda
expression will be instrumented either way.  See the @code{apply} example
below.

@item lambda-expr
An unquoted anonymous lambda expression.

@item &optional
@cindex &optional
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 one item optional, use @code{[&optional @var{spec}]}.  See the
@code{defun} example below.

@item &rest
@cindex &rest
All following elements in the specification list are repeated zero or
more times.  All the elements need not be used in the last repetition,
however.

To specify repetition of certain types of arguments, followed by
dissimilar arguments, use @code{[&rest @var{specs}@dots{}]}.
To specify all elements must match on the last repetition, use
@code{&rest [@var{specs}@dots{}]}.

@item &or
@cindex &or
Each of the following elements in the specification list is an
alternative, processed left to right until one matches.  One of the
alternatives must match otherwise the @code{&or} specification
fails.  To group two or more list elements as a single alternative,
enclose them in @code{[@dots{}]}.

@item &not
@cindex &not
Each of the following elements is matched as alternatives, and if any of
them match, the specification fails.  If none of them match, nothing is
matched, but the @code{&not} specification succeeds.  See the
@code{lambda-list} example below.

@item &define 
@cindex &define 
@cindex defining form 
Indicates that the specification is for a defining form.  The defining
form itself is not instrumented, but forms inside it may be.  The
@code{&define} keyword must appear first in a top-level list
specification.

Other specifications that may only appear after @code{&define} are
described here.  See the @code{defun} example below.

@table @code

@item name
The argument, a symbol, is the name of the defining form. 
But a defining form need not be named at all in which
case a unique name will be created for it.

The @code{name} specification may be used more than once in the
specification and each subsequent use will append the corresponding
symbol argument to the previous name with @samp{@code{@@}} between them.
This is useful for generating unique but meaningful names for
definitions such as @code{defadvice} and @code{defmethod}.

@item :name
The specification following @code{:name} is used as an additional name
component for the definition.  This is useful to add a unique component
to the definition name.  It may be used more than once, and it does not
affect matching of arguments.

@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{&}})
are not allowed.  See @code{lambda-list} and the example below.

@item lambda-list
@cindex lambda-list
This matches the whole argument list of an Emacs Lisp lambda
expression, which is a list of symbols and the keywords
@code{&optional} and @code{&rest}

@item def-body
The argument is the body of code in a definition.  This is like
@code{body}, described above, but a definition body must be instrumented
with a special Edebug call.  Use @code{def-body} for the highest level
list of forms within the definition.

@item def-form
The argument is a single top-level form in a definition.  This is 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.

@end table

@item nil
This is successful when there are no more arguments to match; otherwise
it fails.  See sublist specifications and the @code{backquote}
example below.

@item fence
No argument is matched but backtracking through the fence is disabled
while matching the remainder of the specifications at this level.  See
@ref{Backtracking} for more details.  Also see the @code{let} example
below.

@item @var{other-symbol}
Any other symbol in a specification list may be a predicate or an
indirect specification.

If the symbol has an Edebug specification, this @dfn{indirect
specification} should be a list that is used in-line.  The specification
may be defined with @code{def-edebug-spec} just as for macros. See the
@code{defun} example below.

Otherwise, the symbol should be a predicate.  The predicate is called
with the argument and the specification fails if the predicate fails.
The argument is not instrumented.

@findex keywordp
@findex lambda-list-keywordp
Predicates that may be used include: @code{symbolp}, @code{integerp},
@code{stringp}, @code{vectorp}, @code{atom} (which matches a number,
string, symbol, or vector), @code{keywordp}, and
@code{lambda-list-keywordp}.  The last two, defined in @file{edebug.el},
test whether the argument is a symbol starting with @samp{@code{:}} and
@samp{@code{&}} respectively.

@item [@var{elements}@dots{}]
@cindex [@dots{}]
Rather than matching a vector argument, a vector treats
the @var{elements} as a single @dfn{group specification}.

@item "@var{string}"
A symbol named @var{string}.

@item  '@var{symbol} @r{or} (quote @var{symbol})
The precise symbol @var{symbol}, treated as unevaluated.  Use a string
instead.

@item (vector @var{elements}@dots{})
A vector whose elements must match the @var{elements} in
the specification.  See the @code{backquote} example below.

@item (@var{elements}@dots{})
Any other list is a @dfn{sublist specification} and the argument must be
a list whose elements match the specification @var{elements}.

@cindex dotted lists
A sublist specification may be a dotted list and the corresponding list
argument may then be a dotted list.  Alternatively, the last cdr of a
dotted list specification may be another sublist specification
(via a grouping or an indirect specification) whose elements match the
non-dotted list arguments.  This is useful in recursive specifications
such as in the @code{backquote} example below.  Also see the description
of a @code{nil} specification above for terminating such recursion.

Note that a sublist specification that is printed like @code{(specs .
nil)} means the same as @code{(specs)}, and @code{(specs .
(sublist-elements@dots{}))} means the same as @code{(specs
sublist-elements@dots{})}.

@end table

@c document extensions with &symbol and :symbol

@node Backtracking
@subsubsection Backtracking

@cindex backtracking
@cindex syntax error
If a specification fails to match at some point, this does not
necessarily mean a syntax error will be signaled; instead,
@dfn{backtracking} will take place until all alternatives have been
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.

The special specifications @code{&optional}, @code{&rest}, or @code{&or}
establish alternatives.

Backtracking is disabled for the remainder of a sublist or group when
certain conditions occur, described below, and is reenabled when
another alternative is established.  You might want to disable
backtracking to commit to some alternative so that Edebug can provide
more specific syntax error messages.  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
@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
symbol or string specification.  If you have a set of alternative
constructs that all begin with the same symbol, you can usually work
around this limitation 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{fence} specification.  This is useful when you know that there
can be no higher alternatives.


@node Specification Examples
@subsubsection Specification Examples

This section provides several examples of Edebug specifications to show
most of its capabilities.

A @code{let} special form has a sequence of bindings and a body where
each of the bindings is a symbol or a sublist with a symbol and optional
value.  In the specification below notice the @code{fence} inside of the
sublist to prevent backtracking.

@example
(def-edebug-spec let
  ((&rest
    &or symbolp (fence symbolp &optional form))
   body))
@end example

@cindex Common Lisp
@pindex cl.el
@pindex cl-specs.el
Here are the specifications for the @code{case} and @code{do} macros in
@file{cl.el}.  (Specifications for @i{all} the macros defined by
@file{cl.el} (version 2.02) are in @file{cl-specs.el}.)

@example
(def-edebug-spec case (form &rest (sexp body)))

(def-edebug-spec do
 ((&rest &or symbolp (symbolp &optional form form))
  (form body) body))
@end example

Edebug uses the following specifications for @code{defun} and
@code{defmacro} and the associated argument list and @code{interactive}
specifications.  It is necessary to specially process the argument of an
interactive form to allow debugging of a list argument outside of the
function body, while not stopping on the interactive form itself.

@example
(def-edebug-spec defmacro defun)      ; @r{Indirect ref to @code{defun} spec}
(def-edebug-spec defun 
  (&define name lambda-list 
           [&optional stringp]        ; @r{Match the doc string, if present.}
           [&optional ("interactive" interactive)]
           def-body))

(def-edebug-spec lambda-list
  (([&rest arg]
    [&optional ["&optional" arg &rest arg]]
    &optional ["&rest" arg]
    )))

(def-edebug-spec interactive
  (&optional &or stringp def-form))    ; @r{Notice: @code{def-form}}
@end example

@findex `
@findex @code{backquote}
@findex ,
@findex ,@@
The @code{backquote} specification illustrates how to use @code{nil} to
terminate recursion.  Also a vector may be matched.

Note that backquote (@kbd{`}) is a macro that results in an expression
that is not necessarily evaluated.  It is often used to simplify the
definition of a macro where the result of the macro call is evaluated,
but Edebug does not know when this is the case.  So do not be surprised
when you cannot step through your backquoted code.
However, @code{,} and @code{,@@} forms within backquoted forms are
evaluated and Edebug instruments them.

Nested backquotes are supported to a limited extent.  Quoted forms are
not normally evaluated, but if the quoted form appears immediately
within @code{,} and @code{,@@} forms, Edebug treats this as a backquoted
form at the next higher level.

@example
(def-edebug-spec ` (backquote-form))

(def-edebug-spec backquote-form
  (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
       (backquote-form . [&or nil backquote-form])
       (vector &rest backquote-form)
       sexp))
@end example

@cindex @code{apply} specification
Finally, the standard functions @code{mapcar}, @code{mapconcat},
@code{mapatoms}, @code{apply}, and @code{funcall} all take function
arguments.  Here is one example:

@example
(def-edebug-spec apply (function-form &rest form))
@end example


@node Edebug Options
@subsection Edebug Options

These options affect the behavior of Edebug:


@defopt edebug-setup-hook
Functions to call before Edebug is used.  Each time it is set to a new
function, Edebug will call that function 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
only when you also use Edebug.
@end defopt

@defopt edebug-all-defs
If non-@code{nil}, normal evaluation of any defining forms (e.g.
@code{defun} and @code{defmacro}) will instrument them for Edebug.  This
applies to @code{eval-defun}, @code{eval-region}, and
@code{eval-current-buffer}.

Use the command @code{edebug-all-defs} to toggle the value of
this variable. You may want to make this variable local to each
buffer by calling @code{(make-local-variable 'edebug-all-defs)} in your
@code{emacs-lisp-mode-hook}.

The default value is @code{nil}.  
@end defopt

@defopt edebug-all-forms
If non-@code{nil}, normal evaluation of any forms by @code{eval-defun},
@code{eval-region}, and @code{eval-current-buffer} will instrument them
for Edebug.

Use the command @code{edebug-all-forms} to toggle the value of this
option.
@end defopt

@defopt edebug-save-windows
If non-@code{nil}, save and restore window configuration on Edebug calls.
It takes some time to save and restore, so if your program does not care
what happens to the window configurations, it is better to set this
variable to @code{nil}.
@end defopt


@defopt edebug-save-displayed-buffer-points
If non-@code{nil}, save and restore point in all displayed buffers.
This is necessary if you are debugging code that changes the point of a
buffer which is displayed in a non-selected window.  If Edebug or the
user then selects the window, the buffer's point will be changed to the
window's point.

This is an expensive operation since it visits each window and each
displayed buffer twice for each Edebug activation, so it is best to
avoid it if you can.
@end defopt


@defopt edebug-initial-mode
If this variable is non-@code{nil}, it specifies the initial execution
mode for Edebug when it is first activated.  Possible values are
@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}.  
@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.  You
can customize this display by replacing functions
@code{edebug-print-trace-before} and @code{edebug-print-trace-after}.

The default value is @code{nil}.  
@end defopt

@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 @code{edebug-display-freq-count} to display the frequency count and
coverage information for a definition.
@end defopt

@defopt edebug-continue-kbd-macro 
If non-@code{nil}, continue defining or executing any keyboard macro
that is executing outside of Edebug.
@end defopt

@defopt edebug-print-length
If non-@code{nil}, set @code{print-length} to this while printing results in
Edebug.  The default value is @code{50}. 
@end defopt

@defopt edebug-print-level 
If non-@code{nil}, set @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}, set @code{print-circle} to this while printing results in
Edebug.  The default value is @code{nil}.
@end defopt

