comparison lisp/emacs-lisp/edebug.el @ 103885:adbe0e36df45

(edebug-setup-hook, edebug-all-forms) (edebug-eval-macro-args, edebug-save-displayed-buffer-points) (edebug-print-length, edebug-print-level, edebug-print-circle) (edebug-sit-for-seconds, edebug-view-outside) (edebug-bounce-point, edebug-set-global-break-condition) (edebug-Go-nonstop-mode, edebug-trace-mode) (edebug-Trace-fast-mode, edebug-continue-mode) (edebug-Continue-fast-mode, edebug-forward-sexp, edebug-help) (edebug-visit-eval-list): Doc fixes.

103884:dbafc1b9107d

(defcustom edebug-setup-hook nil
  "Functions to call before edebug is used.
Each time it is set to a new value, Edebug will call those functions
once and then `edebug-setup-hook' is reset to nil.  You could use this
to load up Edebug specifications associated with a package you are
using but only when you also use Edebug."
  :type 'hook
  :group 'edebug)

;; edebug-all-defs and edebug-all-forms need to be autoloaded
;; because the byte compiler binds them; as a result, if edebug

;; because the byte compiler binds them; as a result, if edebug
;; is first loaded for a require in a compilation, they will be left unbound.

;;;###autoload
(defcustom edebug-all-forms nil
  "Non-nil evaluation of all forms will instrument for Edebug.
This doesn't apply to loading or evaluations in the minibuffer.
Use the command `edebug-all-forms' to toggle the value of this option."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-eval-macro-args nil
  "Non-nil means all macro call arguments may be evaluated.
If this variable is nil, the default, Edebug will *not* wrap
macro call arguments as if they will be evaluated.
For each macro, a `edebug-form-spec' overrides this option.
So to specify exceptions for macros that have some arguments evaluated
and some not, you should specify an `edebug-form-spec'."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-save-windows t
  "If non-nil, Edebug saves and restores the window configuration.

(defcustom edebug-save-displayed-buffer-points nil
  "If non-nil, save and restore point in all displayed buffers.

Saving and restoring point in other buffers is necessary if you are
debugging code that changes the point of a buffer which is displayed
in a non-selected window.  If Edebug or the user then selects the
window, the buffer's point will be changed to the window's point.

Saving and restoring point in all buffers is expensive, since it
requires selecting each window twice, so enable this only if you need
it."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-initial-mode 'step
  "Initial execution mode for Edebug, if non-nil.

  :type 'boolean
  :group 'edebug)


(defcustom edebug-print-length 50
  "Default value of `print-length' for printing results in Edebug."
  :type 'integer
  :group 'edebug)
(defcustom edebug-print-level 50
  "Default value of `print-level' for printing results in Edebug."
  :type 'integer
  :group 'edebug)
(defcustom edebug-print-circle t
  "Default value of `print-circle' for printing results in Edebug."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-unwrap-results nil
  "Non-nil if Edebug should unwrap results of expressions.

If the result is non-nil, then break.  Errors are ignored."
  :type 'sexp
  :group 'edebug)

(defcustom edebug-sit-for-seconds 1
  "Number of seconds to pause when execution mode is `trace'."
  :type 'number
  :group 'edebug)

;;; Form spec utilities.

(def-edebug-spec defun
  (&define name lambda-list
	   [&optional stringp]
	   [&optional ("interactive" interactive)]
	   def-body))
(def-edebug-spec defmacro
  (&define name lambda-list [&optional ("declare" &rest sexp)] def-body))

(def-edebug-spec arglist lambda-list)  ;; deprecated - use lambda-list.

(def-edebug-spec mapconcat (function-form form form))
(def-edebug-spec mapatoms (function-form &optional form))
(def-edebug-spec apply (function-form &rest form))
(def-edebug-spec funcall (function-form &rest form))

(def-edebug-spec let
  ((&rest &or (symbolp &optional form) symbolp)
   body))

(def-edebug-spec let* let)

;; Note: here we have defvars for variables that are
;; built-in in certain versions.
;; Each defvar makes a difference
;; in versions where the variable is *not* built-in.

;; Emacs 18
(defvar edebug-outside-unread-command-char)

;; Emacs 19.
(defvar edebug-outside-last-command-event)
(defvar edebug-outside-unread-command-events)

;; Disable byte compiler warnings about unread-command-char and -event
;; (maybe works with byte-compile-version 2.22 at least)
(defvar edebug-unread-command-char-warning)
(defvar edebug-unread-command-event-warning)
(eval-when-compile
  (setq edebug-unread-command-char-warning
	(get 'unread-command-char 'byte-obsolete-variable))
  (put 'unread-command-char 'byte-obsolete-variable nil))

(defun edebug-recursive-edit ()

	(edebug-outside-defining-kbd-macro defining-kbd-macro)

	(edebug-outside-last-command last-command)
	(edebug-outside-this-command this-command)

	(edebug-outside-unread-command-char unread-command-char)
	(edebug-outside-current-prefix-arg current-prefix-arg)

	(edebug-outside-last-input-event last-input-event)
	(edebug-outside-last-command-event last-command-event)
	(edebug-outside-last-event-frame last-event-frame)

  ;;  (edebug-set-windows edebug-inside-windows))
  (edebug-pop-to-buffer edebug-buffer)
  (goto-char edebug-point))

(defun edebug-view-outside ()
  "Change to the outside window configuration."
  (interactive)
  (if (not edebug-active)
      (error "Edebug is not active"))
  (setq edebug-inside-windows
	(edebug-current-windows edebug-save-windows))

	   (substitute-command-keys "\\<global-map>\\[edebug-where]")))


(defun edebug-bounce-point (arg)
  "Bounce the point in the outside current buffer.
If prefix arg is supplied, sit for that many seconds before returning.
The default is one second."
  (interactive "p")
  (if (not edebug-active)
      (error "Edebug is not active"))
  (save-excursion
    ;; If the buffer's currently displayed, avoid set-window-configuration.

  (interactive)
  (edebug-modify-breakpoint nil))


(defun edebug-set-global-break-condition (expression)
  (interactive
   (list
    (let ((initial (and edebug-global-break-condition
			(format "%s" edebug-global-break-condition))))
      (read-from-minibuffer

  (if arg
      (edebug-set-breakpoint t))
  (edebug-set-mode 'go "Go..." "Edebug will go until break."))

(defun edebug-Go-nonstop-mode ()
  "Go, evaluating without debugging."
  (interactive)
  (edebug-set-mode 'Go-nonstop "Go-Nonstop..."
		   "Edebug will not stop at breaks."))


(defun edebug-trace-mode ()
  "Begin trace mode."
  (interactive)
  (edebug-set-mode 'trace "Tracing..." "Edebug will trace with pause."))

(defun edebug-Trace-fast-mode ()
  "Trace with no wait at each step."
  (interactive)
  (edebug-set-mode 'Trace-fast
		   "Trace fast..." "Edebug will trace without pause."))

(defun edebug-continue-mode ()
  "Begin continue mode."
  (interactive)
  (edebug-set-mode 'continue "Continue..."
		   "Edebug will pause at breakpoints."))

(defun edebug-Continue-fast-mode ()
  "Trace with no wait at each step."
  (interactive)
  (edebug-set-mode 'Continue-fast "Continue fast..."
		   "Edebug will stop and go at breakpoints."))

;; ------------------------------------------------------------

   "Edebug will stop after exiting the next expression."))


(defun edebug-forward-sexp (arg)
  "Proceed from the current point to the end of the ARGth sexp ahead.
If there are not ARG sexps ahead, then do edebug-step-out."
  (interactive "p")
  (condition-case nil
      (let ((parse-sexp-ignore-comments t))
	;; Call forward-sexp repeatedly until done or failure.
	(forward-sexp arg)

(global-unset-key global-edebug-prefix)
(global-set-key global-edebug-prefix global-edebug-map)


(defun edebug-help ()
  (interactive)
  (describe-function 'edebug-mode))

(defun edebug-mode ()
  "Mode for Emacs Lisp buffers while in Edebug.

  (edebug-outside-excursion
   (edebug-eval-display-list (edebug-eval-result-list))
   ))

(defun edebug-visit-eval-list ()
  (interactive)
  (edebug-eval-redisplay)
  (edebug-pop-to-buffer edebug-eval-buffer))

    ;; else, could just display edebug-backtrace-buffer
    )
  (with-output-to-temp-buffer (buffer-name edebug-backtrace-buffer)
    (setq edebug-backtrace-buffer standard-output)
    (let ((print-escape-newlines t)
	  (print-length 50)
	  last-ok-point)
      (backtrace)

      ;; Clean up the backtrace.
      ;; Not quite right for current edebug scheme.

  (apply 'edebug-trace-display edebug-trace-buffer fmt args))


;;; Frequency count and coverage

(defun edebug-display-freq-count ()
  "Display the frequency count data for each line of the current definition.
The frequency counts are inserted as comment lines after each line,
and you can undo all insertions with one `undo' command.

103885:adbe0e36df45

(defcustom edebug-setup-hook nil
  "Functions to call before edebug is used.
Each time it is set to a new value, Edebug will call those functions
once and then reset `edebug-setup-hook' to nil.  You could use this
to load up Edebug specifications associated with a package you are
using, but only when you also use Edebug."
  :type 'hook
  :group 'edebug)

;; edebug-all-defs and edebug-all-forms need to be autoloaded
;; because the byte compiler binds them; as a result, if edebug

;; because the byte compiler binds them; as a result, if edebug
;; is first loaded for a require in a compilation, they will be left unbound.

;;;###autoload
(defcustom edebug-all-forms nil
  "Non-nil means evaluation of all forms will instrument for Edebug.
This doesn't apply to loading or evaluations in the minibuffer.
Use the command `edebug-all-forms' to toggle the value of this option."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-eval-macro-args nil
  "Non-nil means all macro call arguments may be evaluated.
If this variable is nil, the default, Edebug will *not* wrap
macro call arguments as if they will be evaluated.
For each macro, an `edebug-form-spec' overrides this option.
So to specify exceptions for macros that have some arguments evaluated
and some not, use `def-edebug-spec' to specify an `edebug-form-spec'."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-save-windows t
  "If non-nil, Edebug saves and restores the window configuration.

(defcustom edebug-save-displayed-buffer-points nil
  "If non-nil, save and restore point in all displayed buffers.

Saving and restoring point in other buffers is necessary if you are
debugging code that changes the point of a buffer that is displayed
in a non-selected window.  If Edebug or the user then selects the
window, the buffer's point will be changed to the window's point.

Saving and restoring point in all buffers is expensive, since it
requires selecting each window twice, so enable this only if you
need it."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-initial-mode 'step
  "Initial execution mode for Edebug, if non-nil.

  :type 'boolean
  :group 'edebug)


(defcustom edebug-print-length 50
  "If non-nil, default value of `print-length' for printing results in Edebug."
  :type 'integer
  :group 'edebug)
(defcustom edebug-print-level 50
  "If non-nil, default value of `print-level' for printing results in Edebug."
  :type 'integer
  :group 'edebug)
(defcustom edebug-print-circle t
  "If non-nil, default value of `print-circle' for printing results in Edebug."
  :type 'boolean
  :group 'edebug)

(defcustom edebug-unwrap-results nil
  "Non-nil if Edebug should unwrap results of expressions.

If the result is non-nil, then break.  Errors are ignored."
  :type 'sexp
  :group 'edebug)

(defcustom edebug-sit-for-seconds 1
  "Number of seconds to pause when execution mode is `trace' or `continue'."
  :type 'number
  :group 'edebug)

;;; Form spec utilities.

(def-edebug-spec defun
  (&define name lambda-list
	   [&optional stringp]
	   [&optional ("interactive" interactive)]
	   def-body))
;; FIXME? Isn't this missing the doc-string?  Cf defun.
(def-edebug-spec defmacro
  (&define name lambda-list [&optional ("declare" &rest sexp)] def-body))

(def-edebug-spec arglist lambda-list)  ;; deprecated - use lambda-list.

(def-edebug-spec mapconcat (function-form form form))
(def-edebug-spec mapatoms (function-form &optional form))
(def-edebug-spec apply (function-form &rest form))
(def-edebug-spec funcall (function-form &rest form))

;; FIXME? The manual has a gate here.
(def-edebug-spec let
  ((&rest &or (symbolp &optional form) symbolp)
   body))

(def-edebug-spec let* let)

;; Note: here we have defvars for variables that are
;; built-in in certain versions.
;; Each defvar makes a difference
;; in versions where the variable is *not* built-in.

;; Emacs 18  FIXME
(defvar edebug-outside-unread-command-char)

;; Emacs 19.
(defvar edebug-outside-last-command-event)
(defvar edebug-outside-unread-command-events)

;; Disable byte compiler warnings about unread-command-char and -event
;; (maybe works with byte-compile-version 2.22 at least)
(defvar edebug-unread-command-char-warning)
(defvar edebug-unread-command-event-warning)
(eval-when-compile			; FIXME
  (setq edebug-unread-command-char-warning
	(get 'unread-command-char 'byte-obsolete-variable))
  (put 'unread-command-char 'byte-obsolete-variable nil))

(defun edebug-recursive-edit ()

	(edebug-outside-defining-kbd-macro defining-kbd-macro)

	(edebug-outside-last-command last-command)
	(edebug-outside-this-command this-command)

	(edebug-outside-unread-command-char unread-command-char) ; FIXME
	(edebug-outside-current-prefix-arg current-prefix-arg)

	(edebug-outside-last-input-event last-input-event)
	(edebug-outside-last-command-event last-command-event)
	(edebug-outside-last-event-frame last-event-frame)

  ;;  (edebug-set-windows edebug-inside-windows))
  (edebug-pop-to-buffer edebug-buffer)
  (goto-char edebug-point))

(defun edebug-view-outside ()
  "Change to the outside window configuration.
Use `edebug-where' to return."
  (interactive)
  (if (not edebug-active)
      (error "Edebug is not active"))
  (setq edebug-inside-windows
	(edebug-current-windows edebug-save-windows))

	   (substitute-command-keys "\\<global-map>\\[edebug-where]")))


(defun edebug-bounce-point (arg)
  "Bounce the point in the outside current buffer.
If prefix argument ARG is supplied, sit for that many seconds
before returning.  The default is one second."
  (interactive "p")
  (if (not edebug-active)
      (error "Edebug is not active"))
  (save-excursion
    ;; If the buffer's currently displayed, avoid set-window-configuration.

  (interactive)
  (edebug-modify-breakpoint nil))


(defun edebug-set-global-break-condition (expression)
  "Set `edebug-global-break-condition' to EXPRESSION."
  (interactive
   (list
    (let ((initial (and edebug-global-break-condition
			(format "%s" edebug-global-break-condition))))
      (read-from-minibuffer

  (if arg
      (edebug-set-breakpoint t))
  (edebug-set-mode 'go "Go..." "Edebug will go until break."))

(defun edebug-Go-nonstop-mode ()
  "Go, evaluating without debugging.
You can use `edebug-stop', or any editing command, to stop."
  (interactive)
  (edebug-set-mode 'Go-nonstop "Go-Nonstop..."
		   "Edebug will not stop at breaks."))


(defun edebug-trace-mode ()
  "Begin trace mode.
Pauses for `edebug-sit-for-seconds' at each stop point."
  (interactive)
  (edebug-set-mode 'trace "Tracing..." "Edebug will trace with pause."))

(defun edebug-Trace-fast-mode ()
  "Trace with no wait at each step.
Updates the display at each stop point, but does not pause."
  (interactive)
  (edebug-set-mode 'Trace-fast
		   "Trace fast..." "Edebug will trace without pause."))

(defun edebug-continue-mode ()
  "Begin continue mode.
Pauses for `edebug-sit-for-seconds' at each break point."
  (interactive)
  (edebug-set-mode 'continue "Continue..."
		   "Edebug will pause at breakpoints."))

(defun edebug-Continue-fast-mode ()
  "Trace with no wait at each step.
Updates the display at each break point, but does not pause."
  (interactive)
  (edebug-set-mode 'Continue-fast "Continue fast..."
		   "Edebug will stop and go at breakpoints."))

;; ------------------------------------------------------------

   "Edebug will stop after exiting the next expression."))


(defun edebug-forward-sexp (arg)
  "Proceed from the current point to the end of the ARGth sexp ahead.
If there are not ARG sexps ahead, then do `edebug-step-out'."
  (interactive "p")
  (condition-case nil
      (let ((parse-sexp-ignore-comments t))
	;; Call forward-sexp repeatedly until done or failure.
	(forward-sexp arg)

(global-unset-key global-edebug-prefix)
(global-set-key global-edebug-prefix global-edebug-map)


(defun edebug-help ()
  "Describe `edebug-mode'."
  (interactive)
  (describe-function 'edebug-mode))

(defun edebug-mode ()
  "Mode for Emacs Lisp buffers while in Edebug.

  (edebug-outside-excursion
   (edebug-eval-display-list (edebug-eval-result-list))
   ))

(defun edebug-visit-eval-list ()
  "Switch to the evaluation list buffer \"*edebug*\"."
  (interactive)
  (edebug-eval-redisplay)
  (edebug-pop-to-buffer edebug-eval-buffer))

    ;; else, could just display edebug-backtrace-buffer
    )
  (with-output-to-temp-buffer (buffer-name edebug-backtrace-buffer)
    (setq edebug-backtrace-buffer standard-output)
    (let ((print-escape-newlines t)
	  (print-length 50)	; FIXME cf edebug-safe-prin1-to-string
	  last-ok-point)
      (backtrace)

      ;; Clean up the backtrace.
      ;; Not quite right for current edebug scheme.

  (apply 'edebug-trace-display edebug-trace-buffer fmt args))


;;; Frequency count and coverage

;; FIXME should this use overlays instead?
(defun edebug-display-freq-count ()
  "Display the frequency count data for each line of the current definition.
The frequency counts are inserted as comment lines after each line,
and you can undo all insertions with one `undo' command.