;;; 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:
;; - 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:
;;
;; @ 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:
;; @@ 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".
;; 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
;; 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
;; 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:
;; ===============================================
;; 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
;; 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:
;;
;; 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 ()
;; 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
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))
(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 "")
;;"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)
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
,(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:
;; ===================================================================
projects / emacs.git / commitdiff