Add backtrace-mode and use it in the debugger, ERT and Edebug

* doc/lispref/debugging.texi (Using Debugger): Remove explanation of
backtrace buffer.  Refer to new node.
(Backtraces): New node.
(Debugger Commands): Refer to new node.  Remove 'v'.
* doc/lispref/edebug.texi (Edebug Misc): Refer to new node.
* doc/misc/ert.texi (Running Tests Interactively): Refer to new node.

* lisp/emacs-lisp-backtrace.el: New file.
* test/lisp/emacs-lisp/backtrace-tests.el: New file.

* lisp/emacs-lisp/debug.el: (debugger-buffer-state): New cl-defstruct.
(debugger--restore-buffer-state): New function.
(debug): Use a debugger-buffer-state object to save and restore buffer
state.  Fix bug#15749 by leaving an unused buffer in debugger-mode,
empty, instead of in fundamental-mode, and then when reusing a buffer,
not calling debugger-mode if the buffer is already in debugger-mode.
(debugger-insert-backtrace): Remove.
(debugger-setup-buffer): Use backtrace-mode.
(debugger--insert-header): New function.
(debugger-continue, debugger-return-value): Change check for flags to
use backtrace-frames.
(debugger-frame-number): Determine backtrace frame number from
backtrace-frames.
(debugger--locals-visible-p, debugger--insert-locals)
(debugger--show-locals, debugger--hide-locals)
(debugger-toggle-locals): Remove.
(debugger-mode-map): Make a child of backtrace-mode-map.  Move
navigation commands to backtrace-mode-map.  Bind 'q' to debugger-quit
instead of top-level.  Make Help Follow menu item call
backtrace-help-follow-symbol.
(debugger-mode): Derive from backtrace-mode.
(debug-help-follow): Remove.  Move body of this function to
'backtrace-help-follow-symbol' in backtrace.el.
(debugger-quit): New function.

* lisp/emacs-lisp/edebug.el (edebug-unwrap-results): Remove warning
in docstring about circular results.
(edebug-unwrap): Use pcase.
(edebug-unwrap1): New function to unwrap circular objects.
(edebug-unwrap*): Use it.
(edebug--frame): New cl-defstruct.
(edebug-backtrace): Call the buffer *Edebug Backtrace* and use
backtrace-mode.  Get the frames from edebug--backtrace-frames.
(edebug--backtrace-frames, edebug--unwrap-and-add-info)
(edebug--symbol-not-prefixed-p): New functions.

* lisp/emacs-lisp/lisp-mode.el
(lisp-el-font-lock-keywords-for-backtraces)
(lisp-el-font-lock-keywords-for-backtraces-1)
(lisp-el-font-lock-keywords-for-backtraces-2): New constants.

* lisp/emacs-lisp/ert.el (ert--print-backtrace): Remove.
(ert--run-test-debugger): Use backtrace-get-frames.
(ert-run-tests-batch): Use backtrace-to-string.
(ert-results-pop-to-backtrace-for-test-at-point): Use backtrace-mode.
(ert--insert-backtrace-header): New function.

* tests/lisp/emacs-lisp/ert-tests.el (ert-test--which-file):
Use backtrace-frame slot accessor.

2 files changed, 90 insertions, 1 deletions

diff --git a/test/lisp/emacs-lisp/backtrace-tests.el b/test/lisp/emacs-lisp/backtrace-tests.el
new file mode 100644
index 00000000000..75da468494b
--- /dev/null
+++ b/test/lisp/emacs-lisp/backtrace-tests.el
@@ -0,0 +1,89 @@
+;;; backtrace-tests.el --- Tests for emacs-lisp/backtrace.el  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2018 Free Software Foundation, Inc.
+
+;; Author: Gemini Lasswell
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Code:
+
+(require 'backtrace)
+(require 'ert)
+(require 'seq)
+
+;; Create a backtrace frames list with several frames.
+;; TODO load this from an el file in backtrace-resources/ so the tests
+;; can be byte-compiled.
+(defvar backtrace-tests--frames nil)
+
+(defun backtrace-tests--func1 (arg1 arg2)
+  (setq backtrace-tests--frames (backtrace-get-frames nil))
+  (list arg1 arg2))
+
+(defun backtrace-tests--func2 (arg)
+  (list arg))
+
+(defun backtrace-tests--func3 (arg)
+  (let ((foo (list 'a arg 'b)))
+    (list foo (backtrace-tests--func2 arg) (backtrace-tests--func1 arg 0))))
+
+(defun backtrace-tests--create-backtrace-frames ()
+  (backtrace-tests--func3 "string")
+  ;; Discard frames before this one.
+  (let (this-index)
+    (dotimes (index (length backtrace-tests--frames))
+      (when (eq (backtrace-frame-fun (nth index backtrace-tests--frames))
+                'backtrace-tests--create-backtrace-frames)
+        (setq this-index index)))
+    (setq backtrace-tests--frames (seq-subseq backtrace-tests--frames
+                                              0 (1+ this-index)))))
+
+(backtrace-tests--create-backtrace-frames)
+
+;; TODO check that debugger-batch-max-lines still works
+
+(defun backtrace-tests--insert-header ()
+  (insert "Test header\n"))
+
+(defmacro backtrace-tests--with-buffer (&rest body)
+  `(with-temp-buffer
+     (backtrace-mode)
+     (setq backtrace-frames backtrace-tests--frames)
+     (setq backtrace-insert-header-function #'backtrace-tests--insert-header)
+     (backtrace-print)
+     ,@body))
+
+;;; Tests
+(ert-deftest backtrace-tests--to-string ()
+  (should (string= (backtrace-to-string backtrace-tests--frames)
+                    "  backtrace-get-frames(nil)
+  (setq backtrace-tests--frames (backtrace-get-frames nil))
+  backtrace-tests--func1(\"string\" 0)
+  (list foo (backtrace-tests--func2 arg) (backtrace-tests--func1 arg 0))
+  (let ((foo (list 'a arg 'b))) (list foo (backtrace-tests--func2 arg) (backtrace-tests--func1 arg 0)))
+  backtrace-tests--func3(\"string\")
+  backtrace-tests--create-backtrace-frames()
+")))
+
+(provide 'backtrace-tests)
+
+;; These tests expect to see non-byte compiled stack frames.
+;; Local Variables:
+;; no-byte-compile: t
+;; End:
+
+;;; backtrace-tests.el ends here
diff --git a/test/lisp/emacs-lisp/ert-tests.el b/test/lisp/emacs-lisp/ert-tests.el
index cb957bd9fd6..1fe5b79ef36 100644
--- a/test/lisp/emacs-lisp/ert-tests.el
+++ b/test/lisp/emacs-lisp/ert-tests.el
@@ -376,7 +376,7 @@ This macro is used to test if macroexpansion in `should' works."
          (test (make-ert-test :body test-body))
          (result (ert-run-test test)))
     (should (ert-test-failed-p result))
-    (should (eq (nth 1 (car (ert-test-failed-backtrace result)))
+    (should (eq (backtrace-frame-fun (car (ert-test-failed-backtrace result)))
                 'signal))))
 
 (ert-deftest ert-test-messages ()