comparison lispref/advice.texi @ 60261:dd9ce828300e

(Advising Functions): Don't imply one part of Emacs should advise another part. Markup changes. (Defining Advice): Move transitional para. (Activation of Advice): Cleanup. Explain if COMPILE is nil or negative.

60260:a8e0abd18501

@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
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
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.

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.

@cindex class of advice
@cindex before-advice
@cindex after-advice
@cindex around-advice
@var{class} specifies the @dfn{class} of the advice---one of @code{before},

symbol.  The advice name uniquely identifies one piece of advice, within all
the pieces of advice in a particular class for a particular
@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
a zero-based position (@code{first} is equivalent to 0).  If no position
is specified, the default is @code{first}.  Position values outside the

@section Activation of Advice
@cindex activating advice
@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 if 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.

are combined with the original definition to make a new definition.
(Pieces of advice that are currently disabled are not used; see
@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.

@deffn Command ad-activate function &optional compile
This command activates all the advice defined for @var{function}.
@end deffn

already loaded.  A value of @code{like-original} specifies to compile
the advice if the original definition of the advised function is
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.
@end defopt

  If the advised definition was constructed during ``preactivation''
(@pxref{Preactivation}), then that definition must already be compiled,
because it was constructed during byte-compilation of the file that

60261:dd9ce828300e

@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 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.

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.

  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
@cindex around-advice
@var{class} specifies the @dfn{class} of the advice---one of @code{before},

symbol.  The advice name uniquely identifies one piece of advice, within all
the pieces of advice in a particular class for a particular
@var{function}.  The name allows you to refer to the piece of
advice---to redefine it, or to enable or disable it.

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
a zero-based position (@code{first} is equivalent to 0).  If no position
is specified, the default is @code{first}.  Position values outside the

@section Activation of Advice
@cindex activating advice
@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.

are combined with the original definition to make a new definition.
(Pieces of advice that are currently disabled are not used; see
@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} (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

already loaded.  A value of @code{like-original} specifies to compile
the advice if the original definition of the advised function is
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) did not force
compilation.
@end defopt

  If the advised definition was constructed during ``preactivation''
(@pxref{Preactivation}), then that definition must already be compiled,
because it was constructed during byte-compilation of the file that