13. Environments

13.1 Environment Operations
13.2 Environment Variables
13.3 REPL Environment
13.4 Interpreter Environments

13.1 Environment Operations

Environments are first-class objects in MIT Scheme. An environment consists of some bindings and possibly a parent environment, from which other bindings are inherited. The operations in this section reveal the frame-like structure of environments by permitting you to examine the bindings of a particular environment separately from those of its parent.

procedure+: environment? object

Returns #t if object is an environment; otherwise returns #f.

procedure+: environment-has-parent? environment

Returns #t if environment has a parent environment; otherwise returns #f.

procedure+: environment-parent environment

Returns the parent environment of environment. It is an error if environment has no parent.

procedure+: environment-bound-names environment

Returns a newly allocated list of the names (symbols) that are bound by environment. This does not include the names that are bound by the parent environment of environment.

procedure+: environment-bindings environment

Returns a newly allocated list of the bindings of environment; does not include the bindings of the parent environment. Each element of this list takes one of two forms: (name) indicates that name is bound but unassigned, while (name object) indicates that name is bound, and its value is object.

procedure+: environment-bound? environment symbol

Returns #t if symbol is bound in environment or one of its ancestor environments; otherwise returns #f.

procedure+: environment-lookup environment symbol

Symbol must be bound in environment or one of its ancestor environments. Returns the value to which it is bound.

procedure+: environment-assignable? environment symbol

Symbol must be bound in environment or one of its ancestor environments. Returns #t if the binding may be modified by side effect.

procedure+: environment-assign! environment symbol object

Symbol must be bound in environment or one of its ancestor environments, and must be assignable. Modifies the binding to have object as its value, and returns an unspecified result.

procedure+: eval expression environment

Evaluates expression, a list-structure representation (sometimes called s-expression representation) of a Scheme expression, in environment. You rarely need eval in ordinary programs; it is useful mostly for evaluating expressions that have been created "on the fly" by a program. eval is relatively expensive because it must convert expression to an internal form before it is executed.

(define foo (list '+ 1 2)) (eval foo (the-environment)) => 3

13.2 Environment Variables

The user-initial-environment is where the top-level read-eval-print (REP) loop evaluates expressions and stores definitions. It is a child of the system-global-environment, which is where all of the Scheme system definitions are stored. All of the bindings in system-global-environment are available when the current environment is user-initial-environment. However, any new bindings that you create in the REP loop (with define forms or by loading files containing define forms) occur in user-initial-environment.

variable+: system-global-environment

The variable system-global-environment is bound to the environment that's the parent of the user-initial-environment. Primitives and system procedures are bound (and sometimes closed) in this environment.

variable+: user-initial-environment

The variable user-initial-environment is bound to the default environment in which typed expressions are evaluated by the top-level REP loop.

Although all bindings in system-global-environment are visible to the REP loop, definitions that are typed at, or loaded by, the REP loop occur in the user-initial-environment. This is partly a safety measure: if you enter a definition that happens to have the same name as a critical system procedure, your definition will be visible only to the procedures you define in the user-initial-environment; the MIT Scheme system procedures, which are defined in the system-global-environment, will continue to see the original definition.

13.3 REPL Environment

procedure+: nearest-repl/environment

Returns the current REP loop environment (i.e. the current environment of the closest enclosing REP loop). When Scheme first starts up, this is the same as user-initial-environment.

procedure+: ge environment

Changes the current REP loop environment to environment. Environment can be either an environment or a procedure object. If it's a procedure, the environment in which that procedure was closed is the new environment.

13.4 Interpreter Environments

The operations in this section return environments that are constructed by the interpreter. These operations should only be used at the top level of a file; they are not supported in any other place. In particular, they force the current environment to be represented in a form suitable for use by the interpreter. This prevents the compiler from performing many useful optimizations on such environments, and forces the use of the interpreter for variable references in them. However, because all top-level environments (such as user-initial-environment) are already interpreter environments, it does no harm to use such operations on them.

Warning: A future release of MIT Scheme will support hygienic macros, which are incompatible with non-top-level instances of make-environment and the-environment. At that time, other uses of these constructs will be disallowed.

special form+: make-environment expression ...

Produces a new environment that is a child of the environment in which it is executed, evaluates the expressions sequentially in the new environment, and returns the new environment. Note that

(make-environment expression ...)

is equivalent to:

(let () expression ... (the-environment))

special form+: the-environment

Returns the current environment.

procedure+: interpreter-environment? object

Returns #t if object is an interpreter environment; otherwise returns #f.