@chapter Advising Emacs Lisp Functions
@cindex advising functions
- The @dfn{advice} feature lets you add to the existing definition of
-a function, by @dfn{advising the function}. This is a cleaner method
-for a library to customize functions defined within Emacs---cleaner
-than redefining the whole function.
-
@cindex piece of advice
- Each function can have multiple @dfn{pieces of advice}, each of
-which can be separately defined and then @dfn{enabled} or
-@dfn{disabled}. All the enabled pieces of advice for any given
-function actually take effect when you @dfn{activate advice} for that
-function, or when you define or redefine the function. Note that
-enabling a piece of advice and activating advice for a function are
-not the same thing.
-
- Advice is useful for altering the behavior of existing calls to an
-existing function. If you want the new behavior for new function
-calls or new key bindings, you should define a new function or
-command, and have it use the existing function as a subroutine.
-
- Advising a function can cause confusion in debugging, since people
-who debug calls to the original function may not notice that it has
-been modified with advice. Therefore, if you have the possibility to
-change the code of that function to run a hook, please solve the
-problem that way. Advice should be reserved for the cases where you
-cannot get the function changed. In particular, Emacs's own source
-files should not put advice on functions in Emacs. There are
-currently a few exceptions to this convention, but we aim to correct
-them.
-
- Unless you know what you are doing, do @emph{not} advise a primitive
-(@pxref{What Is a Function}). Some primitives are used by the advice
-mechanism; advising them could cause an infinite recursion. Also,
-many primitives are called directly from C code. Calls to the
-primitive from Lisp code will take note of the advice, but calls from
-C code will ignore the advice.
+ The @dfn{advice} feature lets you add to the existing definition of
+a function, by @dfn{advising the function}. A function can have
+multiple @dfn{pieces of advice}, each of which can be separately
+defined, and separately enabled or disabled (@pxref{Activation of
+Advice}). Each piece of advice can alter almost anything about the
+function, including its argument list, what the function does when it
+runs, and the value it returns.
+
+ Advice can be useful for altering the behavior of an existing
+function without having to redefine the whole function. However, it
+can be a source of bugs, since existing callers to the function may
+assume the old behavior, and work incorrectly when the behavior is
+changed by advice. Advice can also cause confusion in debugging, if
+the person doing the debugging does not notice or remember that the
+function has been modified by advice.
+
+ For these reasons, advice should be reserved for the cases where you
+cannot modify a function's behavior in any other way. If it is
+possible to do the same thing via a hook, that is preferable
+(@pxref{Hooks}). If you simply want to change what a particular key
+does, it may be better to write a new command, and remap the old
+command's key bindings to the new one (@pxref{Remapping Commands}).
+In particular, Emacs's own source files should not put advice on
+functions in Emacs. (There are currently a few exceptions to this
+convention, but we aim to correct them.)
+
+ Macros can also be advised, in much the same way as functions.
+However, special forms (@pxref{Special Forms}) cannot be advised.
+
+ It is possible to advise a primitive (@pxref{What Is a Function}),
+but one should typically @emph{not} do so, for two reasons. Firstly,
+some primitives are used by the advice mechanism, and advising them
+could cause an infinite recursion. Secondly, many primitives are
+called directly from C, and such calls ignore advice; hence, one ends
+up in a confusing situation where some calls (occurring from Lisp
+code) obey the advice and other calls (from C code) do not.
@menu
* Simple Advice:: A simple example to explain the basics of advice.
@end example
@noindent
-Here, @var{function} is the name of the function (or macro or special
-form) to be advised. From now on, we will write just ``function'' when
-describing the entity being advised, but this always includes macros and
-special forms.
+Here, @var{function} is the name of the function (or macro) to be
+advised. From now on, we will write just ``function'' when describing
+the entity being advised, but this always includes macros.
In place of the argument list in an ordinary definition, an advice
definition calls for several different pieces of information.
;; {<after-K-1-body-form>}*
;; ad-return-value))
-;; Macros and special forms will be redefined as macros, hence the optional
-;; [macro] in the beginning of the definition.
+;; Macros are redefined as macros, hence the optional [macro] in the
+;; beginning of the definition.
;; <arglist> is either the argument list of the original function or the
;; first argument list defined in the list of before/around/after advices.
;; problems because they get expanded at compile or load time, hence, they
;; might not have all the necessary runtime support and such advice cannot be
;; de/activated or changed as it is possible for functions.
+;;
;; Special forms cannot be advised.
;;
;; MORAL: - Only advise macros when you are absolutely sure what you are doing.
;; flexibility and effectiveness of the advice mechanism. Macros that were
;; compile-time expanded before the advice was activated will of course never
;; exhibit the advised behavior.
-;;
-;; @@ Advising special forms:
-;; ==========================
-;; Now for something that should be even more rare than advising macros:
-;; Advising special forms. Because special forms are irregular in their
-;; argument evaluation behavior (e.g., `setq' evaluates the second but not
-;; the first argument) they have to be advised into macros. A dangerous
-;; consequence of this is that the byte-compiler will not recognize them
-;; as special forms anymore (well, in most cases) and use their expansion
-;; rather than the proper byte-code. Also, because the original definition
-;; of a special form cannot be `funcall'ed, `eval' has to be used instead
-;; which is less efficient.
-;;
-;; MORAL: Do not advise special forms unless you are completely sure about
-;; what you are doing (some of the forward advice behavior is
-;; implemented via advice of the special forms `defun' and `defmacro').
-;; As a safety measure one should always do `ad-deactivate-all' before
-;; one byte-compiles a file to avoid any interference of advised
-;; special forms.
-;;
-;; Apart from the safety concerns advising special forms is not any different
-;; from advising plain functions or subrs.
-
;;; Code:
projects / emacs.git / commitdiff