To define a piece of advice, use the macro
defadvice. A call
defadvice has the following syntax, which is based on the
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.
In place of the argument list in an ordinary definition, an advice definition calls for several different pieces of information.
class specifies the class of the advice—one of
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
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-
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.
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
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 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 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:
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.
unwind-protectform, so that it will execute even if the previous code gets an error or uses
throw. See Cleanups.
activateis also specified. See Combined Definition.
defadviceis compiled or macroexpanded. This generates a compiled advised definition according to the current advice state, which will be used during activation if appropriate. See 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.