[[add refs for all conditions signalled]]

Copyright 1999, 2006 Free Software Foundation, Inc.

Motivation
**********

     $Id: env.texi,v 1.1.10.1 2006-02-12 13:42:50 mvo Exp $

This is a draft proposal for a new datatype for representing top-level environments in Guile.  Upon completion, this proposal will be posted to the mailing list guile@cygnus.com for discussion, revised in light of whatever insights that may produce, and eventually implemented.

Note that this is not a proposal for a module system; rather, it is a proposal for a data structure which encapsulates the ideas one needs when writing a module system, and, most importantly, a fixed interface which insulates the interpreter from the details of the module system.  Using these environments, one could implement any module system one pleased, without changing the interpreter.

I hope this text will eventually become a chapter of the Guile manual; thus, the description of environments in written in the present tense, as if it were already implemented, not in the future tense.  However, this text does not actually describe the present state of Guile.

I'm especially interested in improving the vague, rambling presentation of environments in the section "Modules and Environments".  I'm trying to orient the user for the discussion that follows, but I wonder if I'm just confusing the issue.  I would appreciate suggestions if they are concrete --- please provide new wording.

Note also: I'm trying out a convention I'm considering for use in the manual.  When a Scheme procedure which is directly implemented by a C procedure, and both are useful to call from their respective languages, we document the Scheme procedure only, and call it a "Primitive".  If a Scheme function is marked as a primitive, you can derive the name of the corresponding C function by changing - to _, ! to _x, ? to _p, and prepending scm_.  The C function's arguments will be all of the Scheme procedure's argumements, both required and optional; if the Scheme procedure takes a ``rest'' argument, that will be a final argument to the C function.  The C function's arguments, as well as its return type, will be SCM. Thus, a procedure documented like this:
 -- Primitive: set-car! pair value

has a corresponding C function which would be documented like this:
 -- Libguile function: SCM scm_set_car_x (SCM PAIR, SCM VALUE)

The hope is that this will be an uncluttered way to document both the C and Scheme interfaces, without unduly confusing users interested only in the Scheme level.

When there is a C function which provides the same functionality as a primitive, but with a different interface tailored for C's needs, it usually has the same name as the primitive's C function, but with the prefix scm_c_ instead of simply scm_.  Thus, scm_c_environment_ref is almost identical to scm_environment_ref, except that it indicates an unbound variable in a manner friendlier to C code.

Top-Level Environments in Guile
*******************************

In Guile, an environment is a mapping from symbols onto variables, and a variable is a location containing a value.  Guile uses the datatype described here to represent its top-level environments.

Modules and Environments
========================

Guile distinguishes between environments and modules.  A module is a unit of code sharing; it has a name, like (math random), an implementation (e.g., Scheme source code, a dynamically linked library, or a set of primitives built into Guile), and finally, an environment containing the definitions which the module exports for its users.

An environment, by contrast, is simply an abstract data type representing a mapping from symbols onto variables which the Guile interpreter uses to look up top-level definitions.  The eval procedure interprets its first argument, an expression, in the context of its second argument, an environment.

Guile uses environments to implement its module system.  A module created by loading Scheme code might be built from several environments. In addition to the environment of exported definitions, such a module might have an internal top-level environment, containing both exported and private definitions, and perhaps environments for imported definitions alone and local definitions alone.

The interface described here includes a full set of functions for mutating environments, and the system goes to some length to maintain its consistency as environments' bindings change.  This is necessary because Guile is an interactive system.  The user may create new definitions or modify and reload modules while Guile is running; the system should handle these changes in a consistent and predictable way.

A typical Guile system will have several distinct top-level environments.  (This is why we call them ``top-level'', and not ``global''.)  For example, consider the following fragment of an interactive Guile session:

     guile> (use-modules (ice-9 regex))
     guile> (define pattern "^(..+)\\1+$")
     guile> (string-match pattern "xxxx")
     #("xxxx" (0 . 4) (0 . 2))
     guile> (string-match pattern "xxxxx")
     #f
     guile>

