Macro

Summary

Define a user declaration handler for code walkers.

Package

hcl

Signature

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

Arguments

decl-name

A symbol.

lambda-list

A list of two symbols.

body

One or more forms.

Values

decl-name

A symbol.

Description

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 declaration itself.
• The environment, which is the compilation environment in the compiler and the new environment in augment-environment.

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

:variable

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

:function

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

:declare

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.

Notes

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: http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node102.html.

See also

declare
declaration-information
function-information
variable-information
augment-environment
undefine-declaration