procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

* 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

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

@ -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 <hans@cs.buffalo.edu> 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 <documentation-string> 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:
;; ===================================================================