augment-environment Function

Summary

Returns a new environment based on an existing one with different bindings.

Package

hcl

Signature

augment-environment env &key variable symbol-macro function macro declare reset => newenv

Arguments

Values

Description

The function augment-environment returns a new environment newenv, based on env but modified according to the keyword arguments variable, symbol-macro, function, macro, declare and reset.

If env is nil, then newenv will be based on the null environment. Otherwise, if reset is false (the default) then all of the bindings in env will be present in newenv unless overridden by the other keyword arguments. Otherwise, if reset is true then all of the non-local bindings in env will be present in newenv but none of the local bindings will be present. Passing reset as true allows you to create an environment object for calls to variable-information and so on which can access the file compilation environment without seeing local bindings in the lexical environment.

variable should be a list of symbols and newenv will contain these symbols as local variable bindings. A binding will be a special binding if the symbol is declared special non-lexically in env or a special declaration is present in declare.

symbol-macro should be a list of lists of the form (symbol expansion) and newenv will contain local symbol-macro bindings for each symbol with expansion as its macroexpansion.

function should be a list of function names and newenv will contain these symbols as local function bindings.

macro should be a list of lists of the form (symbol macrofunction) and newenv will contain local macro bindings for each symbol with macrofunction as its macroexpansion function. Each macrofunction is a function of two arguments, a form and an environment, which should return the expanded form.

declare should be a list of declaration-specifiers, which will be added to newenv as if by declare.

It is an error to use a symbol in symbol-macro that is also in variable or is declared special.

It is an error to use a symbol in macro that is also in function.

newenv has the same extent as env, that is it might have dynamic extent within the function that created env.

The lists passed to augment-environment should be not destructively modified afterwards.

Notes

augment-environment is part of the environment access API which is based on that specified in Common Lisp: the Language (2nd Edition).

See also

declaration-information
define-declaration
function-information
map-environment
variable-information