diff options
Diffstat (limited to 'lispref/edebug.texi')
| -rw-r--r-- | lispref/edebug.texi | 1545 |
1 files changed, 0 insertions, 1545 deletions
diff --git a/lispref/edebug.texi b/lispref/edebug.texi deleted file mode 100644 index 0f95fa9fb0c..00000000000 --- a/lispref/edebug.texi +++ /dev/null @@ -1,1545 +0,0 @@ -@comment -*-texinfo-*- - -@c This file is intended to be used as a section within the Emacs Lisp -@c Reference Manual. It may also be used by an independent Edebug User -@c Manual, edebug.tex, 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 - -@node Edebug,, Compilation Errors, Debugging -@section Edebug -@cindex Edebug mode - -@cindex Edebug - Edebug is a source-level debugger for Emacs Lisp programs with which -you can: - -@itemize @bullet -@item -Step through evaluation, stopping before and after each expression. - -@item -Set conditional or unconditional breakpoints. - -@item -Stop when a specified condition is true (the global break event). - -@item -Trace slow or fast, stopping briefly at each stop point, or -at each breakpoint. - -@item -Display expression results and evaluate expressions as if outside of -Edebug. - -@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 -Stop when an error occurs. - -@item -Display a backtrace, omitting Edebug's own frames. - -@item -Specify argument evaluation for macros and defining forms. - -@item -Obtain rudimentary coverage testing and frequency counts. -@end itemize - -The first three sections below should tell you enough about Edebug to -enable you to use it. - -@menu -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* 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. -* Trapping Errors:: trapping errors with Edebug. -* Views: Edebug Views. Views inside and outside of Edebug. -* Eval: Edebug Eval. Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* 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. -* Options: Edebug Options. Option variables for customizing Edebug. -@end menu - -@node Using Edebug -@subsection Using Edebug - - To debug a Lisp program with Edebug, you must first @dfn{instrument} -the Lisp code that you want to debug. A simple way to do this is to -first move point into the definition of a function or macro and then do -@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See -@ref{Instrumenting}, for alternative ways to instrument code. - - Once a function is instrumented, any call to the function activates -Edebug. Activating Edebug may stop execution and let you step through -the function, or it may update the display and continue execution while -checking for debugging commands, depending on which Edebug execution -mode you have selected. The default execution mode is step, which does -stop execution. @xref{Edebug Execution Modes}. - - Within Edebug, you normally view an Emacs buffer showing the source of -the Lisp code you are debugging. This is referred to as the @dfn{source -code buffer}. This buffer is temporarily read-only. - - An arrow at the left margin indicates the line where the function is -executing. Point initially shows where within the line the function is -executing, but this ceases to be true if you move point yourself. - - If you instrument the definition of @code{fac} (shown below) and then -execute @code{(fac 3)}, here is what you normally see. Point is at the -open-parenthesis before @code{if}. - -@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. -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 - -The special commands of Edebug are available in the source code buffer -in addition to the commands of Emacs Lisp mode. 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 -display you will see: - -@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. - -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 -exit Edebug and return to the top-level command loop. Type @kbd{?} to -display a list of all Edebug commands. - -@node Instrumenting -@subsection Instrumenting for Edebug - - In order to use Edebug to debug Lisp code, you must first -@dfn{instrument} the code. Instrumenting code inserts additional code -into it, to invoke Edebug at the proper places. - -@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: 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 -@findex eval-region (Edebug) -@findex eval-current-buffer (Edebug) - If @code{edebug-all-defs} is non-@code{nil}, then the commands -@code{eval-region}, @code{eval-current-buffer}, and @code{eval-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. This doesn't apply -to loading or evaluations in the minibuffer. 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} or @code{edebug-all-forms}. - -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 up Edebug specifications associated with a -package you are using, but only when you also use Edebug. - -While Edebug is active, the command @kbd{I} -(@code{edebug-instrument-callee}) instruments the definition of the -function or macro called by the list form after point, if is not already -instrumented. This is possible only if Edebug knows where to find the -source for that function; after loading Edebug, @code{eval-region} -records the position of every definition it evaluates, even if not -instrumenting it. See also the @kbd{i} command (@pxref{Jumping}), which -steps into the call after instrumenting the function. - -@cindex special forms (Edebug) -@cindex interactive commands (Edebug) -@cindex anonymous lambda expressions (Edebug) -@cindex Common Lisp (Edebug) -@pindex cl.el (Edebug) -@pindex cl-specs.el - Edebug knows how to instrument all the standard special forms, an -interactive form with an expression argument, anonymous lambda -expressions, and other defining forms. Edebug cannot know what a -user-defined macro will do with the arguments of a macro call, so you -must tell it; @xref{Instrumenting Macro Calls}, for details. - -@findex eval-expression (Edebug) - To remove instrumentation from a definition, simply reevaluate its -definition in a way that does not instrument. There are two ways of -evaluating forms that never instrument them: from a file with -@code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-:}). - - If Edebug detects a syntax error while instrumenting, it leaves point -at the erroneous code and signals an @code{invalid-read-syntax} error. - - @xref{Edebug Eval}, for 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 or minor modes. The current Edebug execution mode -determines how far Edebug continues execution before stopping---whether -it stops at each stop point, or continues to the next breakpoint, for -example---and how much Edebug displays the progress of the evaluation -before it stops. - -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 -(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in -@ref{Edebug Misc}. - -@item t -Trace: pause 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 -pause (@code{edebug-Trace-fast-mode}). - -@item g -Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. - -@item c -Continue: pause one second at each breakpoint, and then continue -(@code{edebug-continue-mode}). - -@item C -Rapid continue: move point to each breakpoint, but don't pause -(@code{edebug-Continue-fast-mode}). - -@item G -Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You -can still stop the program by typing @kbd{S}, or any editing command. -@end table - -In general, the execution modes earlier in the above list run the -program more slowly or stop sooner than the modes later in the list. - -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 you typed. For example, typing @kbd{t} during -execution switches to trace mode at the next stop point. You can use -@kbd{S} to stop execution without doing anything else. - -If your function happens to read input, a character you type 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. - -@cindex keyboard macros (Edebug) -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. Also, defining or -executing a keyboard macro outside of Edebug does not affect commands -inside Edebug. This is usually an advantage. But see 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. - - -@node Jumping -@subsection Jumping - - The commands described in this section execute until they reach a -specified location. All except @kbd{i} make a temporary breakpoint to -establish the place to stop, then switch to go mode. Any other -breakpoint reached before the intended stop point will also stop -execution. @xref{Breakpoints}, for the details on breakpoints. - - These commands may fail to work as expected in case of nonlocal exit, -because a nonlocal exit can bypass the temporary breakpoint where you -expected the program to stop. - -@table @kbd -@item h -Proceed to the stop point near where point is (@code{edebug-goto-here}). - -@item f -Run the program forward over one expression -(@code{edebug-forward-sexp}). - -@item o -Run the program until the end of the containing sexp. - -@item i -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 -if point, using a temporary breakpoint. See @ref{Breakpoints}, for more -about breakpoints. - -The @kbd{f} command runs the program forward over one expression. More -precisely, it sets a temporary breakpoint at the position that -@kbd{C-M-f} would reach, then executes in 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{cond}, for example. - -The @kbd{f} command does @code{forward-sexp} starting at point, rather -than at the stop point, for flexibility. If you want to execute one -expression @emph{from the current stop point}, type @kbd{w} first, to -move point there, and then type @kbd{f}. - -The @kbd{o} command continues ``out of'' an expression. It places a -temporary breakpoint at the end of the sexp containing point. If the -containing sexp is a function definition itself, @kbd{o} continues until -just before the last sexp in the definition. 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 function unless you are -positioned after the last sexp. - -The @kbd{i} command steps into the function or macro called by the list -form after point, and stops at its first stop point. Note that the form -need not be the one about to be evaluated. But if the form is a -function call about to be evaluated, remember to use this command before -any of the arguments are evaluated, since otherwise it will be too late. - -The @kbd{i} command instruments the function or macro it's supposed to -step into, if it isn't instrumented already. This is convenient, but keep -in mind that the function or macro remains instrumented unless you explicitly -arrange to deinstrument it. - -@node Edebug Misc -@subsection Miscellaneous Edebug Commands - - Some miscellaneous Edebug 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 (@code{top-level}). 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. - -@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 -(@code{edebug-backtrace}). - -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 -pending evaluations with @kbd{d}. - -@node Breakpoints -@subsection Breakpoints - -@cindex breakpoints -Edebug's step mode stops execution at the next stop point reached. -There are three other ways to stop Edebug execution once it has started: -breakpoints, the global break condition, and source breakpoints. - -While using Edebug, you can specify @dfn{breakpoints} in the program you -are testing: points where execution should stop. You can set a -breakpoint at any stop point, as defined in @ref{Using Edebug}. For -setting and unsetting breakpoints, the stop point that is affected is -the first one at or after point in the source code buffer. Here are the -Edebug commands for breakpoints: - -@table @kbd -@item b -Set a breakpoint at the stop point at or after point -(@code{edebug-set-breakpoint}). If you use a prefix argument, the -breakpoint is temporary (it turns off the first time it stops the -program). - -@item u -Unset the breakpoint (if any) at the stop point at or after -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 -(@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 -(@code{edebug-next-breakpoint}). -@end table - -While in Edebug, you can set a breakpoint with @kbd{b} and unset one -with @kbd{u}. First move point to the Edebug stop point of your choice, -then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. -Unsetting a breakpoint where none has been set has no effect. - -Reevaluating or reinstrumenting a definition forgets all its breakpoints. - -A @dfn{conditional breakpoint} tests a condition each time the program -gets there. Any errors that occur as a result of evaluating the -condition are ignored, as if the result were @code{nil}. To set a -conditional breakpoint, use @kbd{x}, and specify the condition -expression in the minibuffer. Setting a conditional breakpoint at a -stop point that has a previously established conditional breakpoint puts -the previous condition expression in the minibuffer so you can edit it. - -You can make a conditional or unconditional breakpoint -@dfn{temporary} by using a prefix arg with the command to set the -breakpoint. When a temporary breakpoint stops the program, it is -automatically unset. - -Edebug always stops or pauses at a breakpoint except when the Edebug -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 following point, within the same -function, 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. -* Source Breakpoints:: Embedding breakpoints in source code. -@end menu - - -@node Global Break Condition -@subsubsection Global Break Condition - -@cindex stopping on events -@cindex global break condition - A @dfn{global break condition} stops execution when a specified -condition is satisfied, no matter where that may occur. Edebug -evaluates the global break condition at every stop point. If it -evaluates to a non-@code{nil} value, then execution stops or pauses -depending on the execution mode, as if a breakpoint had been hit. If -evaluating the condition gets an error, execution does not stop. - -@findex edebug-set-global-break-condition -@vindex edebug-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}). - - 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 -should reset the condition to @code{nil} when not using it. - -@node Source Breakpoints -@subsubsection Source Breakpoints - -@findex edebug -@cindex source breakpoints - All breakpoints in a definition are forgotten each time you -reinstrument it. To make a breakpoint that won't be forgotten, you can -write a @dfn{source breakpoint}, which is simply a call to the function -@code{edebug} in your source code. You can, of course, make such a call -conditional. For example, in the @code{fac} function, insert the first -line as shown below to stop when the argument reaches zero: - -@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, the call to @code{edebug} acts as a breakpoint. Depending on -the execution mode, Edebug stops or pauses there. - -If no instrumented code is being executed when @code{edebug} is called, -that function calls @code{debug}. -@c This may not be a good idea anymore. - -@node Trapping Errors -@subsection Trapping Errors - -Emacs normally displays an error message when an error is signaled and -not handled with @code{condition-case}. While Edebug is active, it -normally responds to all unhandled errors. You can customize this with -the options @code{edebug-on-error} and @code{edebug-on-quit}; see -@ref{Edebug Options}. - -When Edebug responds to an error, it shows the last stop point -encountered before the error. This may be the location of a call to a -function which was not instrumented, within which the error actually -occurred. For an unbound variable error, the last known stop point -might be quite distant from the offending variable reference. In that -case you might want to display a full backtrace (@pxref{Edebug Misc}). - -@c Edebug should be changed for the following: -- dan -If you change @code{debug-on-error} or @code{debug-on-quit} while -Edebug is active, these changes will be forgotten when Edebug becomes -inactive. Furthermore, during Edebug's recursive edit, these variables -are bound to the values they had outside of Edebug. - -@node Edebug Views -@subsection Edebug Views - -These Edebug commands let you view aspects of the buffer and window -status that obtained before entry to Edebug. The outside window -configuration is the collection of windows and contents that were in -effect outside of Edebug. - -@table @kbd -@item v -Temporarily view the outside window configuration -(@code{edebug-view-outside}). - -@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. - -@item w -Move point back to the current stop point (@code{edebug-where}) in the -source code buffer. Also, if you use this command in a different window -displaying the same buffer, that window will be used instead to display -the current definition in the future. - -@item W -@c Its function is not simply to forget the saved configuration -- dan -Toggle whether Edebug saves and restores the outside window -configuration (@code{edebug-toggle-save-windows}). - -With a prefix argument, @code{W} only toggles saving and restoring of -the selected window. To specify a window that is not displaying the -source code buffer, you must use @kbd{C-x X W} from the global keymap. -@end table - -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. - -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 -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 -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. Evaluation of expressions that cause side -effects will work as expected except for things that Edebug explicitly -saves and restores. @xref{The Outside Context}, for details on this -process. - -@table @kbd -@item e @var{exp} @key{RET} -Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. - -@item M-: @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 - -@cindex lexical binding (Edebug) -Edebug supports evaluation of expressions containing references to -lexically bound symbols created by the following constructs in -@file{cl.el} (version 2.03 or later): @code{lexical-let}, -@code{macrolet}, and @code{symbol-macrolet}. - - -@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 mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs -Manual}) as well as these special commands: - -@table @kbd -@item LFD -Evaluate the expression before point, in the outside context, 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 contents of the buffer -(@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 source code 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. - -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. - -@cindex evaluation list group -To do this, write one or more @dfn{evaluation list groups} in the -evaluation list buffer. An evaluation list group consists of one or -more Lisp expressions. Groups are separated by comment lines. - -The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the -evaluation list, scanning the buffer and using the first expression of -each group. (The idea is that the second expression of the group is the -value previously computed and displayed.) - -Be careful not to add expressions that execute instrumented code since -that would cause an infinite loop. -@c There ought to be a way to fix this. - -Each entry to Edebug redisplays the evaluation list by inserting each -expression in the buffer, followed by its current value. It also -inserts comment lines so that each expression becomes its own group. -Thus, if you type @kbd{C-c C-u} again without changing the buffer text, -the evaluation list is effectively unchanged. - -If an error occurs during an evaluation from the evaluation list, the -error message is displayed in a string as if it were the result. -Therefore, expressions that use variables not currently valid 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}. To add a new expression to the evaluation list, insert -the expression at a suitable place, and insert a new comment line. (You -need not insert dashes in the comment line---its contents don't matter.) -Then type @kbd{C-c C-u}. - -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 -you continue execution, and recreated next time it is needed. - - -@node Printing in Edebug -@subsection Printing in Edebug - -@cindex printing (Edebug) -@cindex printing circular structures -@pindex cust-print - If an expression in your program produces a value containing circular -list structure, you may get an error when Edebug attempts to print it. - -@vindex edebug-print-length -@vindex edebug-print-level - One way to cope with circular structure is to set @code{print-length} -or @code{print-level} to truncate the printing. Edebug does this for -you; it binds @code{print-length} and @code{print-level} to 50 if they -were @code{nil}. (Actually, the variables @code{edebug-print-length} -and @code{edebug-print-level} specify the values to use within Edebug.) -@xref{Output Variables}. - - You can also print circular structures and structures that share -elements more informatively by using the @file{cust-print} package. - - To load @file{cust-print} and activate custom printing only for -Edebug, simply use the command @kbd{M-x edebug-install-custom-print}. -To restore the standard print functions, use @kbd{M-x -edebug-uninstall-custom-print}. - - Here is an example of code that creates a circular structure: - -@example -(setq a '(x y)) -(setcar a a)) -@end example - -@noindent -Custom printing prints this as @samp{Result: #1=(#1# y)}. The -@samp{#1=} notation labels the structure that follows it with the label -@samp{1}, and the @samp{#1#} notation references the previously labelled -structure. This notation is used for any shared elements of lists or -vectors. - - Other programs can also use custom printing; see @file{cust-print.el} -for details. - -@node Trace Buffer -@subsection Trace Buffer -@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, -showing the function names and their arguments and values. To enable -trace recording, set @code{edebug-trace} to a non-@code{nil} value. - - Making a trace buffer is not the same thing as using trace execution -mode (@pxref{Edebug Execution Modes}). - - When trace recording is enabled, each function entry and exit adds -lines to the trace buffer. A function entry record looks like -@samp{::::@{} followed by the function name and argument values. A -function exit record looks like @samp{::::@}} followed by the function -name and result of the function. - - The number of @samp{:}s in an entry shows its recursion depth. You -can use the braces in the trace buffer to find the matching beginning or -end of function calls. - -@findex edebug-print-trace-before -@findex edebug-print-trace-after - You can customize trace recording for function entry and exit by -redefining the functions @code{edebug-print-trace-before} and -@code{edebug-print-trace-after}. - -@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. -@code{edebug-tracing} returns the value of the last form in @var{body}. -@end defmac - -@defun edebug-trace format-string &rest format-args -This function inserts text in the trace buffer. It computes the text -with @code{(apply 'format @var{format-string} @var{format-args})}. -It also appends a newline to separate entries. -@end defun - - @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace -buffer even if Edebug is not active. - - Adding text to the trace buffer also scrolls its window to show the -last lines inserted. - -@node Coverage Testing -@subsection Coverage Testing - -@cindex coverage testing -@cindex frequency counts -@cindex performance analysis -Edebug provides rudimentary coverage testing and display of execution -frequency. All execution of an instrumented function accumulates -frequency counts, both before and after evaluation of each instrumented -expression, even if the execution mode is Go-nonstop. Coverage testing -is more expensive, so it is only done if @code{edebug-test-coverage} is -non-@code{nil}. The command @kbd{M-x edebug-display-freq-count} -displays both the frequency data and the coverage data (if recorded). - -@deffn Command edebug-display-freq-count -This command displays the frequency count data for each line of the -current definition. - -The frequency counts appear as comment lines after each line of code, and -you can undo all insertions with one @code{undo} command. The counts -appear under the @kbd{(} before an expression or the @kbd{)} after -an expression, or on the last character of a symbol. Values do not appear if -they are equal to the previous count on the same line. - -The character @samp{=} following the count for an expression says that -the expression has returned the same value each time it was evaluated -This is the only coverage information that Edebug records. - -To clear the frequency count and coverage data for a definition, -reinstrument it. -@end deffn - -For example, after evaluating @code{(fac 5)} with a source -breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when -the breakpoint is reached, the frequency data 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 - -The comment lines show that @code{fac} was called 6 times. The -first @code{if} statement returned 5 times with the same result each -time; the same is true of the condition on the second @code{if}. -The recursive call of @code{fac} did not return at all. - - -@node The Outside Context -@subsection The Outside Context - -Edebug tries to be transparent to the program you are debugging, but it -does not succeed completely. Edebug also tries to be transparent when -you evaluate expressions with @kbd{e} or with the evaluation list -buffer, by temporarily restoring the outside context. This section -explains precisely what context Edebug restores, and how Edebug fails to -be completely transparent. - -@menu -* Checking Whether to Stop:: When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. -@end menu - -@node Checking Whether to Stop -@subsubsection Checking Whether to Stop - -Whenever Edebug is entered, it needs to save and restore certain data -before even deciding whether to make trace information or stop the -program. - -@itemize @bullet -@item -@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both -incremented one time to reduce Edebug's impact on the stack. -You could, however, still run out of stack space when using Edebug. - -@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}. - -@end itemize - - -@node Edebug Display Update -@subsubsection Edebug Display Update - -@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 -(@pxref{Window Configurations}). When you exit Edebug (by continuing -the program), it restores the previous window configuration. - -Emacs redisplays only when it pauses. Usually, when you continue -execution, the program comes back into Edebug at a breakpoint or after -stepping without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. -What you see is the same window configuration as the last time Edebug -was active, with no interruption. - -Entry to Edebug for displaying something also saves and restores the -following data, but some of these are deliberately not restored if an -error or quit signal occurs. - -@itemize @bullet -@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 -@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}). - -The window configuration is not restored on error or quit, but the -outside selected window @emph{is} reselected even on error or quit in -case a @code{save-excursion} is active. If the value of -@code{edebug-save-windows} is a list, only the listed windows are saved -and restored. - -The window start and horizontal scrolling of the source code buffer are -not restored, however, so that the display remains coherent within Edebug. - -@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. So you can safely -invoke Edebug from the recursive edit elsewhere in the same buffer. - -@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. @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 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. - -Edebug cannot save and restore the value of -@code{unread-command-events}. Entering Edebug while this variable has a -nontrivial value 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 -@code{standard-output} and @code{standard-input} are bound to @code{nil} -by the @code{recursive-edit}, but Edebug temporarily restores them during -evaluations. - -@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}. -@end itemize - -@node Instrumenting Macro Calls -@subsection Instrumenting 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 are forms to 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 calls to each macro to enable Edebug to handle it. -To do this, use @code{def-edebug-spec} to define the format of -calls to a given macro. - -@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. - -The @var{macro} argument may actually be any symbol, not just a macro -name. -@end deffn - -Here is a simple example that defines the specification for the -@code{for} macro described in the Emacs Lisp Reference Manual, 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. - -@table @asis -@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 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 - - -@node Specification List -@subsubsection Specification List - -@cindex Edebug specification list -A @dfn{specification list} is required for an Edebug specification if -some arguments of a macro call are evaluated while others are not. Some -elements in a specification list match one or more arguments, but others -modify the processing of all following elements. The latter, called -@dfn{specification keywords}, are symbols beginning with @samp{&} (such -as @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. Specification keywords only apply to the remainder of the -sublist or group they are contained in. - -When a specification list involves alternatives or repetition, matching -it against an actual macro call may require backtracking. -@xref{Backtracking}, for more details. - -Edebug specifications provide the power of regular expression matching, -plus some context-free grammar constructs: the matching of sublists with -balanced parentheses, recursive processing of forms, and recursion via -indirect specifications. - -Here's a table of the possible elements of a specification list, with -their meanings: - -@table @code -@item sexp -A single Lisp object, not unevaluated. -@c "unevaluated expression" is not meaningful, because -@c an expression is a Lisp object intended for evaluation. - -@item form -A single evaluated expression, which is instrumented. - -@item place -@findex edebug-unwrap -A place to store a value, as in the Common Lisp @code{setf} construct. - -@item body -Short for @code{&rest form}. See @code{&rest} below. - -@item function-form -A function form: either 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 an argument that's a lambda -expression might be quoted with @code{quote} rather than -@code{function}, since it instruments the body of the lambda expression -either way. - -@item lambda-expr -A lambda expression with no quoting. - -@item &optional -@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. - -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. - -@item &rest -@kindex &rest @r{(Edebug)} -All following elements in the specification list are repeated zero or -more times. All the elements need not match in the last repetition, -however. - -To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. -To specify several elements that must all match on every repetition, use -@code{&rest [@var{specs}@dots{}]}. - -@item &or -@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. - -Each list element following @code{&or} is a single alternative. To -group two or more list elements as a single alternative, enclose them in -@code{[@dots{}]}. - -@item ¬ -@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)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (i.e. Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. - -@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. - -@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. - -@item @var{other-symbol} -@cindex indirect specifications -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 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. - -Otherwise, the symbol should be a predicate. The predicate is called -with the argument and the specification fails if the predicate returns -@code{nil}. In either case, that argument is not instrumented. - -Some suitable predicates include @code{symbolp}, @code{integerp}, -@code{stringp}, @code{vectorp}, and @code{atom}. - -@item [@var{elements}@dots{}] -@cindex [@dots{}] (Edebug) -A vector of elements groups the elements into a single @dfn{group -specification}. Its meaning has nothing to do with vectors. - -@item "@var{string}" -The argument should be a symbol named @var{string}. This specification -is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name -of @var{symbol} is the @var{string}, but the string form is preferred. - -@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. - -@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 (Edebug) -A sublist specification may be a dotted list and the corresponding list -argument may then be a dotted list. Alternatively, the last @sc{cdr} of a -dotted list specification may be another sublist specification (via a -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 -above for terminating such recursion. - -Note that a sublist specification written as @code{(specs . nil)} -is equivalent to @code{(specs)}, and @code{(specs . -(sublist-elements@dots{}))} is equivalent to @code{(specs -sublist-elements@dots{})}. -@end table - -@c Need to document extensions with &symbol and :symbol - -Here is a list of additional specifications that may only appear after -@code{&define}. See the @code{defun} example below. - -@table @code -@item name -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. - -@item :name -This construct does not actually match an argument. The element -following @code{:name} should be a symbol; it is used as an additional -name component for the definition. You can use this to add a unique, -static component to the name of the definition. It may be used more -than once. - -@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. - -@item lambda-list -@cindex lambda-list (Edebug) -This matches a lambda list---the argument list of a lambda expression. - -@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 different Edebug call that looks up information associated with -the definition. Use @code{def-body} for the highest level list of forms -within the definition. - -@item def-form -The argument is a single, highest-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 - -@node Backtracking -@subsubsection Backtracking - -@cindex backtracking -@cindex syntax error (Edebug) -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. - -Backtracking is disabled for the remainder of a sublist or group when -certain conditions occur, described below. Backtracking is reenabled -when a new alternative is established by @code{&optional}, @code{&rest}, -or @code{&or}. It is also reenabled initially when processing a -sublist or group specification or an indirect specification. - -You might want to disable backtracking to commit to some alternative so -that Edebug can provide a more specific syntax error message. 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, since this usually indicates a -recognized construct. If you have a set of alternative constructs that -all begin with the same symbol, you can usually work around this -constraint 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{gate} specification. This is useful when you know that -no higher alternatives may apply. - -@node Specification Examples -@subsubsection Specification Examples - -It may be easier to understand Edebug specifications by studying -the examples provided here. - -A @code{let} special form has a sequence of bindings and a body. Each -of the bindings is either a symbol or a sublist with a symbol and -optional value. In the specification below, notice the @code{gate} -inside of the sublist to prevent backtracking once a sublist is found. - -@example -(def-edebug-spec let - ((&rest - &or symbolp (gate symbolp &optional form)) - 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 handle interactive forms specially -since an expression argument it is actually evaluated outside of the -function body. - -@smallexample -(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 smallexample - -The specification for backquote below illustrates how to match -dotted lists and use @code{nil} to terminate recursion. It also -illustrates how components of a vector may be matched. (The actual -specification defined by Edebug does not support dotted lists because -doing so causes very deep recursion that could fail.) - -@smallexample -(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.} - -(def-edebug-spec backquote-form - (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) -@end smallexample - - -@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 -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 -but only when you also use Edebug. -@xref{Instrumenting}. -@end defopt - -@defopt edebug-all-defs -If this is non-@code{nil}, normal evaluation of defining forms such as -@code{defun} and @code{defmacro} instruments them for Edebug. This -applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, -and @code{eval-current-buffer}. - -Use the command @kbd{M-x edebug-all-defs} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-all-forms -If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. - -Use the command @kbd{M-x edebug-all-forms} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-save-windows -If this is non-@code{nil}, Edebug saves and restores the window -configuration. That takes some time, so if your program does not care -what happens to the window configurations, it is better to set this -variable to @code{nil}. - -If the value is a list, only the listed windows are saved and -restored. - -You can use the @kbd{W} command in Edebug to change this variable -interactively. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-save-displayed-buffer-points -If this is non-@code{nil}, Edebug saves and restores point in all -displayed buffers. - -Saving and restoring point in other buffers 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, -point in that buffer will move to the window's value of point. - -Saving and restoring point in all buffers is expensive, since it -requires selecting each window twice, so enable this only if you need -it. @xref{Edebug Display Update}. -@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}. -@xref{Edebug Execution Modes}. -@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. - -The default value is @code{nil}. - -Also see @code{edebug-tracing}, in @xref{Trace Buffer}. -@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 @kbd{M-x edebug-display-freq-count} to display the frequency count -and coverage information for a definition. -@xref{Coverage Testing}. -@end defopt - -@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. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-print-length -If non-@code{nil}, bind @code{print-length} to this while printing -results in Edebug. The default value is @code{50}. -@xref{Printing in Edebug}. -@end defopt - -@defopt edebug-print-level -If non-@code{nil}, bind @code{print-level} to this while printing -results in Edebug. The default value is @code{50}. -@end defopt - -@defopt edebug-print-circle -If non-@code{nil}, bind @code{print-circle} to this while printing -results in Edebug. The default value is @code{nil}. -@end defopt - -@defopt edebug-on-error -Edebug binds @code{debug-on-error} to this value, if -@code{debug-on-error} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - -@defopt edebug-on-quit -Edebug binds @code{debug-on-quit} to this value, if -@code{debug-on-quit} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - - If you change the values of @code{edebug-on-error} or -@code{edebug-on-quit} while Edebug is active, their values won't be used -until the @emph{next} time Edebug is invoked via a new command. -@c Not necessarily a deeper command level. -@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. -@xref{Global Break Condition}. -@end defopt |