All Manuals > LispWorks® User Guide and Reference Manual > 37 The HCL Package

define-declaration Macro


Define a user declaration handler for code walkers.




define-declaration decl-name lambda-list &rest body => decl-name

A symbol.
A list of two symbols.
One or more forms.
A symbol.

The macro define-declaration defines a handler for decl-name, which tells the compiler and augment-environment how to deal with this declaration. The handler is a function with lambda list lambda-list, and body body, that is the same function as would be produced by:

#'(lambda lambda-list . body)

When the compiler and augment-environment processes a declaration with decl-name as the first element, the handler is called with two arguments:

The handler must return two values. The first value specifies what kind of declaration it is, and must be one of:

The declaration applies to variable bindings, and hence affects the result of variable-information.
The declaration applies to function bindings, and hence affects the result of function-information .
The declaration does not apply to bindings, and affects the result of declaration-information.

If the first value is :variable or :function then the second value must be a list, the elements of which are lists of the form (binding-name key value). If the corresponding information function (either variable-information or function-information) is called with binding-name and the environment, then the a-list returned by the information function as its third value will have value associated with key.

If the first value is :declare, then the second value must be a cons of the form (key . value). The function declaration-information will return value when called with key and the environment.

define-declaration causes decl-name to be proclaimed as a declaration, as if by:

(proclaim '(declaration decl-name))

decl-name must not be a standard declaration identifier; define-declaration signals an error if it is.

The consequences are undefined if a key returned by a declaration handler defined with define-declaration is a symbol that is used by the corresponding information function to return information about any standard declaration specifier. For example, if the first return value from the handler is :variable, then the second return value should not use the symbols dynamic-extent, ignore, or type as key, because they are reserved by variable-information to return information about the corresponding standard declaration.


Using a declaration defined by define-declaration affects only the return values of variable-information, function-information or declaration-information as described above. It does not affect the behavior of the compiler. define-declaration is intended for use by code walkers that require extra information in the environment.

The evaluator ignores declarations defined by define-declaration.

define-declaration does not have any compile-time effect so must have be evaluated before a declaration for decl-name is processed.

augment-environment processes declarations last, so the environment that is passed to the handler already contain any other information that was passed to augment-environment.

The implementation of define-declaration is based on the specification in Common Lisp the Language, 2nd Edition as on CMU website on 10 Feb 2016:

See also


LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:35