Function: backtrace-mode

backtrace-mode is an interactive and byte-compiled function defined in backtrace.el.gz.

Signature

(backtrace-mode)

Documentation

Generic major mode for examining an Elisp stack backtrace.

This mode can be used directly, or other major modes can be derived from it, using define-derived-mode.

In this major mode, the buffer contains some optional lines of header text followed by backtrace frames, each consisting of one or more whole lines.

Letters in this mode do not insert themselves; instead they are commands.
# backtrace-toggle-print-circle
+ backtrace-multi-line
- backtrace-single-line
. backtrace-expand-ellipses
0 digit-argument
1 digit-argument
2 digit-argument
3 digit-argument
4 digit-argument
5 digit-argument
6 digit-argument
7 digit-argument
8 digit-argument
9 digit-argument
: backtrace-toggle-print-gensym
< beginning-of-buffer
<backtab> backward-button
<follow-link> mouse-face
<mouse-2> mouse-select-window
> end-of-buffer
? describe-mode
C-M-i backward-button
DEL scroll-down-command
RET backtrace-help-follow-symbol
S-SPC scroll-down-command
SPC scroll-up-command
SPC..~ undefined
TAB forward-button
g revert-buffer
h describe-mode
n backtrace-forward-frame
p backtrace-backward-frame
q quit-window
s backtrace-goto-source
v backtrace-toggle-locals

A mode which inherits from Backtrace mode, or a command which creates a backtrace-mode buffer, should usually do the following:

 - Set backtrace-revert-hook, if the buffer contents need
   to be specially recomputed prior to revert-buffer.
 - Maybe set backtrace-insert-header-function to a function to create
   header text for the buffer.
 - Set backtrace-frames(var)/backtrace-frames(fun) (see below).
 - Maybe modify backtrace-view (see below).
 - Maybe set backtrace-print-function.

A command which creates or switches to a Backtrace mode buffer, such as ert-results-pop-to-backtrace-for-test-at-point, should initialize backtrace-frames(var)/backtrace-frames(fun) to a list of backtrace-frame objects (backtrace-get-frames is provided for that purpose, if desired), and may optionally modify backtrace-view, which is a plist describing the appearance of the backtrace. Finally, it should call backtrace-print.

backtrace-print calls backtrace-insert-header-function followed by backtrace-print-frame, once for each stack frame.

In addition to any hooks its parent mode special-mode might have run, this mode runs the hook backtrace-mode-hook, as the final or penultimate step during initialization.

Probably introduced at or before Emacs version 27.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/backtrace.el.gz
;;; The mode definition

(define-derived-mode backtrace-mode special-mode "Backtrace"
  "Generic major mode for examining an Elisp stack backtrace.
This mode can be used directly, or other major modes can be
derived from it, using `define-derived-mode'.

In this major mode, the buffer contains some optional lines of
header text followed by backtrace frames, each consisting of one
or more whole lines.

Letters in this mode do not insert themselves; instead they are
commands.
\\<backtrace-mode-map>
\\{backtrace-mode-map}

A mode which inherits from Backtrace mode, or a command which
creates a `backtrace-mode' buffer, should usually do the following:

 - Set `backtrace-revert-hook', if the buffer contents need
   to be specially recomputed prior to `revert-buffer'.
 - Maybe set `backtrace-insert-header-function' to a function to create
   header text for the buffer.
 - Set `backtrace-frames' (see below).
 - Maybe modify `backtrace-view' (see below).
 - Maybe set `backtrace-print-function'.

A command which creates or switches to a Backtrace mode buffer,
such as `ert-results-pop-to-backtrace-for-test-at-point', should
initialize `backtrace-frames' to a list of `backtrace-frame'
objects (`backtrace-get-frames' is provided for that purpose, if
desired), and may optionally modify `backtrace-view', which is a
plist describing the appearance of the backtrace.  Finally, it
should call `backtrace-print'.

`backtrace-print' calls `backtrace-insert-header-function'
followed by `backtrace-print-frame', once for each stack frame."
  :syntax-table emacs-lisp-mode-syntax-table
  (when backtrace-fontify
    (setq font-lock-defaults
          '((backtrace-font-lock-keywords
             backtrace-font-lock-keywords-1
             backtrace-font-lock-keywords-2)
            nil nil nil nil
	    (font-lock-syntactic-face-function
	     . lisp-font-lock-syntactic-face-function))))
  (setq truncate-lines t)
  (buffer-disable-undo)
  ;; In debug.el, from 1998 to 2009 this was set to nil, reason stated
  ;; was because of bytecode. Since 2009 it's been set to t, but the
  ;; default is t so I think this isn't necessary.
  ;; (set-buffer-multibyte t)
  (setq-local revert-buffer-function #'backtrace-revert)
  (setq-local filter-buffer-substring-function #'backtrace--filter-visible)
  (setq-local indent-line-function 'lisp-indent-line)
  (setq-local indent-region-function 'lisp-indent-region)
  (add-hook 'xref-backend-functions #'backtrace--xref-backend nil t))