Guile evaluates the expressions the user types in a top-level environment reserved for that purpose; the definition of pattern goes there.  That environment is distinct from the one holding the private definitions of the (ice-9 regex) module.  At the Guile prompt, the user does not see the module's private definitions, and the module is unaffected by definitions the user makes at the prompt.  The use-modules form copies the module's public bindings into the user's environment.

All Scheme evaluation takes place with respect to some top-level environment.  Just as the procedure created by a lambda form closes over any local scopes surrounding that form, it also closes over the surrounding top-level environment.  Thus, since the string-match procedure is defined in the (ice-9 regex) module, it closes over that module's top-level environment.  Thus, when the user calls string-match from the Guile prompt, any free variables in string-match's definition are resolved with respect to the module's top-level environment, not the user's.

Although the Guile interaction loop maintains a ``current'' top-level environment in which it evaluates the user's input, it would be misleading to extend the concept of a ``current top-level environment'' to the system as a whole.  Each procedure closes over its own top-level environment, in which that procedure will find bindings for its free variables.  Thus, the top-level environment in force at any given time depends on the procedure Guile happens to be executing.  The global ``current'' environment is a figment of the interaction loop's imagination.

Since environments provide all the operations the Guile interpreter needs to evaluate code, they effectively insulate the interpreter from the details of the module system.  Without changing the interpreter, you can implement any module system you like, as long as its efforts produce an environment object the interpreter can consult.

Finally, environments may prove a convenient way for Guile to access the features of other systems.  For example, one might export the The GIMP's Procedural Database to Guile as a custom environment type; this environment could create Scheme procedure objects corresponding to GIMP procedures, as the user referenced them.

Common Environment Operations
=============================

This section describes the common set of operations that all environment objects support.  To create an environment object, or to perform an operation specific to a particular kind of environment, see Standard Environment Types.

In this section, the following names for formal parameters imply that the actual parameters must have a certain type:

env
     an environment

symbol
     a symbol

proc
     a procedure

value
object
     an arbitrary Scheme value

