@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+@c Copyright (C) 1998, 1999, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/advising
@node Advising Functions, Debugging, Byte Compilation, Top
@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 clean method for a
-library to customize functions defined by other parts of Emacs---cleaner
+ 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
-disabled explicitly. All the enabled pieces of advice for any given
+@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
@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, it is cleaner to define a new
-function (or a new command) which uses the existing function.
+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.
@menu
* Simple Advice:: A simple example to explain the basics of advice.
Suppose you wanted to add a similar feature to @code{previous-line},
which would insert a new line at the beginning of the buffer for the
-command to move to. How could you do this?
+command to move to (when @code{next-line-add-newlines} is
+non-@code{nil}). How could you do this?
You could do it by redefining the whole function, but that is not
modular. The advice feature provides a cleaner alternative: you can
this:
@example
-(defadvice previous-line (before next-line-at-end (arg))
+(defadvice previous-line (before next-line-at-end
+ (&optional arg try-vscroll))
"Insert an empty line when moving up from the top line."
(if (and next-line-add-newlines (= arg 1)
(save-excursion (beginning-of-line) (bobp)))
@code{previous-line}. This piece of advice is named
@code{next-line-at-end}, and the symbol @code{before} says that it is
@dfn{before-advice} which should run before the regular definition of
-@code{previous-line}. @code{(arg)} specifies how the advice code can
-refer to the function's arguments.
+@code{previous-line}. @code{(&optional arg try-vscroll)} specifies
+how the advice code can refer to the function's arguments.
When this piece of advice runs, it creates an additional line, in the
situation where that is appropriate, but does not move point to that
describing the entity being advised, but this always includes macros and
special forms.
+ In place of the argument list in an ordinary definition, an advice
+definition calls for several different pieces of information.
+
@cindex class of advice
@cindex before-advice
@cindex after-advice
@var{function}. The name allows you to refer to the piece of
advice---to redefine it, or to enable or disable it.
-In place of the argument list in an ordinary definition, an advice
-definition calls for several different pieces of information.
-
The optional @var{position} specifies where, in the current list of
advice of the specified @var{class}, this new advice should be placed.
It should be either @code{first}, @code{last} or a number that specifies
searches when the original definition of @code{foo} is run.
@defvar ad-do-it
-This is not really a variable, but it is somewhat used like one
-in around-advice. It specifies the place to run the function's
-original definition and other ``earlier'' around-advice.
+This is not really a variable, rather a place-holder that looks like a
+variable. You use it in around-advice to specify the place to run the
+function's original definition and other ``earlier'' around-advice.
@end defvar
If the around-advice does not use @code{ad-do-it}, then it does not run
@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 automatically activated when the function is
-defined or redefined 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 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.
Separating the activation of advice from the act of defining it permits
you to add several pieces of advice to one function efficiently, without
@ref{Enabling Advice}.) This definition is installed, and optionally
byte-compiled as well, depending on conditions described below.
-In all of the commands to activate advice, if @var{compile} is @code{t},
-the command also compiles the combined definition which implements the
-advice.
+In all of the commands to activate advice, if @var{compile} is
+@code{t} (or anything but @code{nil} or a negative number), the
+command also compiles the combined definition which implements the
+advice. If it is @code{nil} or a negative number, what happens
+depends on @code{ad-default-compilation-action} as described below.
@deffn Command ad-activate function &optional compile
This command activates all the advice defined for @var{function}.
@end deffn
-To activate advice for a function whose advice is already active is not
-a no-op. It is a useful operation which puts into effect any changes in
-that function's advice since the previous activation of advice for that
-function.
+ Activating advice does nothing if @var{function}'s advice is already
+active. But if there is new advice, added since the previous time you
+activated advice for @var{function}, it activates the new advice.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
@deffn Command ad-start-advice
Turn on automatic advice activation when a function is defined or
-redefined. This mode is turned on by default.
+redefined. This is the default mode.
@end deffn
@deffn Command ad-stop-advice
that results from activating advice for a function.
A value of @code{always} specifies to compile unconditionally.
-A value of @code{nil} specifies never compile the advice.
+A value of @code{never} specifies never compile the advice.
A value of @code{maybe} specifies to compile if the byte-compiler is
already loaded. A value of @code{like-original} specifies to compile
compiled or a built-in function.
This variable takes effect only if the @var{compile} argument of
-@code{ad-activate} (or any of the above functions) was supplied as
-@code{nil}. If that argument is non-@code{nil}, that means
-to compile the advice regardless.
+@code{ad-activate} (or any of the above functions) did not force
+compilation.
@end defopt
If the advised definition was constructed during ``preactivation''
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