17.2 Defining Advice

To define a piece of advice, use the macro defadvice. A call to defadvice has the following syntax, which is based on the syntax of defun and defmacro, but adds more:

(defadvice function (class name [position] [arglist] flags...) [documentation-string] [interactive-form] body-forms...)

Here, 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.

class specifies the class of the advice--one of before, after, or around. Before-advice runs before the function itself; after-advice runs after the function itself; around-advice is wrapped around the execution of the function itself. After-advice and around-advice can override the return value by setting ad-return-value.

Variable: ad-return-value

While advice is executing, after the function's original definition has been executed, this variable holds its return value, which will ultimately be returned to the caller after finishing all the advice. After-advice and around-advice can arrange to return some other value by storing it in this variable.

The argument name is the name of the advice, a non-nil symbol. The advice name uniquely identifies one piece of advice, within all the pieces of advice in a particular class for a particular 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 position specifies where, in the current list of advice of the specified class, this new advice should be placed. It should be either first, last or a number that specifies a zero-based position (first is equivalent to 0). If no position is specified, the default is first. Position values outside the range of existing positions in this class are mapped to the beginning or the end of the range, whichever is closer. The position value is ignored when redefining an existing piece of advice.

The optional arglist can be used to define the argument list for the sake of advice. This becomes the argument list of the combined definition that is generated in order to run the advice (see section 17.10 The Combined Definition). Therefore, the advice expressions can use the argument variables in this list to access argument values.

The argument list used in advice need not be the same as the argument list used in the original function, but must be compatible with it, so that it can handle the ways the function is actually called. If two pieces of advice for a function both specify an argument list, they must specify the same argument list.

See section 17.8 Argument Access in Advice, for more information about argument lists and advice, and a more flexible way for advice to access the arguments.

The remaining elements, flags, are symbols that specify further information about how to use this piece of advice. Here are the valid symbols and their meanings:

activate

Activate the advice for function now. Changes in a function's advice always take effect the next time you activate advice for the function; this flag says to do so, for function, immediately after defining this piece of advice.

This flag has no immediate effect if function itself is not defined yet (a situation known as forward advice), because it is impossible to activate an undefined function's advice. However, defining function will automatically activate its advice.

protect

Protect this piece of advice against non-local exits and errors in preceding code and advice. Protecting advice places it as a cleanup in an unwind-protect form, so that it will execute even if the previous code gets an error or uses throw. See section 10.5.4 Cleaning Up from Nonlocal Exits.

compile

Compile the combined definition that is used to run the advice. This flag is ignored unless activate is also specified. See section 17.10 The Combined Definition.

disable

Initially disable this piece of advice, so that it will not be used unless subsequently explicitly enabled. See section 17.6 Enabling and Disabling Advice.

preactivate

Activate advice for function when this defadvice is compiled or macroexpanded. This generates a compiled advised definition according to the current advice state, which will be used during activation if appropriate. See section 17.7 Preactivation.

This is useful only if this defadvice is byte-compiled.

The optional documentation-string serves to document this piece of advice. When advice is active for function, the documentation for function (as returned by documentation) combines the documentation strings of all the advice for function with the documentation string of its original function definition.

The optional interactive-form form can be supplied to change the interactive behavior of the original function. If more than one piece of advice has an interactive-form, then the first one (the one with the smallest position) found among all the advice takes precedence.

The possibly empty list of body-forms specifies the body of the advice. The body of an advice can access or change the arguments, the return value, the binding environment, and perform any other kind of side effect.

Warning: When you advise a macro, keep in mind that macros are expanded when a program is compiled, not when a compiled program is run. All subroutines used by the advice need to be available when the byte compiler expands the macro.

Command: ad-unadvise function

This command deletes the advice from function.

Command: ad-unadvise-all

This command deletes all pieces of advice from all functions.