From aaf0c30025d24dba6d50fda6e61510020c2d611e Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Thu, 18 Oct 2012 11:37:57 -0400 Subject: [PATCH] * lisp/emacs-lisp/advice.el: Clean up commentary a bit. (ad-do-advised-functions, ad-with-originals): Use `declare'. (byte-code-function-p): Never redefine. --- lisp/ChangeLog | 4 ++ lisp/emacs-lisp/advice.el | 85 ++++++++------------------------------- 2 files changed, 20 insertions(+), 69 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 8c8f88dc89b..51e6b67b86c 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,9 @@ 2012-10-18 Stefan Monnier + * emacs-lisp/advice.el: Clean up commentary a bit. + (ad-do-advised-functions, ad-with-originals): Use `declare'. + (byte-code-function-p): Never redefine. + * emacs-lisp/gv.el (cond): Same fix as before for `if'. 2012-10-18 Glenn Morris diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el index d96076d17a6..007871aa3a6 100644 --- a/lisp/emacs-lisp/advice.el +++ b/lisp/emacs-lisp/advice.el @@ -31,10 +31,6 @@ ;;; Commentary: -;; NOTE: This documentation is slightly out of date. In particular, all the -;; references to Emacs-18 are obsolete now, because it is not any longer -;; supported by this version of Advice. - ;; Advice is documented in the Emacs Lisp Manual. ;; @ Introduction: @@ -83,21 +79,10 @@ ;; - Provides manipulation mechanisms for sets of advised functions via ;; regular expressions that match advice names -;; @ How to get Advice for Emacs-18: -;; ================================= -;; `advice18.el', a version of Advice that also works in Emacs-18 is available -;; either via anonymous ftp from `ftp.cs.buffalo.edu (128.205.32.9)' with -;; pathname `/pub/Emacs/advice18.el', or from one of the Emacs Lisp archive -;; sites, or send email to and I'll mail it to you. - ;; @ Overview, or how to read this file: ;; ===================================== -;; NOTE: This documentation is slightly out of date. In particular, all the -;; references to Emacs-18 are obsolete now, because it is not any longer -;; supported by this version of Advice. An up-to-date version will soon be -;; available as an info file (thanks to the kind help of Jack Vinson and -;; David M. Smith). Until then you can use `outline-mode' to help you read -;; this documentation (set `outline-regexp' to `";; @+"'). +;; You can use `outline-mode' to help you read this documentation (set +;; `outline-regexp' to `";; @+"'). ;; ;; The four major sections of this file are: ;; @@ -111,9 +96,6 @@ ;; @ Restrictions: ;; =============== -;; - This version of Advice only works for Emacs 19.26 and later. It uses -;; new versions of the built-in functions `fset/defalias' which are not -;; yet available in Lucid Emacs, hence, it won't work there. ;; - Advised functions/macros/subrs will only exhibit their advised behavior ;; when they are invoked via their function cell. This means that advice will ;; not work for the following: @@ -229,13 +211,8 @@ ;; @@ Terminology: ;; =============== -;; - Emacs, Emacs-19: Emacs as released by the GNU Project -;; - Lemacs: Lucid's version of Emacs with major version 19 -;; - v18: Any Emacs with major version 18 or built as an extension to that -;; (such as Epoch) -;; - v19: Any Emacs with major version 19 -;; - jwz: Jamie Zawinski - former keeper of Lemacs and creator of the optimizing -;; byte-compiler used in v19s. +;; - Emacs: Emacs as released by the GNU Project +;; - jwz: Jamie Zawinski - creator of the byte-compiler used in v19s. ;; - Advice: The name of this package. ;; - advices: Short for "pieces of advice". @@ -294,8 +271,7 @@ ;; generates a compiled advised definition according to the ;; current advice state which will be used during activation ;; if appropriate. Only use this if the `defadvice' gets -;; actually compiled (with a v18 byte-compiler put the `defadvice' -;; into the body of a `defun' to accomplish proper compilation). +;; actually compiled. ;; An optional can be supplied to document the advice. ;; On call of the `documentation' function it will be combined with the @@ -399,10 +375,7 @@ ;; gets redefined in a non-advice style into a function by the edebug ;; package. If the advice assumes `eval-region' to be a subr it might break ;; once edebug is loaded. Similar situations arise when one wants to use the -;; same piece of advice across different versions of Emacs. Some subrs in a -;; v18 Emacs are functions in v19 and vice versa, but for the most part the -;; semantics remain the same, hence, the same piece of advice might be usable -;; in both Emacs versions. +;; same piece of advice across different versions of Emacs. ;; As a solution to that advice provides argument list access macros that get ;; translated into the proper access forms at activation time, i.e., when the @@ -556,12 +529,7 @@ ;; defined. The special forms `defun' and `defmacro' have been advised to ;; check whether the function/macro they defined had advice information ;; associated with it. If so and forward advice is enabled, the original -;; definition will be saved, and then the advice will be activated. When a -;; file is loaded in a v18 Emacs the functions/macros it defines are also -;; defined with calls to `defun/defmacro'. Hence, we can forward advise -;; functions/macros which will be defined later during a load/autoload of some -;; file (for compiled files generated by jwz's byte-compiler in a v19 Emacs -;; this is slightly more complicated but the basic idea is the same). +;; definition will be saved, and then the advice will be activated. ;; @@ Enabling/disabling pieces or sets of advice: ;; =============================================== @@ -694,10 +662,8 @@ ;; specified as disabled) and all other currently enabled pieces of advice to ;; construct an advised definition and an identifying cache-id and makes them ;; part of the `defadvice' expansion which will then be compiled by the -;; byte-compiler (to ensure that in a v18 emacs you have to put the -;; `defadvice' inside a `defun' to get it compiled and then you have to call -;; that compiled `defun' in order to actually execute the `defadvice'). When -;; the file with the compiled, preactivating `defadvice' gets loaded the +;; byte-compiler. +;; When the file with the compiled, preactivating `defadvice' gets loaded the ;; precompiled advised definition will be cached on the advised function's ;; advice-info. When it gets activated (can be immediately on execution of the ;; `defadvice' or any time later) the cache-id gets checked against the @@ -792,8 +758,7 @@ ;; advised definition of a function, rather they are assembled into a hook ;; form which will be evaluated whenever the advice-info of the advised ;; function gets activated or deactivated. One application of this mechanism -;; is to define file load hooks for files that do not provide such hooks -;; (v19s already come with a general file-load-hook mechanism, v18s don't). +;; is to define file load hooks for files that do not provide such hooks. ;; For example, suppose you want to print a message whenever `file-x' gets ;; loaded, and suppose the last function defined in `file-x' is ;; `file-x-last-fn'. Then we can define the following advice: @@ -1400,8 +1365,8 @@ ;; ;; If you put a preactivating `defadvice' into a Lisp file that gets byte- ;; compiled then the constructed advised definition will get compiled by -;; the byte-compiler. For that to occur in a v18 emacs you have to put the -;; `defadvice' inside a `defun' because the v18 compiler does not compile +;; the byte-compiler. For that to occur in a v18 Emacs you had to put the +;; `defadvice' inside a `defun' because the v18 compiler did not compile ;; top-level forms other than `defun' or `defmacro', for example, ;; ;; (defun fg-defadvice-fum () @@ -1496,10 +1461,7 @@ ;; if one advises a subr such as `eval-region' which then gets redefined by ;; some package (e.g., edebug) into a function with different argument names, ;; then a piece of advice written for `eval-region' that was written with -;; the subr arguments in mind will break. Similar situations arise when one -;; switches between major Emacs versions, e.g., certain subrs in v18 are -;; functions in v19 and vice versa. Also, in v19s subr argument lists -;; are available and will be used, while they are not available in v18. +;; the subr arguments in mind will break. ;; ;; Argument access text macros allow one to access arguments of an advised ;; function in a portable way without having to worry about all these @@ -1882,15 +1844,13 @@ generates a copy of TREE." BODY-FORM...) On each iteration VAR will be bound to the name of an advised function \(a symbol)." + (declare (indent 1)) `(cl-dolist (,(car varform) ad-advised-functions ,(car (cdr varform))) (setq ,(car varform) (intern (car ,(car varform)))) ,@body)) -(if (not (get 'ad-do-advised-functions 'lisp-indent-hook)) - (put 'ad-do-advised-functions 'lisp-indent-hook 1)) - (defun ad-get-advice-info (function) (get function 'ad-advice-info)) @@ -2117,7 +2077,7 @@ function at point for which PREDICATE returns non-nil)." (lambda (function) ;; Oops, no closures - the joys of dynamic scoping: ;; `predicate' clashed with the `predicate' argument - ;; of Lemacs' `completing-read'..... + ;; of `completing-read'..... (funcall ad-pReDiCaTe (intern (car function)))))) t))) (if (equal function "") @@ -2394,12 +2354,6 @@ See Info node `(elisp)Computed Advice' for detailed documentation." ;;"non-nil if DEFINITION is a piece of advice." `(eq (car-safe ,definition) 'advice)) -;; Emacs/Lemacs cross-compatibility -;; (compiled-function-p is an obsolete function in Emacs): -(if (and (not (fboundp 'byte-code-function-p)) - (fboundp 'compiled-function-p)) - (ad-safe-fset 'byte-code-function-p 'compiled-function-p)) - (defmacro ad-compiled-p (definition) "Return non-nil if DEFINITION is a compiled byte-code object." `(or (byte-code-function-p ,definition) @@ -3696,6 +3650,7 @@ usage: (defadvice FUNCTION (CLASS NAME [POSITION] [ARGLIST] FLAG...) For any members of FUNCTIONS that are not currently advised the rebinding will be a noop. Any modifications done to the definitions of FUNCTIONS will be undone on exit of this macro." + (declare (indent 1)) (let* ((index -1) ;; Make let-variables to store current definitions: (current-bindings @@ -3735,14 +3690,6 @@ undone on exit of this macro." ,(car (nth index current-bindings))))) functions)))))) -(if (not (get 'ad-with-originals 'lisp-indent-hook)) - (put 'ad-with-originals 'lisp-indent-hook 1)) - - -;; @@ Advising `documentation': -;; ============================ -;; Use the advice mechanism to advise `documentation' to make it -;; generate proper documentation strings for advised definitions: ;; @@ Starting, stopping and recovering from the advice package magic: ;; =================================================================== -- 2.39.2