12 The LISPWORKS Package

defadvice

Macro

Summary

Defines a new piece of advice.

Package

lispworks

Signature

defadvice (dspec name advice-type &key where documentation)
            lambda-list &body body => nil

dspec ::= fn-name |
         macro-name |
         (method generic-fn-name [(class*)])   

advice-type ::= :before |:after |:around

Arguments

dspec

Specifies the functional definition to which the piece of advice belongs. There are three forms which this specification may take. The first one above specifies a function by its name; the second one specifies a macro by name; the third specifies a method by the name of its generic function and by a list of classes to specialize the arguments to the method. In the case of a method the list of classes must correspond exactly to the classes of the specialized parameters of an existing method, and the advice is then attached to this method.

When advice is provided for a macro usingdefadvice, then the function with which the advice is associated is the expansion function for that macro. Thus before and after advice for a macro receive the arguments given to the macro expansion function, which are normally the macro call form and an environment.

name

A symbol naming the piece of advice being created. It should of course be unique to the advised function, but does not need to be globally unique.

advice-type

A keyword specifying the kind of advice wanted.

where

Specifies where this advice should be placed in the ordering of pieces of advice for the function. By default a piece of advice is placed at the start of the corresponding section. If this argument is present and is:end then the advice is instead placed at the end of its section. The other permissible value for this argument is:start, which places the advice at the start of its section in the ordering (as in the default behavior).

documentation

A string providing documentation on the piece of advice.

lambda-list

A lambda list for the piece of advice. In the case of before and after advice this should be compatible with the lambda-list for the original definition, since such advice receives the same arguments as that function.

body

The main body of the advice.

Values

defadvice returnsnil.

Description

defadvice is the macro used to define a new piece of advice. Advice provides a way to change the behavior of existing functional definitions in the system. In a simple instance advice might be used to carry out some additional actions before or after the original definition. More sophisticated uses allow the definition to be replaced by new code that can access the original function repeatedly or as rarely as desired, and that can receive different numbers of arguments and return any values. A function may have any number of pieces of advice attached to it by usingdefadvice.

There are three kinds of advice that may be defined: before, after and around advice. The first two kinds attach auxiliary code to be carried out alongside the original definition (before it for before advice, after it in the case of after advice). Around advice replaces the function altogether; it may define code that never accesses the original definition, that receives different numbers of arguments, and returns different values. All the pieces of advice for a function are ordered. The ordering is important in determining how all the pieces of advice for a function are combined. Around advice always comes first, then before advice, then the original definition, and lastly the after advice.

Conceptually the before advice, the original definition and the after advice are amalgamated into one new construct. If this gets called then each of its components receives the same arguments in turn, and the values returned are those produced by the last piece of after advice to be called in this way (or the original function if there is no after advice). The code associated with before and after advice should not destructively modify its arguments.

If around advice is present then the first piece of around advice is called, instead of the combination involving before and after advice discussed above. It does not have to access any of the other advice, nor the original definition. Its only link to the rest of the advice is by means of a call tocall-next-advice. It may invoke this as often as it chooses, and by doing so it accesses the next piece of around advice if present, or else it accesses the combination of before and after advice together with the original definition.

Notes

defadvice is an extension to Common Lisp.