| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: fspec class name position &rest forms
Starting in Allegro CL release 6.0, the new fwrapper facility, described in fwrappers-and-advice.htm, replaces the advice facility, and continued use of the advice facility is deprecated.
None of the arguments are evaluated. This macro advises the function fspec appropriately with code defined by the forms.
fspec specifies the function (or macro) to advise. This argument is normally a symbol but it can be any function name (see implementation.htm). See fwrappers-and-advice.htm for information on advising macros. The information in the remainder of this definition relates to functions only.
class specifies the type of advice. The three
choices are :before
, :around
, and
:after
. :before
advice will be evaluated
before the advised function is called; :around
advice
will be evaluated around the calling of the advised function (in the
sense that the call to the function will be embedded within the
:around
code); :after
advice will be
evaluated after the advised function has been called. See below for
more information on classes of advice.
name specifies the name of the advice. Its
value may be nil
, but it is convenient to refer to advice by
name. Note that there can be only one piece of advice of each class
with a given name. (But there may be as many as you like without a
name, i.e. with nil
as the specified name.) If more advice is defined
with the same name and class as existing advice, the new advice will
replace the existing advice, thus taking its place.
position specifies the location of advice relative to other advice of the same class on the same function. The important point about this argument is that it is used only when the advice is first defined and is then forgotten. Therefore, the position is calculated with respect to already existing advice of the same class, whose positions are 0, 1, 2... regardless of the value of the position argument when they were defined. See fwrappers-and-advice.htm for examples that further explain this point.
There can be many pieces of advice of each class on a
function. position specifies where the piece of
advice currently being defined will go. position
may be a non-negative integer, a name or nil
. If it is a number, then the lower the number,
the farther the advice will be from the actual evaluation of the forms
defining the function itself. Thus for :before
and
:around
advice, advice 0 will be run first, then 1,
2, 3, and so on, while for :after
advice, advice 0
will be run last, preceded by 1, 2, 3, and so on. Say there are n
pieces of advice of the class of the advice being defined. The
existing advice is numbered 0, 1, 2, ..., n-
1,
inclusive. Then a position of 0 will result in the new advice being
placed farther from the function call than all the rest of the advice,
a position of k
where k
is
between 1 and n-1
will be placed farther then the
k
th piece of existing advice, and a position
n
or larger will be placed nearest the function
call.
If position is nil
, the
advice is put farther from the function call then all
currently-defined advice of the same class. If position is a name of
existing advice, the advice will be placed next farther from the
function call (before for :before
and
:around
, after for :after
) than
the named advice. Note that if new advice has the same name and class
as existing advice, it will replace the existing advice and take the
position of the existing advice. In that case, the position argument
will be ignored.
forms are the actual forms that will be
evaluated. All advice on a function is combined in an enclosing
cl:prog, so a return placed anywhere in any type of advice will
cause the advised function to return with the values specified with
the return, without any further advice code being evaluated and (if it
has not already done so) without the advised function being
evaluated. Syntactically, :around
advice should be
a single form. If multiple forms are specified, however, they are
automatically wrapped in a cl:progn. Warning:
forms cannot be the single form nil
. If you want the single form nil
(in, for example, :around advice to not call the
function and return nil
), specify
(progn nil)
instead.
:before
advice will be evaluated before the function
call. The argument list with which the function was called is
available to :before
advice. The argument list is stored
as the value of the variable excl:arglist
(this symbol
also names a function which returns the arguments list of an
operator). You may check the values in this list, change the values or
replace the list altogether with a new list. (If you replace the list,
be careful that it have the correct format for the function -- number
and types of arguments in the list -- or you may get an error, or
worse, a wrong result but no error.) :before
advice is
used only for its side effects. Any value returned by
:before
advice code is ignored.
:around
advice places the function call inside the
code of the advice. The keyword :do-it
signals where the
function should be called within the advice code. When Lisp encounters
the :do-it
, it calls the next piece of
:around
advice, if there is more, or the function. When
the function returns, the :around
advice code continues
execution. :do-it
may appear several times in
:around
advice. Normally, it is placed in conditional
code, as shown in this code fragment:
(advise myfunction :around example nil (... [do stuff before function call in :around advice code] (if (zerop (car excl:arglist)) (+ 5 :do-it) (* 7 :do-it)) ... [do stuff after function call] ))
In that case, the system will encounter one or the other
:do-it
, but not both. However, it is allowed to
have several :do-it
s all of which are evaluated. In
that case, the succeeding :around
advice and the
advised function are evaluated more than
once. :after
advice is still evaluated only once,
however. :around
advice can work with
excl:arglist
before the
:do-it
. Since the advised function is run at the
location specified by the :do-it
, the values the
function return are available to :around
advice
just like with any function call. The list bound to the variable
values
is not set up until after all
:around
advice is run, then
values
is bound to the list of values returned by
the final piece of :around
advice. Note that if
the function returns multiple values, these should be caught with
multiple-value-bind or multiple-value-list or some similar
function if you are interested in the values beyond the first.
advice is evaluated after the function has completed, but before
control is passed back to whatever called the
function. :after
advice may examine and change the list
of returned values from the last piece of :around
advice
(or the function, if there is no :around
advice) stored
in the variable values
. :after
advice is
used only for its side effects. Any value returned by the
:after
advice code is ignored. The list bound to
values
is returned from the now completed function
call.
See also fwrappers-and-advice.htm for general information on the new fwrapper facility and the older, now deprecated, advice facility in Allegro CL.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |