xemacs-beta: man/lispref/edebug-inc.texi comparison

comparison man/lispref/edebug-inc.texi @ 444:576fb035e263 r21-2-37

Import from CVS: tag r21-2-37

author	cvs
date	Mon, 13 Aug 2007 11:36:19 +0200
parents	3ecd8885ac67
children	755ae5b97edb

comparison

equal deleted inserted replaced

-:a8296e22da4e
+:576fb035e263
 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.
 @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)
 (* 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 to the top-level command loop.  Type @kbd{?} to display a list of
 all Edebug commands.
 @file{my-specs.el} may be loaded automatically when you use
 @code{my-package} with Edebug by including the following code in
 @file{my-package.el}.
 @example
 (add-hook 'edebug-setup-hook
 (function (lambda () (require 'my-specs))))
 @end example
 While Edebug is active, the command @kbd{I}
 (@code{edebug-instrument-callee}) instruments the definition of the
 program more slowly or stop sooner.
 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 @code{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.
 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}
 stop point.  If you want to execute one expression from the current stop
 point, type @kbd{w} first, to move point there.
 @item o
 Continue ``out of'' an expression (@code{edebug-step-out}).  It places a
 temporary breakpoint at the end of the sexp containing point.
 If the containing sexp is a function definition itself, it 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
 @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
 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.
 * Embedded Breakpoints::	Embedding breakpoints in code.
 @end menu
 @node Global Break Condition
 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}
 produce a traditional trace listing of execution in a separate buffer,
 @samp{*edebug-trace*}.
 @findex edebug-print-trace-before
 @findex edebug-print-trace-after
-If the variable @code{edebug-trace} is non-nil, each function entry and
+If the variable @code{edebug-trace} is non-@code{nil}, each function entry and
 exit adds lines to the trace buffer.  On function entry, Edebug prints
 @samp{::::@{} followed by the function name and argument values.  On
 function exit, Edebug prints @samp{::::@}} followed by the function name
 and result of the function.  The number of @samp{:}s is computed from
 the recursion depth.  The balanced braces in the trace buffer can be
 the breakpoint is reached, 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
 The comment lines show that @code{fac} has been called 6 times.  The
 first @code{if} statement has returned 5 times with the same result each
 time, and the same is true for the condition on the second @code{if}.
 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 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
 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 where point and mark are in the current
 buffer are saved and restored.
 @item
 @cindex window configuration (Edebug)
 @findex save-excursion (Edebug)
 @vindex edebug-save-windows
 The Edebug Display Update, 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 @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.
 @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
 @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
 (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
+@defmac 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.
 name.
 Unless you are using Emacs 19 or XEmacs, this macro is only defined
 in Edebug, so you may want to use the following which is equivalent:
 @code{(put '@var{macro} 'edebug-form-spec '@var{specification})}
-@end deffn
+@end defmac
 Here is a simple example that defines the specification for the
 @code{for} macro described in the XEmacs Lisp Reference Manual, followed
 by an alternative, equivalent specification.
 An unquoted anonymous lambda expression.
 @item &optional
 @cindex &optional (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 should all succeed together, use @code{&optional
 [@var{specs}@dots{}]}.  See the @code{defun} example below.
 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{&not} specification
 succeeds.
 @item &define
 @cindex &define (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
 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
 arguments bound to instrumented forms, then you should modify the
 specification for the macro as follows: the specifications for those
 arguments must use @code{def-form} instead of @code{form}.  (This is to
 reestablish the Edebugging context for those external forms.)
 For example, the @code{for} macro
 @c (@pxref{Problems with Macros}) @c in XEmacs Lisp Reference Manual
 (@pxref{Problems with Macros,,,, XEmacs Lisp Reference Manual}) @c Edebug Doc
 is shown here but with @code{edebug-`}
 substituted for regular @code{`}.
 interactive form specially since it is actually evaluated outside of the
 function body.
 @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
 calls.  It takes some time to do this, so if your program does not care
 what happens to data about windows, you may want to set this variable to
 @code{nil}.
 If the value is a list, only the listed windows are saved and
 restored.
 @kbd{M-x edebug-toggle-save-windows} may be used to change this variable.
 This command is bound to @kbd{W} in source code buffers.
 See @ref{Edebug Display Update}.
 @end defopt
 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}.
 See @ref{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}.
 See @ref{Tracing}.
 @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
 Use @kbd{M-x edebug-display-freq-count} to display the frequency count
 and coverage information for a definition.
 See @ref{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.
 See @ref{Edebug Execution Modes}.
 @end defopt
 If non-@code{nil}, bind @code{print-length} to this while printing
 results in Edebug.  The default value is @code{50}.
 See @ref{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
 See @ref{Debugging Backquote}.
 @end defopt
 @defopt edebug-global-break-condition
 If non-@code{nil}, an expression to test for at every stop point.
-If the result is non-nil, then break.  Errors are ignored.
+If the result is non-@code{nil}, then break.  Errors are ignored.
 See @ref{Global Break Condition}.
 @end defopt

Mercurial > hg > xemacs-beta

comparison man/lispref/edebug-inc.texi @ 444:576fb035e263 r21-2-37