GNU Info

(elisp)Activation of Advice

---

Next: Enabling Advice Prev: Computed Advice Up: Advising Functions

---

Enter node , (file) or (file)node

Activation of Advice
====================

   By default, advice does not take effect when you define it--only when
you "activate" advice for the function that was advised.  You can
request the activation of advice for a function when you define the
advice, by specifying the `activate' flag in the `defadvice'.  But
normally you activate the advice for a function by calling the function
`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 redefining the function over and over as each
advice is added.  More importantly, it permits defining advice for a
function before that function is actually defined.

   When a function's advice is first activated, the function's original
definition is saved, and all enabled pieces of advice for that function
are combined with the original definition to make a new definition.
(Pieces of advice that are currently disabled are not used; see Note:
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 COMPILE is `t', the
command also compiles the combined definition which implements the
advice.

 - Command: ad-activate function &optional compile
     This command activates all the advice defined for FUNCTION.

   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.

 - Command: ad-deactivate function
     This command deactivates the advice for FUNCTION.

 - Command: ad-update function &optional compile
     This command activates the advice for FUNCTION if its advice is
     already activated.  This is useful if you change the advice.

 - Command: ad-activate-all &optional compile
     This command activates the advice for all functions.

 - Command: ad-deactivate-all
     This command deactivates the advice for all functions.

 - Command: ad-update-all &optional compile
     This command activates the advice for all functions whose advice
     is already activated.  This is useful if you change the advice of
     some functions.

 - Command: ad-activate-regexp regexp &optional compile
     This command activates all pieces of advice whose names match
     REGEXP.  More precisely, it activates all advice for any function
     which has at least one piece of advice that matches REGEXP.

 - Command: ad-deactivate-regexp regexp
     This command deactivates all pieces of advice whose names match
     REGEXP.  More precisely, it deactivates all advice for any
     function which has at least one piece of advice that matches
     REGEXP.

 - Command: ad-update-regexp regexp &optional compile
     This command activates pieces of advice whose names match REGEXP,
     but only those for functions whose advice is already activated.

     Reactivating a function's advice is useful for putting into effect
     all the changes that have been made in its advice (including
     enabling and disabling specific pieces of advice; Note: Enabling
     Advice) since the last time it was activated.

 - Command: ad-start-advice
     Turn on automatic advice activation when a function is defined or
     redefined.  If you turn on this mode, then advice takes effect
     immediately when defined.

 - Command: ad-stop-advice
     Turn off automatic advice activation when a function is defined or
     redefined.

 - User Option: ad-default-compilation-action
     This variable controls whether to compile the combined definition
     that results from activating advice for a function.

     A value of `always' specifies to compile unconditionally.  A value
     of `nil' specifies never compile the advice.

     A value of `maybe' specifies to compile if the byte-compiler is
     already loaded.  A value of `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 COMPILE argument of
     `ad-activate' (or any of the above functions) was supplied as
     `nil'.  If that argument is non-`nil', that means to compile the
     advice regardless.

   If the advised definition was constructed during "preactivation"
(Note: Preactivation), then that definition must already be compiled,
because it was constructed during byte-compilation of the file that
contained the `defadvice' with the `preactivate' flag.