--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename env.info
+@settitle Top-level Environments in Guile
+@c %**end of header
+
+@setchapternewpage odd
+
+@c Changes since Jost's implementation:
+@c "finite environments" -> "leaf environments"
+@c "scm_foo_internal" -> "scm_c_foo"
+
+@c To do:
+@c add spec for soft environments
+
+@c When merged into the main manual, add cross-references for:
+@c weak references
+@c smobs (esp. module's mark and free functions)
+
+
+[[add refs for all conditions signalled]]
+
+@ifinfo
+Copyright 1999, 2006 Free Software Foundation, Inc.
+@end ifinfo
+
+@titlepage
+@sp 10
+@comment The title is printed in a large font.
+@center @titlefont{Top-level Environments in Guile}
+
+@c The following two commands start the copyright page.
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1999, 2006 Free Software Foundation, Inc.
+@end titlepage
+
+@node Top, Motivation, (dir), (dir)
+
+@menu
+* Motivation::
+* Top-Level Environments in Guile::
+* Modules::
+@end menu
+
+@node Motivation, Top-Level Environments in Guile, Top, Top
+@chapter Motivation
+
+@example
+$Id: env.texi,v 1.1.10.1 2006-02-12 13:42:50 mvo Exp $
+@end example
+
+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 @samp{guile@@cygnus.com} for discussion, revised in
+light of whatever insights that may produce, and eventually implemented.
+
+Note that this is @emph{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 @code{-} to @code{_}, @code{!} to
+@code{_x}, @code{?} to @code{_p}, and prepending @code{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 @code{SCM}.
+Thus, a procedure documented like this:
+@deffn Primitive set-car! pair value
+@end deffn
+
+has a corresponding C function which would be documented like this:
+@deftypefn {Libguile function} SCM scm_set_car_x (SCM @var{pair}, SCM @var{value})
+@end deftypefn
+
+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 @code{scm_c_} instead of simply @code{scm_}. Thus,
+@code{scm_c_environment_ref} is almost identical to
+@code{scm_environment_ref}, except that it indicates an unbound variable
+in a manner friendlier to C code.
+
+
+
+@node Top-Level Environments in Guile, Modules, Motivation, Top
+@chapter 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.
+
+
+@menu
+* Modules and Environments:: Modules are environments, with bookkeeping.
+* Common Environment Operations:: Looking up bindings, creating bindings, etc.
+* Standard Environment Types:: Guile has some fundamental environment types.
+* Implementing Environments:: You can extend Guile with new kinds of
+ environments.
+* Switching to Environments:: Changes needed to today's Guile to
+ implement the features described here.
+@end menu
+
+@node Modules and Environments, Common Environment Operations, Top-Level Environments in Guile, Top-Level Environments in Guile
+@section Modules and Environments
+
+Guile distinguishes between environments and modules. A module is a
+unit of code sharing; it has a name, like @code{(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 @code{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:
+
+@example
+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>
+@end example
+@noindent
+Guile evaluates the expressions the user types in a top-level
+environment reserved for that purpose; the definition of @code{pattern}
+goes there. That environment is distinct from the one holding the
+private definitions of the @code{(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
+@code{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 @code{lambda} form
+closes over any local scopes surrounding that form, it also closes over
+the surrounding top-level environment. Thus, since the
+@code{string-match} procedure is defined in the @code{(ice-9 regex)}
+module, it closes over that module's top-level environment. Thus, when
+the user calls @code{string-match} from the Guile prompt, any free
+variables in @code{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.
+
+
+@node Common Environment Operations, Standard Environment Types, Modules and Environments, Top-Level Environments in Guile
+@section 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
+@ref{Standard Environment Types}.
+
+In this section, the following names for formal parameters imply that
+the actual parameters must have a certain type:
+
+@table @var
+
+@item env
+an environment
+
+@item symbol
+a symbol
+
+@item proc
+a procedure
+
+@item value
+@itemx object
+an arbitrary Scheme value
+
+@end table
+
+
+@menu
+* Examining Environments::
+* Changing Environments::
+* Caching Environment Lookups::
+* Observing Changes to Environments ::
+* Environment Errors::
+@end menu
+
+@node Examining Environments, Changing Environments, Common Environment Operations, Common Environment Operations
+@subsection Examining Environments
+
+@deffn Primitive environment? object
+Return @code{#t} if @var{object} is an environment, or @code{#f} otherwise.
+@end deffn
+
+@deffn Primitive environment-ref env symbol
+Return the value of the location bound to @var{symbol} in @var{env}.
+If @var{symbol} is unbound in @var{env}, signal an @code{environment:unbound}
+error (@pxref{Environment Errors}).
+@end deffn
+
+@deffn Primitive environment-bound? env symbol
+Return @code{#t} if @var{symbol} is bound in @var{env}, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn Primitive environment-fold env proc init
+Iterate over all the bindings in an environment, accumulating some value.
+
+For each binding in @var{env}, apply @var{proc} to the symbol bound, its
+value, and the result from the previous application of @var{proc}. Use
+@var{init} as @var{proc}'s third argument the first time @var{proc} is
+applied.
+
+If @var{env} contains no bindings, this function simply returns @var{init}.
+
+If @var{env} binds the symbol @var{sym1} to the value @var{val1},
+@var{sym2} to @var{val2}, and so on, then this procedure computes:
+@example
+(@var{proc} @var{sym1} @var{val1}
+ (@var{proc} @var{sym2} @var{val2}
+ ...
+ (@var{proc} @var{symn} @var{valn}
+ @var{init})))
+@end example
+
+Each binding in @var{env} is processed at most once.
+@code{environment-fold} makes no guarantees about the order in which the
+bindings are processed.
+
+If @var{env} is not modified while the iteration is taking place,
+@code{environment-fold} will apply @var{proc} to each binding in
+@var{env} exactly once.
+
+If @var{env} is modified while the iteration is taking place, we need to
+be more subtle in describing @code{environment-fold}'s behavior.
+@code{environment-fold} repeatedly applies @var{proc} to a binding which
+was present in @var{env} when @code{environment-fold} was invoked and is
+still present in @var{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 @var{proc}.
+
+Here is a function which, given an environment, constructs an
+association list representing that environment's bindings, using
+@code{environment-fold}:
+@example
+(define (environment->alist env)
+ (environment-fold env
+ (lambda (sym val tail)
+ (cons (cons sym val) tail))
+ '()))
+@end example
+@end deffn
+
+@deftypefn {Libguile macro} int SCM_ENVP (@var{object})
+Return non-zero if @var{object} is an environment.
+@end deftypefn
+
+@deftypefn {Libguile function} SCM scm_c_environment_ref (SCM @var{env}, SCM @var{symbol})
+This C function is identical to @code{environment-ref}, except that if
+@var{symbol} is unbound in @var{env}, it returns the value
+@code{SCM_UNDEFINED}, instead of signalling an error.
+@end deftypefn
+
+@deftypefn {Libguile function} SCM scm_c_environment_fold (SCM @var{env}, scm_environment_folder *@var{proc}, SCM @var{data}, SCM @var{init})
+This is the C-level analog of @code{environment-fold}. For each binding in
+@var{env}, make the call:
+@example
+(*@var{proc}) (@var{data}, @var{symbol}, @var{value}, @var{previous})
+@end example
+@noindent
+where @var{previous} is the value returned from the last call to
+@code{*@var{proc}}, or @var{init} for the first call. If @var{env}
+contains no bindings, return @var{init}.
+@end deftypefn
+
+@deftp {Libguile data type} scm_environment_folder SCM (SCM @var{data}, SCM @var{symbol}, SCM @var{value}, SCM @var{tail})
+The type of a folding function to pass to @code{scm_c_environment_fold}.
+@end deftp
+
+
+@node Changing Environments, Caching Environment Lookups, Examining Environments, Common Environment Operations
+@subsection 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
+@code{environment:immutable-binding} or
+@code{environment:immutable-location} error. However, simply because a
+binding cannot be changed via these functions does @emph{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.
+
+@deffn Primitive environment-define env symbol value
+Bind @var{symbol} to a new location containing @var{value} in @var{env}.
+If @var{symbol} is already bound to another location in @var{env}, that
+binding is replaced. The new binding and location are both mutable.
+The return value is unspecified.
+
+If @var{symbol} is already bound in @var{env}, and the binding is
+immutable, signal an @code{environment:immutable-binding} error.
+@end deffn
+
+@deffn Primitive environment-undefine env symbol
+Remove any binding for @var{symbol} from @var{env}. If @var{symbol} is
+unbound in @var{env}, do nothing. The return value is unspecified.
+
+If @var{symbol} is already bound in @var{env}, and the binding is
+immutable, signal an @code{environment:immutable-binding} error.
+@end deffn
+
+@deffn Primitive environment-set! env symbol value
+If @var{env} binds @var{symbol} to some location, change that location's
+value to @var{value}. The return value is unspecified.
+
+If @var{symbol} is not bound in @var{env}, signal an
+@code{environment:unbound} error. If @var{env} binds @var{symbol} to an
+immutable location, signal an @code{environment:immutable-location}
+error.
+@end deffn
+
+
+@node Caching Environment Lookups, Observing Changes to Environments , Changing Environments, Common Environment Operations
+@subsection Caching Environment Lookups
+
+Some applications refer to variables' values so frequently that the
+overhead of @code{environment-ref} and @code{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
+@code{environment-cell} function described here can provide very
+efficient access to variable values.
+
+In the Guile interpreter, most variables are represented by pairs; the
+@sc{cdr} of the pair holds the variable's value. Thus, a variable
+reference corresponds to taking the @sc{cdr} of one of these pairs, and
+setting a variable corresponds to a @code{set-cdr!} operation. A pair
+used to represent a variable's value in this manner is called a
+@dfn{value cell}. Value cells represent the ``locations'' to which
+environments bind symbols.
+
+The @code{environment-cell} function returns the value cell bound to a
+symbol. For example, an interpreter might make the call
+@code{(environment-cell @var{env} @var{symbol} #t)} to find the value
+cell which @var{env} binds to @var{symbol}, and then use @code{cdr} and
+@code{set-cdr!} to reference and assign to that variable, instead of
+calling @code{environment-ref} or @var{environment-set!} for each
+variable reference.
+
+There are a few caveats that apply here:
+
+@itemize @bullet
+
+@item
+Environments are not required to represent variables' values using value
+cells. An environment is free to return @code{#f} in response to a
+request for a symbol's value cell; in this case, the caller must use
+@code{environment-ref} and @code{environment-set!} to manipulate the
+variable.
+
+@item
+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
+@code{environment-cell} to obtain the variable's value cell, it no
+longer needs to use @code{environment-ref} and @code{environment-set!}
+to access the variable, and it may not see the new binding.
+
+Thus, code which uses @code{environment-cell} should almost always use
+@code{environment-observe} to track changes to the symbol's binding;
+this is the additional complexity hinted at above. @xref{Observing
+Changes to Environments}.
+
+@item
+Some variables should be immutable. If a program uses
+@code{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 @code{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, @code{environment-cell} takes an argument
+indicating whether the caller intends to mutate the cell's value; if
+this argument is true, then @code{environment-cell} signals an
+@code{environment:immutable-location} error.
+
+Programs should therefore make separate calls to @code{environment-cell}
+to obtain value cells for reference and for assignment. It is incorrect
+for a program to call @code{environment-cell} once to obtain a value
+cell, and then use that cell for both reference and mutation.
+
+@end itemize
+
+@deffn Primitive environment-cell env symbol for-write
+Return the value cell which @var{env} binds to @var{symbol}, or
+@code{#f} if the binding does not live in a value cell.
+
+The argument @var{for-write} indicates whether the caller intends to
+modify the variable's value by mutating the value cell. If the variable
+is immutable, then @code{environment-cell} signals an
+@code{environment:immutable-location} error.
+
+If @var{symbol} is unbound in @var{env}, signal an @code{environment:unbound}
+error.
+
+If you use this function, you should consider using
+@code{environment-observe}, to be notified when @code{symbol} gets
+re-bound to a new value cell, or becomes undefined.
+@end deffn
+
+@deftypefn {Libguile function} SCM scm_c_environment_cell (SCM @var{env}, SCM @var{symbol}, int for_write)
+This C function is identical to @code{environment-cell}, except that if
+@var{symbol} is unbound in @var{env}, it returns the value
+@code{SCM_UNDEFINED}, instead of signalling an error.
+@end deftypefn
+
+[[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.]]
+
+
+@node Observing Changes to Environments , Environment Errors, Caching Environment Lookups, Common Environment Operations
+@subsection Observing Changes to Environments
+
+The procedures described here allow you to add and remove @dfn{observing
+procedures} for an environment.
+
+
+@menu
+* Registering Observing Procedures::
+* Observations and Garbage Collection::
+* Observing Environments from C Code::
+@end menu
+
+@node Registering Observing Procedures, Observations and Garbage Collection, Observing Changes to Environments , Observing Changes to Environments
+@subsubsection Registering Observing Procedures
+
+A program may register an @dfn{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 @dfn{observe} the environment's bindings.
+You can register new observing procedures for an environment using
+@code{environment-observe}.
+
+@deffn Primitive environment-observe env proc
+Whenever @var{env}'s bindings change, apply @var{proc} to @var{env}.
+
+This function returns an object, @var{token}, which you can pass to
+@code{environment-unobserve} to remove @var{proc} from the set of
+procedures observing @var{env}. The type and value of @var{token} is
+unspecified.
+@end deffn
+
+@deffn Primitive environment-unobserve token
+Cancel the observation request which returned the value @var{token}.
+The return value is unspecified.
+
+If a call @code{(environment-observe @var{env} @var{proc})} returns
+@var{token}, then the call @code{(environment-unobserve @var{token})}
+will cause @var{proc} to no longer be called when @var{env}'s bindings
+change.
+@end deffn
+
+There are some limitations on observation:
+@itemize @bullet
+@item
+These procedures do not allow you to observe specific bindings; you
+can only observe an entire environment.
+@item
+These procedures observe bindings, not locations. There is no way
+to receive notification when a location's value changes, using these
+procedures.
+@item
+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.
+@item
+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.
+@end itemize
+
+(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.)
+
+@node Observations and Garbage Collection, Observing Environments from C Code, Registering Observing Procedures, Observing Changes to Environments
+@subsubsection Observations and Garbage Collection
+
+When writing observing procedures, pay close attention to garbage
+collection issues. If you use @code{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 @code{environment-observe-weak}
+procedure to create a weak reference from the environment to the
+observing procedure.
+
+For example, suppose an interpreter uses @code{environment-cell} to
+reference variables efficiently, as described above in @ref{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
+@code{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).
+
+@deffn Primitive environment-observe-weak env proc
+This function is the same as @code{environment-observe}, except that the
+reference @var{env} retains to @var{proc} is a weak reference. This
+means that, if there are no other live, non-weak references to
+@var{proc}, it will be garbage-collected, and dropped from @var{env}'s
+list of observing procedures.
+@end deffn
+
+
+@node Observing Environments from C Code, , Observations and Garbage Collection, Observing Changes to Environments
+@subsubsection Observing Environments from C Code
+
+It is also possible to write code that observes an environment in C.
+The @code{scm_c_environment_observe} function registers a C
+function to observe an environment. The typedef
+@code{scm_environment_observer} is the type a C observer function must
+have.
+
+@deftypefn {Libguile function} SCM scm_c_environment_observe (SCM @var{env}, scm_environment_observer *proc, SCM @var{data}, int weak_p)
+This is the C-level analog of the Scheme function
+@code{environment-observe}. Whenever @var{env}'s bindings change, call
+the function @var{proc}, passing it @var{env} and @var{data}. If
+@var{weak_p} is non-zero, @var{env} will retain only a weak reference to
+@var{data}, and if @var{data} is garbage collected, the entire
+observation will be dropped.
+
+This function returns a token, with the same meaning as those returned
+by @code{environment-observe}.
+@end deftypefn
+
+@deftp {Libguile data type} scm_environment_observer void (SCM @var{env}, SCM @var{data})
+The type for observing functions written in C. A function meant to be
+passed to @code{scm_c_environment_observe} should have the type
+@code{scm_environment_observer}.
+@end deftp
+
+Note that, like all other primitives, @code{environment-observe} is also
+available from C, under the name @code{scm_environment_observe}.
+
+
+@node Environment Errors, , Observing Changes to Environments , Common Environment Operations
+@subsection Environment Errors
+
+Here are the error conditions signalled by the environment routines
+described above. In these conditions, @var{func} is a string naming a
+particular procedure.
+
+@deffn Condition environment:unbound func message args env symbol
+By calling @var{func}, the program attempted to retrieve the value of
+@var{symbol} in @var{env}, but @var{symbol} is unbound in @var{env}.
+@end deffn
+
+@deffn Condition environment:immutable-binding func message args env symbol
+By calling @var{func}, the program attempted to change the binding of
+@var{symbol} in @var{env}, but that binding is immutable.
+@end deffn
+
+@deffn Condition environment:immutable-location func message args env symbol
+By calling @var{func}, the program attempted to change the value of
+the location to which @var{symbol} is bound in @var{env}, but that
+location is immutable.
+@end deffn
+
+
+@node Standard Environment Types, Implementing Environments, Common Environment Operations, Top-Level Environments in Guile
+@section 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 @ref{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.
+
+@menu
+* Leaf Environments:: A simple set of bindings.
+* Eval Environments:: Local definitions, shadowing
+ imported definitions.
+* Import Environments:: The union of a list of environments.
+* Export Environments:: A selected subset of an environment.
+* General Environments:: Environments implemented by user
+ functions.
+@end menu
+
+@node Leaf Environments, Eval Environments, Standard Environment Types, Standard Environment Types
+@subsection Leaf Environments
+
+A @dfn{leaf} environment is simply a mutable set of definitions. A mutable
+environment supports no operations beyond the common set.
+
+@deffn Primitive make-leaf-environment
+Create a new leaf environment, containing no bindings. All bindings
+and locations in the new environment are mutable.
+@end deffn
+
+@deffn Primitive leaf-environment? object
+Return @code{#t} if @var{object} is a leaf environment, or @var{#f}
+otherwise.
+@end deffn
+
+
+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.
+
+
+@node Eval Environments, Import Environments, Leaf Environments, Standard Environment Types
+@subsection Eval Environments
+
+A module's source code refers to definitions imported from other
+modules, and definitions made within itself. An @dfn{eval} environment
+combines two environments --- a @dfn{local} environment and an
+@dfn{imported} environment --- to produce a new environment in which
+both sorts of references can be resolved.
+
+@deffn Primitive make-eval-environment local imported
+Return a new environment object @var{eval} whose bindings are the union
+of the bindings in the environments @var{local} and @var{imported}, with
+bindings from @var{local} taking precedence. Definitions made in
+@var{eval} are placed in @var{local}.
+
+Applying @code{environment-define} or @code{environment-undefine} to
+@var{eval} has the same effect as applying the procedure to @var{local}.
+This means that applying @code{environment-undefine} to a symbol bound
+in @var{imported} and free in @var{local} has no effect on the bindings
+visible in @var{eval}, which may be surprising.
+
+Note that @var{eval} incorporates @var{local} and @var{imported}
+@emph{by reference} --- if, after creating @var{eval}, the program
+changes the bindings of @var{local} or @var{imported}, those changes
+will be visible in @var{eval}.
+
+Since most Scheme evaluation takes place in @var{eval} environments,
+they transparenty cache the bindings received from @var{local} and
+@var{imported}. Thus, the first time the program looks up a symbol in
+@var{eval}, @var{eval} may make calls to @var{local} or @var{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, @var{local} will be a leaf environment, and
+@var{imported} will be an import environment, described below.
+@end deffn
+
+@deffn Primitive eval-environment? object
+Return @code{#t} if @var{object} is an eval environment, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn Primitive eval-environment-local env
+@deffnx Primitive eval-environment-imported env
+Return the @var{local} or @var{imported} environment of @var{env};
+@var{env} must be an eval environment.
+@end deffn
+
+
+@node Import Environments, Export Environments, Eval Environments, Standard Environment Types
+@subsection Import Environments
+
+An @dfn{import} environment combines the bindings of a set of
+argument environments, and checks for naming clashes.
+
+@deffn Primitive make-import-environment imports conflict-proc
+Return a new environment @var{imp} whose bindings are the union of the
+bindings from the environments in @var{imports}; @var{imports} must be a
+list of environments. That is, @var{imp} binds @var{symbol} to
+@var{location} when some element of @var{imports} does.
+
+If two different elements of @var{imports} have a binding for the same
+symbol, apply @var{conflict-proc} to the two environments. If the bindings
+of any of the @var{imports} ever changes, check for conflicts again.
+
+All bindings in @var{imp} are immutable. If you apply
+@code{environment-define} or @code{environment-undefine} to @var{imp},
+Guile will signal an @code{environment:immutable-binding} error.
+However, notice that the set of bindings in @var{imp} may still change,
+if one of its imported environments changes.
+@end deffn
+
+@deffn Primitive import-environment? object
+Return @code{#t} if @var{object} is an import environment, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn Primitive import-environment-imports env
+Return the list of @var{env}'s imported environments; @var{env} must be
+an import env.
+@end deffn
+
+@deffn Primitive import-environment-set-imports! env imports
+Change @var{env}'s list of imported environments to @var{imports}, and
+check for conflicts.
+@end deffn
+
+I'm not at all sure about the way @var{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.
+
+
+@node Export Environments, General Environments, Import Environments, Standard Environment Types
+@subsection Export Environments
+
+An export environment restricts an environment a specified set of
+bindings.
+
+@deffn Primitive make-export-environment private signature
+Return a new environment @var{exp} containing only those bindings in
+@var{private} whose symbols are present in @var{signature}. The
+@var{private} argument must be an environment.
+
+The environment @var{exp} binds @var{symbol} to @var{location} when
+@var{env} does, and @var{symbol} is exported by @var{signature}.
+
+@var{Signature} is a list specifying which of the bindings in
+@var{private} should be visible in @var{exp}. Each element of
+@var{signature} should be a list of the form:
+@example
+(@var{symbol} @var{attribute} ...)
+@end example
+@noindent
+where each @var{attribute} is one of the following:
+@table @asis
+@item the symbol @code{mutable-location}
+@var{exp} should treat the location bound to @var{symbol} as mutable.
+That is, @var{exp} will pass calls to @var{env-set!} or
+@code{environment-cell} directly through to @var{private}.
+
+@item the symbol @code{immutable-location}
+@var{exp} should treat the location bound to @var{symbol} as immutable.
+If the program applies @code{environment-set!} to @var{exp} and
+@var{symbol}, or calls @code{environment-cell} to obtain a writable
+value cell, @code{environment-set!} will signal an
+@code{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.
+@end table
+
+It is an error for an element of @var{signature} to specify both
+@code{mutable-location} and @code{immutable-location}. If neither is
+specified, @code{immutable-location} is assumed.
+
+As a special case, if an element of @var{signature} is a lone symbol
+@var{sym}, it is equivalent to an element of the form
+@code{(@var{sym})}.
+
+All bindings in @var{exp} are immutable. If you apply
+@code{environment-define} or @code{environment-undefine} to @var{exp},
+Guile will signal an @code{environment:immutable-binding} error.
+However, notice that the set of bindings in @var{exp} may still change,
+if the bindings in @var{private} change.
+@end deffn
+
+@deffn Primitive export-environment? object
+Return @code{#t} if @var{object} is an export environment, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn Primitive export-environment-private env
+@deffnx Primitive export-environment-set-private! env
+@deffnx Primitive export-environment-signature env
+@deffnx Primitive export-environment-set-signature! env
+Accessors and mutators for the private environment and signature of
+@var{env}; @var{env} must be an export environment.
+@end deffn
+
+
+@node General Environments, , Export Environments, Standard Environment Types
+@subsection 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?]]
+
+@node Implementing Environments, Switching to Environments, Standard Environment Types, Top-Level Environments in Guile
+@section 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 @code{environment-ref}, @code{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!]]
+
+
+@menu
+* Environment Function Tables::
+* Environment Data::
+* Environment Example::
+@end menu
+
+
+@node Environment Function Tables, Environment Data, Implementing Environments, Implementing Environments
+@subsection Environment Function Tables
+
+An environment object is a smob whose @sc{cdr} is a pointer to a pointer
+to a @code{struct environment_funcs}:
+@example
+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);
+@};
+@end example
+
+You can use the following macro to access an environment's function table:
+
+@deftypefn {Libguile macro} struct environment_funcs *SCM_ENVIRONMENT_FUNCS (@var{env})
+Return a pointer to the @code{struct environment_func} for the environment
+@var{env}. If @var{env} is not an environment object, the behavior of
+this macro is undefined.
+@end deftypefn
+
+Here is what each element of @var{env_funcs} must do to correctly
+implement an environment. In all of these calls, @var{self} is the
+environment whose function is being invoked.
+
+@table @code
+
+@item SCM ref (SCM @var{self}, SCM @var{symbol});
+This function must have the effect described above for the C call:
+@example
+scm_c_environment_ref (@var{self}, @var{symbol})
+@end example
+@xref{Examining Environments}.
+
+Note that the @code{ref} element of a @code{struct environment_funcs}
+may be zero if a @code{cell} function is provided.
+
+@item SCM fold (SCM self, scm_environment_folder *proc, SCM data, SCM init);
+This function must have the effect described above for the C call:
+@example
+scm_c_environment_fold (@var{self}, @var{proc}, @var{data}, @var{init})
+@end example
+@xref{Examining Environments}.
+
+@item void define (SCM self, SCM symbol, SCM value);
+This function must have the effect described above for the Scheme call:
+@example
+(environment-define @var{self} @var{symbol} @var{value})
+@end example
+@xref{Changing Environments}.
+
+@item void undefine (SCM self, SCM symbol);
+This function must have the effect described above for the Scheme call:
+@example
+(environment-undefine @var{self} @var{symbol})
+@end example
+@xref{Changing Environments}.
+
+@item void set (SCM self, SCM symbol, SCM value);
+This function must have the effect described above for the Scheme call:
+@example
+(environment-set! @var{self} @var{symbol} @var{value})
+@end example
+@xref{Changing Environments}.
+
+Note that the @code{set} element of a @code{struct environment_funcs}
+may be zero if a @code{cell} function is provided.
+
+@item SCM cell (SCM self, SCM symbol, int for_write);
+This function must have the effect described above for the C call:
+@example
+scm_c_environment_cell (@var{self}, @var{symbol})
+@end example
+@xref{Caching Environment Lookups}.
+
+@item 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:
+@example
+scm_c_environment_observe (@var{env}, @var{proc}, @var{data}, @var{weak_p})
+@end example
+@xref{Observing Changes to Environments}.
+
+@item void unobserve (SCM self, SCM token);
+Cancel the request to observe @var{self} that returned @var{token}.
+@xref{Observing Changes to Environments}.
+
+@item SCM mark (SCM self);
+Set the garbage collection mark all Scheme cells referred to by
+@var{self}. Assume that @var{self} itself is already marked. Return a
+final object to be marked recursively.
+
+@item scm_sizet free (SCM self);
+Free all non-cell storage associated with @var{self}; return the number
+of bytes freed that were obtained using @code{scm_must_malloc} or
+@code{scm_must_realloc}.
+
+@item SCM print (SCM self, SCM port, scm_print_state *pstate);
+Print an external representation of @var{self} on @var{port}, passing
+@var{pstate} to any recursive calls to the object printer.
+
+@end table
+
+
+@node Environment Data, Environment Example, Environment Function Tables, Implementing Environments
+@subsection 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
+@sc{cdr} of an environment smob point to your structure, as long as your
+structure's first element is a pointer to a @code{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.
+
+@deftypefn {Libguile macro} struct environment_funcs **SCM_ENVIRONMENT_DATA (@var{env})
+Return the @sc{cdr} of @var{env}, as a pointer to a pointer to an
+@code{environment_funcs} structure.
+@end deftypefn
+
+@node Environment Example, , Environment Data, Implementing Environments
+@subsection Environment Example
+
+[[perhaps a simple environment based on association lists]]
+
+
+@node Switching to Environments, , Implementing Environments, Top-Level Environments in Guile
+@section 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.
+
+@itemize @bullet
+
+@item
+For testing purposes, make an utterly minimal version of
+@file{boot-9.scm}: no module system, no R5RS, nothing. I think a simple
+REPL is all we need.
+
+@item
+Implement the environment datatypes in libguile, and test them using
+this utterly minimal system.
+
+@item
+Change the interpreter to use the @code{environment-cell} and
+@code{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.
+
+@item
+Reimplement the current module system in terms of environments. It
+should still be in Scheme.
+
+@item
+Reintegrate the rest of @file{boot-9.scm}. This might be a good point
+to move it into modules.
+
+@item
+Do some profiling and optimization.
+
+@end itemize
+
+Once this is done, we can make the following simplifications to Guile:
+
+@itemize @bullet
+
+@item
+A good portion of symbols.c can go away. Symbols no longer need value
+slots. The mismash of @code{scm_sym2ovcell},
+@code{scm_intern_obarray_soft}, etc. can go away. @code{intern} becomes
+simpler.
+
+@item
+Remove first-class variables: @file{variables.c} and @file{variables.h}.
+
+@item
+Organize the primitives into environments.
+
+@item
+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.
+
+@end itemize
+
+
+
+@node Modules, , Top-Level Environments in Guile, Top
+@chapter 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.
+
+@menu
+* Modules of Guile Primitives::
+* Modules of Interpreted Scheme Code::
+@end menu
+
+@node Modules of Guile Primitives, Modules of Interpreted Scheme Code, Modules, Modules
+@section Modules of Guile Primitives
+
+@node Modules of Interpreted Scheme Code, , Modules of Guile Primitives, Modules
+@section Modules of Interpreted Scheme Code
+
+If a module is implemented by interpreted Scheme code, Guile represents
+it using several environments:
+
+@table @asis
+
+@item the @dfn{local} environment
+This environment holds all the definitions made locally by the module,
+both public and private.
+
+@item the @dfn{import} environment
+This environment holds all the definitions this module imports from
+other modules.
+
+@item the @dfn{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 @var{local} and
+@var{import} environments, with local bindings taking precedence.
+
+@item the @dfn{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
+@var{evaluation} environment, restricted to the set of exported
+definitions.
+
+@end table
+
+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 @code{environment-ref} and @code{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.
+
+
+
+@bye
projects / lilypond.git / blobdiff