GNU Info
(elisp)Defining Advice
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 (Note: 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.
Note: 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'. Note:
Cleanups.
`compile'
Compile the combined definition that is used to run the advice.
This flag is ignored unless `activate' is also specified. Note:
Combined Definition.
`disable'
Initially disable this piece of advice, so that it will not be used
unless subsequently explicitly enabled. Note: Enabling 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. Note: 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.
automatically generated by info2www version 1.2.2.9