defadvice

defadvice Macro

Summary

Defines a new piece of advice.

Package

lispworks

Signature

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

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

Arguments

`function-dspec`⇩	A function dspec.
`name`⇩	A symbol.
`where`⇩	Either `:start` or `:end`.
`documentation`⇩	A string or `nil`.
`lambda-list`⇩	A lambda list.
`body`⇩	Forms.

Description

The macro defadvice is the macro used to define a new piece of advice for function-dspec. See 7.5.1 Function dspecs for description of function dspecs.

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 using defadvice.

When function-dspec names a macro, 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.

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 to call-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.

name is used to name the advice. It should be unique to the advised function, but does not need to be globally unique. If you use the same name again then the advise will be redefined.

advice-type specifies 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 supplied 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 provides documentation on the piece of advice.

lambda-list is the 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 is main body of the advice.

Remove advice using remove-advice or delete-advice.

Notes

defadvice is an extension to Common Lisp.