diff options
Diffstat (limited to 'devdocs/elisp/invoking-the-debugger.html')
| -rw-r--r-- | devdocs/elisp/invoking-the-debugger.html | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/devdocs/elisp/invoking-the-debugger.html b/devdocs/elisp/invoking-the-debugger.html new file mode 100644 index 00000000..5da1a918 --- /dev/null +++ b/devdocs/elisp/invoking-the-debugger.html @@ -0,0 +1,24 @@ + <h4 class="subsection">Invoking the Debugger</h4> <p>Here we describe in full detail the function <code>debug</code> that is used to invoke the debugger. </p> <dl> <dt id="debug">Command: <strong>debug</strong> <em>&rest debugger-args</em> +</dt> <dd> +<p>This function enters the debugger. It switches buffers to a buffer named <samp>*Backtrace*</samp> (or <samp>*Backtrace*<2></samp> if it is the second recursive entry to the debugger, etc.), and fills it with information about the stack of Lisp function calls. It then enters a recursive edit, showing the backtrace buffer in Debugger mode. </p> <p>The Debugger mode <kbd>c</kbd>, <kbd>d</kbd>, <kbd>j</kbd>, and <kbd>r</kbd> commands exit the recursive edit; then <code>debug</code> switches back to the previous buffer and returns to whatever called <code>debug</code>. This is the only way the function <code>debug</code> can return to its caller. </p> <p>The use of the <var>debugger-args</var> is that <code>debug</code> displays the rest of its arguments at the top of the <samp>*Backtrace*</samp> buffer, so that the user can see them. Except as described below, this is the <em>only</em> way these arguments are used. </p> <p>However, certain values for first argument to <code>debug</code> have a special significance. (Normally, these values are used only by the internals of Emacs, and not by programmers calling <code>debug</code>.) Here is a table of these special values: </p> <dl compact> <dt><code>lambda</code></dt> <dd> + <p>A first argument of <code>lambda</code> means <code>debug</code> was called because of entry to a function when <code>debug-on-next-call</code> was non-<code>nil</code>. The debugger displays ‘<samp>Debugger entered--entering a function:</samp>’ as a line of text at the top of the buffer. </p> </dd> <dt><code>debug</code></dt> <dd> +<p><code>debug</code> as first argument means <code>debug</code> was called because of entry to a function that was set to debug on entry. The debugger displays the string ‘<samp>Debugger entered--entering a function:</samp>’, just as in the <code>lambda</code> case. It also marks the stack frame for that function so that it will invoke the debugger when exited. </p> </dd> <dt><code>t</code></dt> <dd> +<p>When the first argument is <code>t</code>, this indicates a call to <code>debug</code> due to evaluation of a function call form when <code>debug-on-next-call</code> is non-<code>nil</code>. The debugger displays ‘<samp>Debugger entered--beginning evaluation of function call form:</samp>’ as the top line in the buffer. </p> </dd> <dt><code>exit</code></dt> <dd> +<p>When the first argument is <code>exit</code>, it indicates the exit of a stack frame previously marked to invoke the debugger on exit. The second argument given to <code>debug</code> in this case is the value being returned from the frame. The debugger displays ‘<samp>Debugger entered--returning value:</samp>’ in the top line of the buffer, followed by the value being returned. </p> </dd> <dt><code>error</code></dt> <dd> + <p>When the first argument is <code>error</code>, the debugger indicates that it is being entered because an error or <code>quit</code> was signaled and not handled, by displaying ‘<samp>Debugger entered--Lisp error:</samp>’ followed by the error signaled and any arguments to <code>signal</code>. For example, </p> <div class="example"> <pre class="example">(let ((debug-on-error t)) + (/ 1 0)) +</pre> + +<pre class="example">------ Buffer: *Backtrace* ------ +Debugger entered--Lisp error: (arith-error) + /(1 0) +... +------ Buffer: *Backtrace* ------ +</pre> +</div> <p>If an error was signaled, presumably the variable <code>debug-on-error</code> is non-<code>nil</code>. If <code>quit</code> was signaled, then presumably the variable <code>debug-on-quit</code> is non-<code>nil</code>. </p> </dd> <dt><code>nil</code></dt> <dd><p>Use <code>nil</code> as the first of the <var>debugger-args</var> when you want to enter the debugger explicitly. The rest of the <var>debugger-args</var> are printed on the top line of the buffer. You can use this feature to display messages—for example, to remind yourself of the conditions under which <code>debug</code> is called. </p></dd> </dl> </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/Invoking-the-Debugger.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Invoking-the-Debugger.html</a> + </p> +</div> |