diff options
Diffstat (limited to 'doc/lispref/debugging.texi')
| -rw-r--r-- | doc/lispref/debugging.texi | 85 |
1 files changed, 84 insertions, 1 deletions
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 371934377a8..8fb663d2aee 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -69,6 +69,7 @@ debugger recursively. @xref{Recursive Editing}. * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * Function Debugging:: Entering it when a certain function is called. +* Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. * Using Debugger:: What the debugger does; what you see while in it. * Debugger Commands:: Commands used while in the debugger. @@ -290,6 +291,36 @@ Calling @code{cancel-debug-on-entry} does nothing to a function which is not currently set up to break on entry. @end deffn +@node Variable Debugging +@subsection Entering the debugger when a variable is modified +@cindex variable write debugging +@cindex debugging changes to variables + +Sometimes a problem with a function is due to a wrong setting of a +variable. Setting up the debugger to trigger whenever the variable is +changed is a quick way to find the origin of the setting. + +@deffn Command debug-on-variable-change variable +This function arranges for the debugger to be called whenever +@var{variable} is modified. + +It is implemented using the watchpoint mechanism, so it inherits the +same characteristics and limitations: all aliases of @var{variable} +will be watched together, only dynamic variables can be watched, and +changes to the objects referenced by variables are not detected. For +details, see @ref{Watching Variables}. +@end deffn + +@deffn Command cancel-debug-on-variable-change &optional variable +This function undoes the effect of @code{debug-on-variable-change} on +@var{variable}. When called interactively, it prompts for +@var{variable} in the minibuffer. If @var{variable} is omitted or +@code{nil}, it cancels break-on-change for all variables. Calling +@code{cancel-debug-on-variable-change} does nothing to a variable +which is not currently set up to break on change. +@end deffn + + @node Explicit Debug @subsection Explicit Entry to the Debugger @cindex debugger, explicit entry @@ -630,6 +661,37 @@ forms are elided. @end smallexample @end deffn +@defvar debugger-stack-frame-as-list +If this variable is non-@code{nil}, every stack frame of the backtrace +is displayed as a list. This aims at improving the backtrace +readability at the cost of special forms no longer being visually +different from regular function calls. + +With @code{debugger-stack-frame-as-list} non-@code{nil}, the above +example would look as follows: + +@smallexample +@group +----------- Buffer: backtrace-output ------------ + (backtrace) + (list ...computing arguments...) +@end group + (progn ...) + (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + (eval (with-output-to-temp-buffer ...)) + (eval-last-sexp-1 nil) +@group + (eval-last-sexp nil) + (call-interactively eval-last-sexp) +----------- Buffer: backtrace-output ------------ +@end group +@end smallexample +@end defvar + @defvar debug-on-next-call @cindex @code{eval}, and debugging @cindex @code{apply}, and debugging @@ -665,7 +727,7 @@ invocation. This variable is obsolete and will be removed in future versions. @end defvar -@defun backtrace-frame frame-number +@defun backtrace-frame frame-number &optional base The function @code{backtrace-frame} is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame @var{frame-number} levels down. @@ -682,10 +744,31 @@ In the return value, @var{function} is whatever was supplied as the case of a macro call. If the function has a @code{&rest} argument, that is represented as the tail of the list @var{arg-values}. +If @var{base} is specified, @var{frame-number} counts relative to +the topmost frame whose @var{function} is @var{base}. + If @var{frame-number} is out of range, @code{backtrace-frame} returns @code{nil}. @end defun +@defun mapbacktrace function &optional base +The function @code{mapbacktrace} calls @var{function} once for each +frame in the backtrace, starting at the first frame whose function is +@var{base} (or from the top if @var{base} is omitted or @code{nil}). + +@var{function} is called with four arguments: @var{evald}, @var{func}, +@var{args}, and @var{flags}. + +If a frame has not evaluated its arguments yet or is a special form, +@var{evald} is @code{nil} and @var{args} is a list of forms. + +If a frame has evaluated its arguments and called its function +already, @var{evald} is @code{t} and @var{args} is a list of values. +@var{flags} is a plist of properties of the current frame: currently, +the only supported property is @code{:debug-on-exit}, which is +@code{t} if the stack frame's @code{debug-on-exit} flag is set. +@end defun + @include edebug.texi @node Syntax Errors |