/[emacs]/emacs/lispref/advice.texi
ViewVC logotype

Diff of /emacs/lispref/advice.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.19 by rms, Wed Oct 27 14:54:18 2004 UTC revision 1.20 by rms, Sat Feb 26 23:49:49 2005 UTC
# Line 7  Line 7 
7  @chapter Advising Emacs Lisp Functions  @chapter Advising Emacs Lisp Functions
8  @cindex advising functions  @cindex advising functions
9    
10    The @dfn{advice} feature lets you add to the existing definition of a    The @dfn{advice} feature lets you add to the existing definition of
11  function, by @dfn{advising the function}.  This is a clean method for a  a function, by @dfn{advising the function}.  This is a clean method
12  library to customize functions defined by other parts of Emacs---cleaner  for a library to customize functions defined within Emacs---cleaner
13  than redefining the whole function.  than redefining the whole function.
14    
15  @cindex piece of advice  @cindex piece of advice
16    Each function can have multiple @dfn{pieces of advice}, separately    Each function can have multiple @dfn{pieces of advice}, separately
17  defined.  Each defined piece of advice can be @dfn{enabled} or  defined.  Each defined piece of advice can be @dfn{enabled} or
18  disabled explicitly.  All the enabled pieces of advice for any given  @dfn{disabled} explicitly.  All the enabled pieces of advice for any given
19  function actually take effect when you @dfn{activate} advice for that  function actually take effect when you @dfn{activate} advice for that
20  function, or when you define or redefine the function.  Note that  function, or when you define or redefine the function.  Note that
21  enabling a piece of advice and activating advice for a function  enabling a piece of advice and activating advice for a function
# Line 129  form) to be advised.  From now on, we wi Line 129  form) to be advised.  From now on, we wi
129  describing the entity being advised, but this always includes macros and  describing the entity being advised, but this always includes macros and
130  special forms.  special forms.
131    
132      In place of the argument list in an ordinary definition, an advice
133    definition calls for several different pieces of information.
134    
135  @cindex class of advice  @cindex class of advice
136  @cindex before-advice  @cindex before-advice
137  @cindex after-advice  @cindex after-advice
# Line 154  the pieces of advice in a particular cla Line 157  the pieces of advice in a particular cla
157  @var{function}.  The name allows you to refer to the piece of  @var{function}.  The name allows you to refer to the piece of
158  advice---to redefine it, or to enable or disable it.  advice---to redefine it, or to enable or disable it.
159    
 In place of the argument list in an ordinary definition, an advice  
 definition calls for several different pieces of information.  
   
160  The optional @var{position} specifies where, in the current list of  The optional @var{position} specifies where, in the current list of
161  advice of the specified @var{class}, this new advice should be placed.  advice of the specified @var{class}, this new advice should be placed.
162  It should be either @code{first}, @code{last} or a number that specifies  It should be either @code{first}, @code{last} or a number that specifies
# Line 332  replaced with the new one. Line 332  replaced with the new one.
332  @cindex advice, activating  @cindex advice, activating
333    
334  By default, advice does not take effect when you define it---only when  By default, advice does not take effect when you define it---only when
335  you @dfn{activate} advice for the function that was advised.  However  you @dfn{activate} advice for the function that was advised.  However,
336  the advice will be automatically activated if the function is defined  the advice will be activated automatically if you define or redefine
337  or redefined later.  You can request the activation of advice for a  the function later.  You can request the activation of advice for a
338  function when you define the advice, by specifying the @code{activate}  function when you define the advice, by specifying the @code{activate}
339  flag in the @code{defadvice}.  But normally you activate the advice  flag in the @code{defadvice}.  But normally you activate the advice
340  for a function by calling the function @code{ad-activate} or one of  for a function by calling the function @code{ad-activate} or one of
# Line 353  are combined with the original definitio Line 353  are combined with the original definitio
353  @ref{Enabling Advice}.)  This definition is installed, and optionally  @ref{Enabling Advice}.)  This definition is installed, and optionally
354  byte-compiled as well, depending on conditions described below.  byte-compiled as well, depending on conditions described below.
355    
356  In all of the commands to activate advice, if @var{compile} is @code{t},  In all of the commands to activate advice, if @var{compile} is
357  the command also compiles the combined definition which implements the  @code{t} (or anything but @code{nil} or a negative number), the
358  advice.  command also compiles the combined definition which implements the
359    advice.  If it is @code{nil} or a negative number, what happens
360    depends on @code{ad-default-compilation-action} as described below.
361    
362  @deffn Command ad-activate function &optional compile  @deffn Command ad-activate function &optional compile
363  This command activates all the advice defined for @var{function}.  This command activates all the advice defined for @var{function}.
# Line 438  the advice if the original definition of Line 440  the advice if the original definition of
440  compiled or a built-in function.  compiled or a built-in function.
441    
442  This variable takes effect only if the @var{compile} argument of  This variable takes effect only if the @var{compile} argument of
443  @code{ad-activate} (or any of the above functions) was supplied as  @code{ad-activate} (or any of the above functions) did not force
444  @code{nil}.  If that argument is non-@code{nil}, that means  compilation.
 to compile the advice regardless.  
445  @end defopt  @end defopt
446    
447    If the advised definition was constructed during ``preactivation''    If the advised definition was constructed during ``preactivation''

Legend:
Removed from v.1.19  
changed lines
  Added in v.1.20

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26