doc.txt

Environment

_Environment_
_environment_

Richard Cobbe
<cobbe at ccs dot neu dot edu>

This collection provides two files:

  _environment.ss_: implements a standard functional rib-cage environment
                    structure. 
  _environment-tests.ss_: SchemeUnit (q.v.) tests for environment.ss.

This environment structure accepts any kind of value as an `identifier',
although the interface has been designed around the assumption that
symbolic identifiers are the most common case.

======================================================================

> (make-empty-env)

Creates an environment with no bindings.

> (extend-env env ids values)

Returns a new environment containing all bindings in env, but extended with
the specified bindings.  For example,

    (extend-env (make-empty-env) '(a b) '(3 4))

produces an environment in which 'a is bound to 3 and 'b is bound to 4.
The bindings added by this function shadow those in env, as one would
expect, and bindings earlier in the argument lists shadow those later in
the same lists.

> (env (id val) ...)

This macro creates an environment containing exactly the specified
bindings.  The ids are implicitly quoted; the vals are not.  As with
extend-env, earlier ids shadow later ones.

> (lookup env id [id-eq?] [fk])

Looks up the identifier id in env, using id-eq? to compare the supplied id
with those in the environment.  If the id is not found, invokes the thunk
fk in tail context.  If id-eq? is not provided, it defaults to eq?.  The
default fk raises an exn:env:unbound exception.

> (env->alist env)

This function converts the environment env to an association list,
containing all of env's bindings (including the shadowed ones).  For
example, 

    (env->alist (env [a 3] [b 4]))

produces the list

    '((a 3) (b 4)) .

This is useful for debugging and testing.

> (env? x)

Returns #t if its argument is an environment---that is, it was constructed
with make-empty-env, extend-env, or env.

> exn:env:unbound

This structure type (a substructure of exn:fail:contract) is used as an
exception to signal an unbound identifier in an environment.  It adds one
additional field:

  - id : the unbound identifier.

======================================================================

The environment-tests module exports one identifier:

> environment-tests

This is a SchemeUnit test suite that tests the functionality of the
environment module documented above.