@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1998-1999, 2001-2014 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/advising
-@node Advising Functions, Debugging, Byte Compilation, Top
+@node Advising Functions
@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}, separately
-defined. Each defined piece of advice can be @dfn{enabled} or
-@dfn{disabled} explicitly. 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.
-
- @strong{Usage Note:} Advice is useful for altering the behavior of
-existing calls to an existing function. If you want the new behavior
-for new calls, or for key bindings, you should define a new function
-(or a new command) which uses the existing function.
-
- @strong{Usage note:} 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 (or ask
-someone to do so) 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, this means that a file in Emacs should not put advice
-on a function in Emacs. There are currently a few exceptions to this
-convention, but we aim to correct them.
+ 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.
* Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments.
-* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
@end menu
@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.
compiler expands the macro.
@deffn Command ad-unadvise function
-This command deletes the advice from @var{function}.
+This command deletes all pieces of advice from @var{function}.
@end deffn
@deffn Command ad-unadvise-all
@cindex advice, activating
By default, advice does not take effect when you define it---only when
-you @dfn{activate} advice for the function that was advised. However,
-the advice will be activated automatically if you define or redefine
-the function later. You can request the activation of advice for a
-function when you define the advice, by specifying the @code{activate}
-flag in the @code{defadvice}. But normally you activate the advice
-for a function by calling the function @code{ad-activate} or one of
-the other activation commands listed below.
+you @dfn{activate} advice for the function. However, the advice will
+be activated automatically if you define or redefine the function
+later. You can request the activation of advice for a function when
+you define the advice, by specifying the @code{activate} flag in the
+@code{defadvice}; or you can activate the advice separately by calling
+the function @code{ad-activate} or one of the other activation
+commands listed below.
Separating the activation of advice from the act of defining it permits
you to add several pieces of advice to one function efficiently, without
These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism.
-@node Advising Primitives
-@section Advising Primitives
-@cindex advising primitives
-
- Advising a primitive function (@pxref{What Is a Function}) is risky.
-Some primitive functions are used by the advice mechanism; advising
-them could cause an infinite recursion. Also, many primitive
-functions 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.
-
-When the advice facility constructs the combined definition, it needs
-to know the argument list of the original function. This is not
-always possible for primitive functions. When advice cannot determine
-the argument list, it uses @code{(&rest ad-subr-args)}, which always
-works but is inefficient because it constructs a list of the argument
-values. You can use @code{ad-define-subr-args} to declare the proper
-argument names for a primitive function:
-
-@defun ad-define-subr-args function arglist
-This function specifies that @var{arglist} should be used as the
-argument list for function @var{function}.
-@end defun
-
-For example,
-
-@example
-(ad-define-subr-args 'fset '(sym newdef))
-@end example
-
-@noindent
-specifies the argument list for the function @code{fset}.
-
@node Combined Definition
@section The Combined Definition
HCoop / bpt / emacs.git / blobdiff