@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c Copyright (C) 1998-1999, 2001-2012 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
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
+ 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.
-
- @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.
+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.
@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
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
A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the
-advised definition. Access macros access actual arguments by position
-regardless of how these actual arguments get distributed onto the
-argument variables of a function. This is robust because in Emacs Lisp
-the meaning of an argument is strictly determined by its position in the
-argument list.
+advised definition. Access macros access actual arguments by their
+(zero-based) position, regardless of how these actual arguments get
+distributed onto the argument variables of a function. This is robust
+because in Emacs Lisp the meaning of an argument is strictly
+determined by its position in the argument list.
@defmac ad-get-arg position
This returns the actual argument that was supplied at @var{position}.
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 (also called a ``subr'') 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
executed even if some previous piece of advice had an error or a
non-local exit. If any around-advice is protected, then the whole
around-advice onion is protected as a result.
-
-@ignore
- arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
-@end ignore