From 0b0210946b093bcabae9b6bbd06b28b494d1188d Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 31 Mar 2012 12:58:05 -0700 Subject: [PATCH] Edebug doc fixes * doc/lispref/edebug.texi (Instrumenting Macro Calls): Mention defining macros at instrumentation time. (Edebug Options): Mention edebug-unwrap-results. * lisp/emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix. Comments. * admin/FOR-RELEASE: Markup. --- admin/FOR-RELEASE | 4 ++-- doc/lispref/ChangeLog | 6 ++++++ doc/lispref/edebug.texi | 44 +++++++++++++++++++++++++++++++++++++-- lisp/ChangeLog | 4 ++++ lisp/emacs-lisp/edebug.el | 13 ++++++++++-- 5 files changed, 65 insertions(+), 6 deletions(-) diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index 1f498e06c31..ec12b977b9e 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -183,7 +183,7 @@ xresources.texi cyd abbrevs.texi rgm advice.texi cyd anti.texi -back.texi +back.texi rgm backups.texi cyd buffers.texi cyd commands.texi cyd @@ -192,7 +192,7 @@ control.texi cyd customize.texi cyd debugging.texi cyd display.texi cyd -edebug.texi +edebug.texi rgm elisp.texi errors.texi rgm eval.texi cyd diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index b0f9b7c586e..cb7a5c48e15 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2012-03-31 Glenn Morris + + * edebug.texi (Instrumenting Macro Calls): + Mention defining macros at instrumentation time. + (Edebug Options): Mention edebug-unwrap-results. + 2012-03-31 Eli Zaretskii * text.texi (Special Properties): Clarify the description of the diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 33e5e54f1c6..245aaf94c6d 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1113,6 +1113,15 @@ definition, but specifications are much more general than macro arguments. @xref{Defining Macros}, for more explanation of the @code{declare} form. +@c See eg http://debbugs.gnu.org/10577 +@c FIXME Maybe there should be an Edebug option to get it to +@c automatically load the entire source file containing the function +@c being instrumented. That would avoid this. + Take care to ensure that the specifications are known to Edebug when +you instrument code. If you are instrumenting a function from a file +that uses @code{eval-when-compile} to require another file containing +macro definitions, you may need to explicitly load that file. + You can also define an edebug specification for a macro separately from the macro definition with @code{def-edebug-spec}. Adding @code{debug} declarations is preferred, and more convenient, for macro @@ -1255,6 +1264,8 @@ Each of the following elements is matched as alternatives as if by using of them match, nothing is matched, but the @code{¬} specification succeeds. +@c FIXME &key? + @item &define @c @kindex &define @r{(Edebug)} Indicates that the specification is for a defining form. The defining @@ -1422,7 +1433,15 @@ of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the @code{gate} inside of the sublist to prevent backtracking once a sublist is found. -@c FIXME? The actual definition in edebug.el does not have a gate. +@ignore +@c FIXME? The actual definition in edebug.el looks like this (and always +@c has AFAICS). In fact, nothing in edebug.el uses gate. So maybe +@c this is just an example for illustration? +(def-edebug-spec let + ((&rest + &or (symbolp &optional form) symbolp) + body)) +@end ignore @example (def-edebug-spec let ((&rest @@ -1566,7 +1585,28 @@ debugged. @xref{Edebug Execution Modes}. @end defopt -@c FIXME edebug-unwrap-results +@defopt edebug-unwrap-results +If non-@code{nil}, Edebug tries to remove any of its own +instrumentation when showing the results of expressions. This is +relevant when debugging macros where the results of expressions are +themselves instrumented expressions. As a very artificial example, +suppose that the example function @code{fac} has been instrumented, +and consider a macro of the form: + +@c FIXME find a less silly example. +@smallexample +(defmacro test () "Edebug example." + (if (symbol-function 'fac) + @dots{})) +@end smallexample + +If you instrument the @code{test} macro and step through it, then by +default the result of the @code{symbol-function} call has numerous +@code{edebug-after} and @code{edebug-before} forms, which can make it +difficult to see the ``actual'' result. If +@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove +these forms from the result. +@end defopt @defopt edebug-on-error Edebug binds @code{debug-on-error} to this value, if diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 2def7e4c934..970c74bf50f 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,7 @@ +2012-03-31 Glenn Morris + + * emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix. + 2012-03-30 Thierry Volpiatto * dired-aux.el (dired-copy-file-recursive, dired-create-files): diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el index c241ac710cf..67ffd6d5d31 100644 --- a/lisp/emacs-lisp/edebug.el +++ b/lisp/emacs-lisp/edebug.el @@ -1,6 +1,6 @@ ;;; edebug.el --- a source-level debugger for Emacs Lisp -;; Copyright (C) 1988-1995, 1997, 1999-2012 Free Software Foundation, Inc. +;; Copyright (C) 1988-1995, 1997, 1999-2012 Free Software Foundation, Inc. ;; Author: Daniel LaLiberte ;; Maintainer: FSF @@ -191,6 +191,7 @@ Use this with caution since it is not debugged." (defcustom edebug-unwrap-results nil "Non-nil if Edebug should unwrap results of expressions. +That is, Edebug will try to remove its own instrumentation from the result. This is useful when debugging macros where the results of expressions are instrumented expressions. But don't do this when results might be circular or an infinite loop will result." @@ -2028,7 +2029,10 @@ expressions; a `progn' form will be returned enclosing these forms." (def-edebug-spec apply (function-form &rest form)) (def-edebug-spec funcall (function-form &rest form)) -;; FIXME? The manual has a gate here. +;; FIXME? The manual uses this form (maybe that's just for illustration?): +;; (def-edebug-spec let +;; ((&rest &or symbolp (gate symbolp &optional form)) +;; body)) (def-edebug-spec let ((&rest &or (symbolp &optional form) symbolp) body)) @@ -4157,6 +4161,8 @@ You must include newlines in FMT to break lines, but one newline is appended." ;;; Frequency count and coverage ;; FIXME should this use overlays instead? +;; Definitely, IMO. The current business with undo in +;; edebug-temp-display-freq-count is horrid. (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, @@ -4226,6 +4232,8 @@ reinstrument it." (insert "\n") (setq i first-index))))) +;; FIXME this does not work very well. Eg if you press an arrow key, +;; or make a mouse-click, it fails with "Non-character input-event". (defun edebug-temp-display-freq-count () "Temporarily display the frequency count data for the current definition. It is removed when you hit any char." @@ -4235,6 +4243,7 @@ It is removed when you hit any char." (undo-boundary) (edebug-display-freq-count) (setq unread-command-char (read-char)) + ;; Yuck! This doesn't seem to work at all for me. (undo))) -- 2.39.2