Examining Environments
----------------------

 -- Primitive: environment? object
     Return #t if OBJECT is an environment, or #f otherwise.

 -- Primitive: environment-ref env symbol
     Return the value of the location bound to SYMBOL in ENV. If SYMBOL is unbound in ENV, signal an environment:unbound error (see Environment Errors).

 -- Primitive: environment-bound? env symbol
     Return #t if SYMBOL is bound in ENV, or #f otherwise.

 -- Primitive: environment-fold env proc init
     Iterate over all the bindings in an environment, accumulating some value.

     For each binding in ENV, apply PROC to the symbol bound, its value, and the result from the previous application of PROC.  Use INIT as PROC's third argument the first time PROC is applied.

     If ENV contains no bindings, this function simply returns INIT.

     If ENV binds the symbol SYM1 to the value VAL1, SYM2 to VAL2, and so on, then this procedure computes:

          (PROC SYM1 VAL1
                (PROC SYM2 VAL2
                      ...
                      (PROC SYMN VALN
                            INIT)))

     Each binding in ENV is processed at most once. environment-fold makes no guarantees about the order in which the bindings are processed.

     If ENV is not modified while the iteration is taking place, environment-fold will apply PROC to each binding in ENV exactly once.

     If ENV is modified while the iteration is taking place, we need to be more subtle in describing environment-fold's behavior. environment-fold repeatedly applies PROC to a binding which was present in ENV when environment-fold was invoked and is still present in ENV, until there are no such bindings remaining. (If no mutations take place, this definition is equivalent to the simpler one given above.)  By this definition, bindings added during the iteration will not be passed to PROC.

     Here is a function which, given an environment, constructs an association list representing that environment's bindings, using environment-fold:

          (define (environment->alist env)
            (environment-fold env
                              (lambda (sym val tail)
                                (cons (cons sym val) tail))
                              '()))

 -- Libguile macro: int SCM_ENVP (OBJECT)
     Return non-zero if OBJECT is an environment.

 -- Libguile function: SCM scm_c_environment_ref (SCM ENV, SCM SYMBOL)
     This C function is identical to environment-ref, except that if SYMBOL is unbound in ENV, it returns the value SCM_UNDEFINED, instead of signalling an error.

 -- Libguile function: SCM scm_c_environment_fold (SCM ENV, scm_environment_folder *PROC, SCM DATA, SCM INIT)
     This is the C-level analog of environment-fold.  For each binding in ENV, make the call:

          (*PROC) (DATA, SYMBOL, VALUE, PREVIOUS)

     where PREVIOUS is the value returned from the last call to *PROC, or INIT for the first call.  If ENV contains no bindings, return INIT.

 -- Libguile data type: scm_environment_folder SCM (SCM DATA, SCM SYMBOL, SCM VALUE, SCM TAIL)
     The type of a folding function to pass to scm_c_environment_fold.

Changing Environments
---------------------

Here are functions for changing symbols' bindings and values.

Although it is common to say that an environment binds a symbol to a value, this is not quite accurate; an environment binds a symbol to a location, and the location contains a value.  In the descriptions below, we will try to make clear how each function affects bindings and locations.

Note that some environments may contain some immutable bindings, or may bind symbols to immutable locations.  If you attempt to change an immutable binding or value, these functions will signal an environment:immutable-binding or environment:immutable-location error.  However, simply because a binding cannot be changed via these functions does not imply that it is constant.  Mechanisms outside the scope of this section (say, re-loading a module's source code) may change a binding or value which is immutable via these functions.

 -- Primitive: environment-define env symbol value
     Bind SYMBOL to a new location containing VALUE in ENV. If SYMBOL is already bound to another location in ENV, that binding is replaced.  The new binding and location are both mutable. The return value is unspecified.

     If SYMBOL is already bound in ENV, and the binding is immutable, signal an environment:immutable-binding error.

 -- Primitive: environment-undefine env symbol
     Remove any binding for SYMBOL from ENV.  If SYMBOL is unbound in ENV, do nothing.  The return value is unspecified.

     If SYMBOL is already bound in ENV, and the binding is immutable, signal an environment:immutable-binding error.

 -- Primitive: environment-set! env symbol value
     If ENV binds SYMBOL to some location, change that location's value to VALUE.  The return value is unspecified.

     If SYMBOL is not bound in ENV, signal an environment:unbound error.  If ENV binds SYMBOL to an immutable location, signal an environment:immutable-location error.

Caching Environment Lookups
---------------------------

Some applications refer to variables' values so frequently that the overhead of environment-ref and environment-set! is unacceptable.  For example, variable reference speed is a critical factor in the performance of the Guile interpreter itself.  If an application can tolerate some additional complexity, the environment-cell function described here can provide very efficient access to variable values.

In the Guile interpreter, most variables are represented by pairs; the CDR of the pair holds the variable's value.  Thus, a variable reference corresponds to taking the CDR of one of these pairs, and setting a variable corresponds to a set-cdr! operation.  A pair used to represent a variable's value in this manner is called a value cell.  Value cells represent the ``locations'' to which environments bind symbols.

The environment-cell function returns the value cell bound to a symbol.  For example, an interpreter might make the call (environment-cell ENV SYMBOL #t) to find the value cell which ENV binds to SYMBOL, and then use cdr and set-cdr! to reference and assign to that variable, instead of calling environment-ref or ENVIRONMENT-SET! for each variable reference.

There are a few caveats that apply here:

  * Environments are not required to represent variables' values using value cells.  An environment is free to return #f in response to a request for a symbol's value cell; in this case, the caller must use environment-ref and environment-set! to manipulate the variable.

  * An environment's binding for a symbol may change.  For example, the user could override an imported variable with a local definition, associating a new value cell with that symbol.  If an interpreter has used environment-cell to obtain the variable's value cell, it no longer needs to use environment-ref and environment-set! to access the variable, and it may not see the new binding.

     Thus, code which uses environment-cell should almost always use environment-observe to track changes to the symbol's binding; this is the additional complexity hinted at above.  See Observing Changes to Environments.

  * Some variables should be immutable.  If a program uses environment-cell to obtain the value cell of such a variable, then it is impossible for the environment to prevent the program from changing the variable's value, using set-cdr!.  However, this is discouraged; it is probably better to redesign the interface than to disregard such a request.  To make it easy for programs to honor the immutability of a variable, environment-cell takes an argument indicating whether the caller intends to mutate the cell's value; if this argument is true, then environment-cell signals an environment:immutable-location error.

     Programs should therefore make separate calls to environment-cell to obtain value cells for reference and for assignment.  It is incorrect for a program to call environment-cell once to obtain a value cell, and then use that cell for both reference and mutation.

 -- Primitive: environment-cell env symbol for-write
     Return the value cell which ENV binds to SYMBOL, or #f if the binding does not live in a value cell.

     The argument FOR-WRITE indicates whether the caller intends to modify the variable's value by mutating the value cell.  If the variable is immutable, then environment-cell signals an environment:immutable-location error.

     If SYMBOL is unbound in ENV, signal an environment:unbound error.

     If you use this function, you should consider using environment-observe, to be notified when symbol gets re-bound to a new value cell, or becomes undefined.

 -- Libguile function: SCM scm_c_environment_cell (SCM ENV, SCM SYMBOL, int for_write)
     This C function is identical to environment-cell, except that if SYMBOL is unbound in ENV, it returns the value SCM_UNDEFINED, instead of signalling an error.

[[After we have some experience using this, we may find that we want to be able to explicitly ask questions like, "Is this variable mutable?" without the annoyance of error handling.  But maybe this is fine.]]

Observing Changes to Environments
---------------------------------

The procedures described here allow you to add and remove observing procedures for an environment.

Registering Observing Procedures
................................

A program may register an observing procedure for an environment, which will be called whenever a binding in a particular environment changes.  For example, if the user changes a module's source code and re-loads the module, other parts of the system may want to throw away information they have cached about the bindings of the older version of the module.  To support this, each environment retains a set of observing procedures which it will invoke whenever its bindings change. We say that these procedures observe the environment's bindings. You can register new observing procedures for an environment using environment-observe.

 -- Primitive: environment-observe env proc
     Whenever ENV's bindings change, apply PROC to ENV.

     This function returns an object, TOKEN, which you can pass to environment-unobserve to remove PROC from the set of procedures observing ENV.  The type and value of TOKEN is unspecified.

 -- Primitive: environment-unobserve token
     Cancel the observation request which returned the value TOKEN. The return value is unspecified.

     If a call (environment-observe ENV PROC) returns TOKEN, then the call (environment-unobserve TOKEN) will cause PROC to no longer be called when ENV's bindings change.

There are some limitations on observation:

  * These procedures do not allow you to observe specific bindings; you can only observe an entire environment.

  * These procedures observe bindings, not locations.  There is no way to receive notification when a location's value changes, using these procedures.

  * These procedures do not promise to call the observing procedure for each individual binding change.  However, if multiple bindings do change between calls to the observing procedure, those changes will appear atomic to the entire system, not just to a few observing procedures.

  * Since a single environment may have several procedures observing it, a correct design obviously may not assume that nothing else in the system has yet observed a given change.

(One weakness of this observation architecture is that observing procedures make no promises to the observer.  That's fine if you're just trying to implement an accurate cache, but too weak to implement things that walk the environment tree.)

Observations and Garbage Collection
...................................

When writing observing procedures, pay close attention to garbage collection issues.  If you use environment-observe to register observing procedures for an environment, the environment will hold a reference to those procedures; while that environment is alive, its observing procedures will live, as will any data they close over.  If this is not appropriate, you can use the environment-observe-weak procedure to create a weak reference from the environment to the observing procedure.

For example, suppose an interpreter uses environment-cell to reference variables efficiently, as described above in Caching Environment Lookups.  That interpreter must register observing procedures to track changes to the environment.  If those procedures retain any reference to the data structure representing the program being interpreted, then that structure cannot be collected as long as the observed environment lives.  This is almost certainly incorrect --- if there are no other references to the structure, it can never be invoked, so it should be collected.  In this case, the interpreter should register its observing procedure using environment-observe-weak, and retain a pointer to it from the code it updates.  Thus, when the code is no longer referenced elsewhere in the system, the weak link will be broken, and Guile will collect the code (and its observing procedure).

 -- Primitive: environment-observe-weak env proc
     This function is the same as environment-observe, except that the reference ENV retains to PROC is a weak reference.  This means that, if there are no other live, non-weak references to PROC, it will be garbage-collected, and dropped from ENV's list of observing procedures.

Observing Environments from C Code
..................................

It is also possible to write code that observes an environment in C. The scm_c_environment_observe function registers a C function to observe an environment.  The typedef scm_environment_observer is the type a C observer function must have.

 -- Libguile function: SCM scm_c_environment_observe (SCM ENV, scm_environment_observer *proc, SCM DATA, int weak_p)
     This is the C-level analog of the Scheme function environment-observe.  Whenever ENV's bindings change, call the function PROC, passing it ENV and DATA.  If WEAK_P is non-zero, ENV will retain only a weak reference to DATA, and if DATA is garbage collected, the entire observation will be dropped.

     This function returns a token, with the same meaning as those returned by environment-observe.

 -- Libguile data type: scm_environment_observer void (SCM ENV, SCM DATA)
     The type for observing functions written in C.  A function meant to be passed to scm_c_environment_observe should have the type scm_environment_observer.

Note that, like all other primitives, environment-observe is also available from C, under the name scm_environment_observe.

Environment Errors
------------------

Here are the error conditions signalled by the environment routines described above.  In these conditions, FUNC is a string naming a particular procedure.

 -- Condition: environment:unbound func message args env symbol
     By calling FUNC, the program attempted to retrieve the value of SYMBOL in ENV, but SYMBOL is unbound in ENV.

 -- Condition: environment:immutable-binding func message args env symbol
     By calling FUNC, the program attempted to change the binding of SYMBOL in ENV, but that binding is immutable.

 -- Condition: environment:immutable-location func message args env symbol
     By calling FUNC, the program attempted to change the value of the location to which SYMBOL is bound in ENV, but that location is immutable.

Standard Environment Types
==========================

Guile supports several different kinds of environments.  The operations described above are actually only the common functionality provided by all the members of a family of environment types, each designed for a separate purpose.

Each environment type has a constructor procedure for building elements of that type, and extends the set of common operations with its own procedures, providing specialized functions.  For an example of how these environment types work together, see Modules of Interpreted Scheme Code.

Guile allows users to define their own environment types.  Given a set of procedures that implement the common environment operations, Guile will construct a new environment object based on those procedures.

Leaf Environments
-----------------

A leaf environment is simply a mutable set of definitions.  A mutable environment supports no operations beyond the common set.

 -- Primitive: make-leaf-environment
     Create a new leaf environment, containing no bindings.  All bindings and locations in the new environment are mutable.

 -- Primitive: leaf-environment? object
     Return #t if OBJECT is a leaf environment, or #F otherwise.

In Guile, each module of interpreted Scheme code uses a leaf environment to hold the definitions made in that module.

Leaf environments are so named because their bindings are not computed from the contents of other environments.  Most other environment types have no bindings of their own, but compute their binding sets based on those of their operand environments.  Thus, the environments in a running Guile system form a tree, with interior nodes computing their contents from their child nodes.  Leaf environments are the leaves of such trees.

Eval Environments
-----------------

A module's source code refers to definitions imported from other modules, and definitions made within itself.  An eval environment combines two environments --- a local environment and an imported environment --- to produce a new environment in which both sorts of references can be resolved.

 -- Primitive: make-eval-environment local imported
     Return a new environment object EVAL whose bindings are the union of the bindings in the environments LOCAL and IMPORTED, with bindings from LOCAL taking precedence.  Definitions made in EVAL are placed in LOCAL.

     Applying environment-define or environment-undefine to EVAL has the same effect as applying the procedure to LOCAL. This means that applying environment-undefine to a symbol bound in IMPORTED and free in LOCAL has no effect on the bindings visible in EVAL, which may be surprising.

     Note that EVAL incorporates LOCAL and IMPORTED by reference --- if, after creating EVAL, the program changes the bindings of LOCAL or IMPORTED, those changes will be visible in EVAL.

     Since most Scheme evaluation takes place in EVAL environments, they transparenty cache the bindings received from LOCAL and IMPORTED.  Thus, the first time the program looks up a symbol in EVAL, EVAL may make calls to LOCAL or IMPORTED to find their bindings, but subsequent references to that symbol will be as fast as references to bindings in leaf environments.

     In typical use, LOCAL will be a leaf environment, and IMPORTED will be an import environment, described below.

 -- Primitive: eval-environment? object
     Return #t if OBJECT is an eval environment, or #f otherwise.

 -- Primitive: eval-environment-local env
 -- Primitive: eval-environment-imported env
     Return the LOCAL or IMPORTED environment of ENV; ENV must be an eval environment.

Import Environments
-------------------

An import environment combines the bindings of a set of argument environments, and checks for naming clashes.

 -- Primitive: make-import-environment imports conflict-proc
     Return a new environment IMP whose bindings are the union of the bindings from the environments in IMPORTS; IMPORTS must be a list of environments.  That is, IMP binds SYMBOL to LOCATION when some element of IMPORTS does.

     If two different elements of IMPORTS have a binding for the same symbol, apply CONFLICT-PROC to the two environments.  If the bindings of any of the IMPORTS ever changes, check for conflicts again.

     All bindings in IMP are immutable.  If you apply environment-define or environment-undefine to IMP, Guile will signal an environment:immutable-binding error. However, notice that the set of bindings in IMP may still change, if one of its imported environments changes.

 -- Primitive: import-environment? object
     Return #t if OBJECT is an import environment, or #f otherwise.

 -- Primitive: import-environment-imports env
     Return the list of ENV's imported environments; ENV must be an import env.

 -- Primitive: import-environment-set-imports! env imports
     Change ENV's list of imported environments to IMPORTS, and check for conflicts.

I'm not at all sure about the way CONFLICT-PROC works.  I think module systems should warn you if it seems you're likely to get the wrong binding, but exactly how and when those warnings should be generated, I don't know.

Export Environments
-------------------

An export environment restricts an environment a specified set of bindings.

 -- Primitive: make-export-environment private signature
     Return a new environment EXP containing only those bindings in PRIVATE whose symbols are present in SIGNATURE.  The PRIVATE argument must be an environment.

     The environment EXP binds SYMBOL to LOCATION when ENV does, and SYMBOL is exported by SIGNATURE.

     SIGNATURE is a list specifying which of the bindings in PRIVATE should be visible in EXP.  Each element of SIGNATURE should be a list of the form:

          (SYMBOL ATTRIBUTE ...)

     where each ATTRIBUTE is one of the following:

     the symbol mutable-location
          EXP should treat the location bound to SYMBOL as mutable. That is, EXP will pass calls to ENV-SET! or environment-cell directly through to PRIVATE.

     the symbol immutable-location
          EXP should treat the location bound to SYMBOL as immutable. If the program applies environment-set! to EXP and SYMBOL, or calls environment-cell to obtain a writable value cell, environment-set!  will signal an environment:immutable-location error.

          Note that, even if an export environment treats a location as immutable, the underlying environment may treat it as mutable, so its value may change.

     It is an error for an element of SIGNATURE to specify both mutable-location and immutable-location.  If neither is specified, immutable-location is assumed.

     As a special case, if an element of SIGNATURE is a lone symbol SYM, it is equivalent to an element of the form (SYM).

     All bindings in EXP are immutable.  If you apply environment-define or environment-undefine to EXP, Guile will signal an environment:immutable-binding error. However, notice that the set of bindings in EXP may still change, if the bindings in PRIVATE change.

 -- Primitive: export-environment? object
     Return #t if OBJECT is an export environment, or #f otherwise.

 -- Primitive: export-environment-private env
 -- Primitive: export-environment-set-private! env
 -- Primitive: export-environment-signature env
 -- Primitive: export-environment-set-signature! env
     Accessors and mutators for the private environment and signature of ENV; ENV must be an export environment.

General Environments
--------------------

[[user provides the procedures]] [[A observers B and C; B observes C; C changes; A should only be notified once, right?]] [[observation loops?]]

Implementing Environments
=========================

This section describes how to implement new environment types in Guile.

Guile's internal representation of environments allows you to extend Guile with new kinds of environments without modifying Guile itself. Every environment object carries a pointer to a structure of pointers to functions implementing the common operations for that environment.  The procedures environment-ref, environment-set!, etc. simply find this structure and invoke the appropriate function.

[[It would be nice to have an example around here.  How about a persistent environment, bound to a directory, where ref and set actually access files?  Ref on a directory would return another environment... Hey, let's import my home directory!]]

Environment Function Tables
---------------------------

An environment object is a smob whose CDR is a pointer to a pointer to a struct environment_funcs:

     struct environment_funcs {
       SCM  (*ref) (SCM self, SCM symbol);
       SCM  (*fold) (SCM self, scm_environment_folder *proc, SCM data, SCM init);
       void (*define) (SCM self, SCM symbol, SCM value);
       void (*undefine) (SCM self, SCM symbol);
       void (*set) (SCM self, SCM symbol, SCM value);
       SCM  (*cell) (SCM self, SCM symbol, int for_write);
       SCM  (*observe) (SCM self, scm_environment_observer *proc, SCM data, int weak_p);
       void (*unobserve) (SCM self, SCM token);
       SCM  (*mark) (SCM self);
       scm_sizet (*free) (SCM self);
       int  (*print) (SCM self, SCM port, scm_print_state *pstate);
     };

You can use the following macro to access an environment's function table:

 -- Libguile macro: struct environment_funcs *SCM_ENVIRONMENT_FUNCS (ENV)
     Return a pointer to the struct environment_func for the environment ENV.  If ENV is not an environment object, the behavior of this macro is undefined.

Here is what each element of ENV_FUNCS must do to correctly implement an environment.  In all of these calls, SELF is the environment whose function is being invoked.

SCM ref (SCM SELF, SCM SYMBOL);
     This function must have the effect described above for the C call:

          scm_c_environment_ref (SELF, SYMBOL)

     See Examining Environments.

     Note that the ref element of a struct environment_funcs may be zero if a cell function is provided.

SCM fold (SCM self, scm_environment_folder *proc, SCM data, SCM init);
     This function must have the effect described above for the C call:

          scm_c_environment_fold (SELF, PROC, DATA, INIT)

     See Examining Environments.

void define (SCM self, SCM symbol, SCM value);
     This function must have the effect described above for the Scheme call:

          (environment-define SELF SYMBOL VALUE)

     See Changing Environments.

void undefine (SCM self, SCM symbol);
     This function must have the effect described above for the Scheme call:

          (environment-undefine SELF SYMBOL)

     See Changing Environments.

void set (SCM self, SCM symbol, SCM value);
     This function must have the effect described above for the Scheme call:

          (environment-set! SELF SYMBOL VALUE)

     See Changing Environments.

     Note that the set element of a struct environment_funcs may be zero if a cell function is provided.

SCM cell (SCM self, SCM symbol, int for_write);
     This function must have the effect described above for the C call:

          scm_c_environment_cell (SELF, SYMBOL)

     See Caching Environment Lookups.

SCM observe (SCM self, scm_environment_observer *proc, SCM data, int weak_p);
     This function must have the effect described above for the C call:

          scm_c_environment_observe (ENV, PROC, DATA, WEAK_P)

     See Observing Changes to Environments.

void unobserve (SCM self, SCM token);
     Cancel the request to observe SELF that returned TOKEN. See Observing Changes to Environments.

SCM mark (SCM self);
     Set the garbage collection mark all Scheme cells referred to by SELF.  Assume that SELF itself is already marked.  Return a final object to be marked recursively.

scm_sizet free (SCM self);
     Free all non-cell storage associated with SELF; return the number of bytes freed that were obtained using scm_must_malloc or scm_must_realloc.

SCM print (SCM self, SCM port, scm_print_state *pstate);
     Print an external representation of SELF on PORT, passing PSTATE to any recursive calls to the object printer.

Environment Data
----------------

When you implement a new environment type, you will likely want to associate some data of your own design with each environment object. Since ANSI C promises that casts will safely convert between a pointer to a structure and a pointer to its first element, you can have the CDR of an environment smob point to your structure, as long as your structure's first element is a pointer to a struct environment_funcs.  Then, your code can use the macro below to retrieve a pointer to the structure, and cast it to the appropriate type.

 -- Libguile macro: struct environment_funcs **SCM_ENVIRONMENT_DATA (ENV)
     Return the CDR of ENV, as a pointer to a pointer to an environment_funcs structure.

Environment Example
-------------------

[[perhaps a simple environment based on association lists]]

Switching to Environments
=========================

Here's what we'd need to do to today's Guile to install the system described above.  This work would probably be done on a branch, because it involves crippling Guile while a lot of work gets done.  Also, it could change the default set of bindings available pretty drastically, so the next minor release should not contain these changes.

After each step here, we should have a Guile that we can at least interact with, perhaps with some limitations.

  * For testing purposes, make an utterly minimal version of boot-9.scm: no module system, no R5RS, nothing.  I think a simple REPL is all we need.

  * Implement the environment datatypes in libguile, and test them using this utterly minimal system.

  * Change the interpreter to use the environment-cell and environment-observe instead of the symbol value slots, first-class variables, etc.  Modify the rest of libguile as necessary to register all the primitives in a single environment.  We'll segregate them into modules later.

  * Reimplement the current module system in terms of environments.  It should still be in Scheme.

  * Reintegrate the rest of boot-9.scm.  This might be a good point to move it into modules.

  * Do some profiling and optimization.

Once this is done, we can make the following simplifications to Guile:

  * A good portion of symbols.c can go away.  Symbols no longer need value slots.  The mismash of scm_sym2ovcell, scm_intern_obarray_soft, etc. can go away.  intern becomes simpler.

  * Remove first-class variables: variables.c and variables.h.

  * Organize the primitives into environments.

  * The family of environment types is clearly an abstract class/concrete subclass arrangement.  We should provide GOOPS classes/metaclasses that make defining new environment types easy and consistent.

Modules
*******

The material here is just a sketch.  Don't take it too seriously.  The point is that environments allow us to experiment without getting tangled up with the interpreter.

Modules of Guile Primitives
===========================

Modules of Interpreted Scheme Code
==================================

If a module is implemented by interpreted Scheme code, Guile represents it using several environments:

the local environment
     This environment holds all the definitions made locally by the module, both public and private.

the import environment
     This environment holds all the definitions this module imports from other modules.

the evaluation environment
     This is the environment in which the module's code is actually evaluated, and the one closed over by the module's procedures, both public and private.  Its bindings are the union of the LOCAL and IMPORT environments, with local bindings taking precedence.

the exported environment
     This environment holds the module's public definitions.  This is the only environment that the module's users have access to.  It is the EVALUATION environment, restricted to the set of exported definitions.

Each of these environments is implemented using a separate environment type.  Some of these types, like the evaluation and import environments, actually just compute their bindings by consulting other environments; they have no bindings in their own right.  They implement operations like environment-ref and environment-define by passing them through to the environments from which they are derived.  For example, the evaluation environment will pass definitions through to the local environment, and search for references and assignments first in the local environment, and then in the import environment.