mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-10 00:00:39 -08:00
Code Issues Projects Releases Wiki Activity

* lisp/emacs-lisp/advice.el: Clean up commentary a bit.

Browse source 
(ad-do-advised-functions, ad-with-originals): Use `declare'.
(byte-code-function-p): Never redefine.
This commit is contained in:
Stefan Monnier 2012-10-18 11:37:57 -04:00
parent 90eacf9920
commit aaf0c30025
2 changed files with 20 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

4
lisp/ChangeLog
View file

@ -1,5 +1,9 @@
2012-10-18 Stefan Monnier <monnier@iro.umontreal.ca> 2012-10-18 Stefan Monnier <monnier@iro.umontreal.ca>
* 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'. * emacs-lisp/gv.el (cond): Same fix as before for `if'.
2012-10-18 Glenn Morris <rgm@gnu.org> 2012-10-18 Glenn Morris <rgm@gnu.org>

85
lisp/emacs-lisp/advice.el
View file

@ -31,10 +31,6 @@
;;; Commentary: ;;; 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. ;; Advice is documented in the Emacs Lisp Manual.
;; @ Introduction: ;; @ Introduction:
@ -83,21 +79,10 @@
;; - Provides manipulation mechanisms for sets of advised functions via ;; - Provides manipulation mechanisms for sets of advised functions via
;; regular expressions that match advice names ;; 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 <hans@cs.buffalo.edu> and I'll mail it to you.
;; @ Overview, or how to read this file: ;; @ Overview, or how to read this file:
;; ===================================== ;; =====================================
;; NOTE: This documentation is slightly out of date. In particular, all the ;; You can use `outline-mode' to help you read this documentation (set
;; references to Emacs-18 are obsolete now, because it is not any longer ;; `outline-regexp' to `";; @+"').
;; 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 `";; @+"').
;; ;;
;; The four major sections of this file are: ;; The four major sections of this file are:
;; ;;
@ -111,9 +96,6 @@
;; @ Restrictions: ;; @ 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 ;; - Advised functions/macros/subrs will only exhibit their advised behavior
;; when they are invoked via their function cell. This means that advice will ;; when they are invoked via their function cell. This means that advice will
;; not work for the following: ;; not work for the following:
@ -229,13 +211,8 @@
;; @@ Terminology: ;; @@ Terminology:
;; =============== ;; ===============
;; - Emacs, Emacs-19: Emacs as released by the GNU Project ;; - Emacs: Emacs as released by the GNU Project
;; - Lemacs: Lucid's version of Emacs with major version 19 ;; - jwz: Jamie Zawinski - creator of the byte-compiler used in v19s.
;; - 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.
;; - Advice: The name of this package. ;; - Advice: The name of this package.
;; - advices: Short for "pieces of advice". ;; - advices: Short for "pieces of advice".
@ -294,8 +271,7 @@
;; generates a compiled advised definition according to the ;; generates a compiled advised definition according to the
;; current advice state which will be used during activation ;; current advice state which will be used during activation
;; if appropriate. Only use this if the `defadvice' gets ;; if appropriate. Only use this if the `defadvice' gets
;; actually compiled (with a v18 byte-compiler put the `defadvice' ;; actually compiled.
;; into the body of a `defun' to accomplish proper compilation).
;; An optional <documentation-string> can be supplied to document the advice. ;; An optional <documentation-string> can be supplied to document the advice.
;; On call of the `documentation' function it will be combined with the ;; 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 ;; 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 ;; 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 ;; 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 ;; same piece of advice across different versions of Emacs.
;; 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.
;; As a solution to that advice provides argument list access macros that get ;; 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 ;; 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 ;; defined. The special forms `defun' and `defmacro' have been advised to
;; check whether the function/macro they defined had advice information ;; check whether the function/macro they defined had advice information
;; associated with it. If so and forward advice is enabled, the original ;; 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 ;; definition will be saved, and then the advice will be activated.
;; 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).
;; @@ Enabling/disabling pieces or sets of advice: ;; @@ Enabling/disabling pieces or sets of advice:
;; =============================================== ;; ===============================================
@ -694,10 +662,8 @@
;; specified as disabled) and all other currently enabled pieces of advice to ;; specified as disabled) and all other currently enabled pieces of advice to
;; construct an advised definition and an identifying cache-id and makes them ;; construct an advised definition and an identifying cache-id and makes them
;; part of the `defadvice' expansion which will then be compiled by the ;; 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 ;; byte-compiler.
;; `defadvice' inside a `defun' to get it compiled and then you have to call ;; When the file with the compiled, preactivating `defadvice' gets loaded the
;; that compiled `defun' in order to actually execute the `defadvice'). When
;; the file with the compiled, preactivating `defadvice' gets loaded the
;; precompiled advised definition will be cached on the advised function's ;; precompiled advised definition will be cached on the advised function's
;; advice-info. When it gets activated (can be immediately on execution of the ;; 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 ;; `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 ;; advised definition of a function, rather they are assembled into a hook
;; form which will be evaluated whenever the advice-info of the advised ;; form which will be evaluated whenever the advice-info of the advised
;; function gets activated or deactivated. One application of this mechanism ;; function gets activated or deactivated. One application of this mechanism
;; is to define file load hooks for files that do not provide such hooks ;; 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).
;; For example, suppose you want to print a message whenever `file-x' gets ;; For example, suppose you want to print a message whenever `file-x' gets
;; loaded, and suppose the last function defined in `file-x' is ;; loaded, and suppose the last function defined in `file-x' is
;; `file-x-last-fn'. Then we can define the following advice: ;; `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- ;; If you put a preactivating `defadvice' into a Lisp file that gets byte-
;; compiled then the constructed advised definition will get compiled by ;; 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 ;; the byte-compiler. For that to occur in a v18 Emacs you had to put the
;; `defadvice' inside a `defun' because the v18 compiler does not compile ;; `defadvice' inside a `defun' because the v18 compiler did not compile
;; top-level forms other than `defun' or `defmacro', for example, ;; top-level forms other than `defun' or `defmacro', for example,
;; ;;
;; (defun fg-defadvice-fum () ;; (defun fg-defadvice-fum ()
@ -1496,10 +1461,7 @@
;; if one advises a subr such as `eval-region' which then gets redefined by ;; 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, ;; 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 ;; 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 ;; the subr arguments in mind will break.
;; 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.
;; ;;
;; Argument access text macros allow one to access arguments of an advised ;; Argument access text macros allow one to access arguments of an advised
;; function in a portable way without having to worry about all these ;; function in a portable way without having to worry about all these
@ -1882,15 +1844,13 @@ generates a copy of TREE."
BODY-FORM...) BODY-FORM...)
On each iteration VAR will be bound to the name of an advised function On each iteration VAR will be bound to the name of an advised function
\(a symbol)." \(a symbol)."
(declare (indent 1))
`(cl-dolist (,(car varform) `(cl-dolist (,(car varform)
ad-advised-functions ad-advised-functions
,(car (cdr varform))) ,(car (cdr varform)))
(setq ,(car varform) (intern (car ,(car varform)))) (setq ,(car varform) (intern (car ,(car varform))))
,@body)) ,@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) (defun ad-get-advice-info (function)
(get function 'ad-advice-info)) (get function 'ad-advice-info))
@ -2117,7 +2077,7 @@ function at point for which PREDICATE returns non-nil)."
(lambda (function) (lambda (function)
;; Oops, no closures - the joys of dynamic scoping: ;; Oops, no closures - the joys of dynamic scoping:
;; `predicate' clashed with the `predicate' argument ;; `predicate' clashed with the `predicate' argument
;; of Lemacs' `completing-read'..... ;; of `completing-read'.....
(funcall ad-pReDiCaTe (intern (car function)))))) (funcall ad-pReDiCaTe (intern (car function))))))
t))) t)))
(if (equal function "") (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." ;;"non-nil if DEFINITION is a piece of advice."
`(eq (car-safe ,definition) '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) (defmacro ad-compiled-p (definition)
"Return non-nil if DEFINITION is a compiled byte-code object." "Return non-nil if DEFINITION is a compiled byte-code object."
`(or (byte-code-function-p ,definition) `(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 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 be a noop. Any modifications done to the definitions of FUNCTIONS will be
undone on exit of this macro." undone on exit of this macro."
(declare (indent 1))
(let* ((index -1) (let* ((index -1)
;; Make let-variables to store current definitions: ;; Make let-variables to store current definitions:
(current-bindings (current-bindings
@ -3735,14 +3690,6 @@ undone on exit of this macro."
,(car (nth index current-bindings))))) ,(car (nth index current-bindings)))))
functions)))))) 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: ;; @@ Starting, stopping and recovering from the advice package magic:
;; =================================================================== ;; ===================================================================