diff options
Diffstat (limited to 'devdocs/elisp/internals-of-debugger.html')
| -rw-r--r-- | devdocs/elisp/internals-of-debugger.html | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/devdocs/elisp/internals-of-debugger.html b/devdocs/elisp/internals-of-debugger.html new file mode 100644 index 00000000..1f5112f9 --- /dev/null +++ b/devdocs/elisp/internals-of-debugger.html @@ -0,0 +1,81 @@ + <h4 class="subsection">Internals of the Debugger</h4> <p>This section describes functions and variables used internally by the debugger. </p> <dl> <dt id="debugger">Variable: <strong>debugger</strong> +</dt> <dd> +<p>The value of this variable is the function to call to invoke the debugger. Its value must be a function of any number of arguments, or, more typically, the name of a function. This function should invoke some kind of debugger. The default value of the variable is <code>debug</code>. </p> <p>The first argument that Lisp hands to the function indicates why it was called. The convention for arguments is detailed in the description of <code>debug</code> (see <a href="invoking-the-debugger">Invoking the Debugger</a>). </p> +</dd> +</dl> <dl> <dt id="backtrace">Function: <strong>backtrace</strong> +</dt> <dd> + <p>This function prints a trace of Lisp function calls currently active. The trace is identical to the one that <code>debug</code> would show in the <samp>*Backtrace*</samp> buffer. The return value is always nil. </p> <p>In the following example, a Lisp expression calls <code>backtrace</code> explicitly. This prints the backtrace to the stream <code>standard-output</code>, which, in this case, is the buffer ‘<samp>backtrace-output</samp>’. </p> <p>Each line of the backtrace represents one function call. The line shows the function followed by a list of the values of the function’s arguments if they are all known; if they are still being computed, the line consists of a list containing the function and its unevaluated arguments. Long lists or deeply nested structures may be elided. </p> <div class="example"> <pre class="example">(with-output-to-temp-buffer "backtrace-output" + (let ((var 1)) + (save-excursion + (setq var (eval '(progn + (1+ var) + (list 'testing (backtrace)))))))) + + ⇒ (testing nil) +</pre> + +<pre class="example">----------- Buffer: backtrace-output ------------ + backtrace() + (list 'testing (backtrace)) +</pre> +<pre class="example"> (progn ...) + eval((progn (1+ var) (list 'testing (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + eval((with-output-to-temp-buffer ...)) + eval-last-sexp-1(nil) +</pre> +<pre class="example"> eval-last-sexp(nil) + call-interactively(eval-last-sexp) +----------- Buffer: backtrace-output ------------ +</pre> +</div> </dd> +</dl> <dl> <dt id="debugger-stack-frame-as-list">User Option: <strong>debugger-stack-frame-as-list</strong> +</dt> <dd> +<p>If this variable is non-<code>nil</code>, 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. </p> <p>With <code>debugger-stack-frame-as-list</code> non-<code>nil</code>, the above example would look as follows: </p> <div class="example"> <pre class="example">----------- Buffer: backtrace-output ------------ + (backtrace) + (list 'testing (backtrace)) +</pre> +<pre class="example"> (progn ...) + (eval (progn (1+ var) (list 'testing (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + (eval (with-output-to-temp-buffer ...)) + (eval-last-sexp-1 nil) +</pre> +<pre class="example"> (eval-last-sexp nil) + (call-interactively eval-last-sexp) +----------- Buffer: backtrace-output ------------ +</pre> +</div> </dd> +</dl> <dl> <dt id="debug-on-next-call">Variable: <strong>debug-on-next-call</strong> +</dt> <dd> + <p>If this variable is non-<code>nil</code>, it says to call the debugger before the next <code>eval</code>, <code>apply</code> or <code>funcall</code>. Entering the debugger sets <code>debug-on-next-call</code> to <code>nil</code>. </p> <p>The <kbd>d</kbd> command in the debugger works by setting this variable. </p> +</dd> +</dl> <dl> <dt id="backtrace-debug">Function: <strong>backtrace-debug</strong> <em>level flag</em> +</dt> <dd> +<p>This function sets the debug-on-exit flag of the stack frame <var>level</var> levels down the stack, giving it the value <var>flag</var>. If <var>flag</var> is non-<code>nil</code>, this will cause the debugger to be entered when that frame later exits. Even a nonlocal exit through that frame will enter the debugger. </p> <p>This function is used only by the debugger. </p> +</dd> +</dl> <dl> <dt id="command-debug-status">Variable: <strong>command-debug-status</strong> +</dt> <dd> +<p>This variable records the debugging status of the current interactive command. Each time a command is called interactively, this variable is bound to <code>nil</code>. The debugger can set this variable to leave information for future debugger invocations during the same command invocation. </p> <p>The advantage of using this variable rather than an ordinary global variable is that the data will never carry over to a subsequent command invocation. </p> <p>This variable is obsolete and will be removed in future versions. </p> +</dd> +</dl> <dl> <dt id="backtrace-frame">Function: <strong>backtrace-frame</strong> <em>frame-number &optional base</em> +</dt> <dd> +<p>The function <code>backtrace-frame</code> is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame <var>frame-number</var> levels down. </p> <p>If that frame has not evaluated the arguments yet, or is a special form, the value is <code>(nil <var>function</var> <var>arg-forms</var>…)</code>. </p> <p>If that frame has evaluated its arguments and called its function already, the return value is <code>(t <var>function</var> +<var>arg-values</var>…)</code>. </p> <p>In the return value, <var>function</var> is whatever was supplied as the <small>CAR</small> of the evaluated list, or a <code>lambda</code> expression in the case of a macro call. If the function has a <code>&rest</code> argument, that is represented as the tail of the list <var>arg-values</var>. </p> <p>If <var>base</var> is specified, <var>frame-number</var> counts relative to the topmost frame whose <var>function</var> is <var>base</var>. </p> <p>If <var>frame-number</var> is out of range, <code>backtrace-frame</code> returns <code>nil</code>. </p> +</dd> +</dl> <dl> <dt id="mapbacktrace">Function: <strong>mapbacktrace</strong> <em>function &optional base</em> +</dt> <dd> +<p>The function <code>mapbacktrace</code> calls <var>function</var> once for each frame in the backtrace, starting at the first frame whose function is <var>base</var> (or from the top if <var>base</var> is omitted or <code>nil</code>). </p> <p><var>function</var> is called with four arguments: <var>evald</var>, <var>func</var>, <var>args</var>, and <var>flags</var>. </p> <p>If a frame has not evaluated its arguments yet or is a special form, <var>evald</var> is <code>nil</code> and <var>args</var> is a list of forms. </p> <p>If a frame has evaluated its arguments and called its function already, <var>evald</var> is <code>t</code> and <var>args</var> is a list of values. <var>flags</var> is a plist of properties of the current frame: currently, the only supported property is <code>:debug-on-exit</code>, which is <code>t</code> if the stack frame’s <code>debug-on-exit</code> flag is set. </p> +</dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Internals-of-Debugger.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Internals-of-Debugger.html</a> + </p> +</div> |