17.5 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. 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 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 Enabling and Disabling 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 (or anything but nil or a negative number), the command also compiles the combined definition which implements the advice. If it is nil or a negative number, what happens depends on ad-default-compilation-action as described below.

Command: ad-activate function &optional compile

This command activates all the advice defined for function.

Activating advice does nothing if function's advice is already active. But if there is new advice, added since the previous time you activated advice for function, it activates the new advice.

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; voir la section Enabling and Disabling Advice) since the last time it was activated.

Command: ad-start-advice

Turn on automatic advice activation when a function is defined or redefined. This is the default mode.

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 never 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) did not force compilation.

If the advised definition was constructed during “preactivation” (voir la section 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.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.