EnvironmentsMIT.md edited online with Bitbucket

EnvironmentsMIT.md

@@ -6,10 +6,10 @@ These environments can be passed to `eval` as a second argument, but otherwise
 cannot be controlled or manipulated.
 
 In R5RS there were only three such environments; R6RS and R7RS added the ability
-to create environments based on a set of import specifiers.  The environments
+to create novel environments based on a set of import specifiers.  The environments
 of this SRFI are built on top of those environments, but add the ability to
-create, obtain, and destroy bindings and to dcreate either fully mutable
-or mutable environments, as well as an inheritance relationship
+create, obtain, and destroy bindings and to create either fully mutable
+or immutable environments, as well as an inheritance relationship
 between environments that makes them a forest of trees.
 
 ## Constructors
@@ -20,18 +20,19 @@ Returns a unique fully mutable environment containing an implementation-specifie
 set of bindings.  On R6RS systems, at least the `(rnrs base`) bindings must be
 included; on R7RS systems, at least the `(scheme base)` bindings must be included.
 The intention is that this environment is the one used to
-evaluate expressions entered to the system REPL.
+evaluate expressions and definitions entered to the system REPL.
 
 `(scheme-report-environment `*version*`)`  [R5RS, R6RS, R7RS]
 
 If *version* is the exact integer 5, returns an environment containing the bindings
-of the R5RS (in R5RS and R6RS systems) or of the `(scheme r5rs)` library (in R7RS
-systems).  These are almost but not quite the same (e.g. `transcript-on` and
-`transcript-off` are not part of the R7RS library).  The returned environment may
-be mutable or immutable.
+of the R5RS in R5RS systems, of the `(rnrs r5rs)` library in R6RS systems,
+or of the `(scheme r5rs)` library in R7RS systems.
+These are almost but not quite the same (e.g. `transcript-on` and
+`transcript-off` are not part of the R6RS or R7RS libraries).
+The returned environment may be mutable or immutable.
 
 Implementations may also support other values of *version*,
-in which case they return a specifier for an environment
+in which case they return an environment
 containing bindings corresponding to the specified version
 of the report. If version is neither 5 nor another value
 supported by the implementation, an error is signaled.
@@ -43,7 +44,7 @@ except that only syntactic keywords are bound and not variables.
 
 `(environment `*list* ...`)`  [R6RS, R7RS]
 
-This procedure returns a specifier for the environment that
+This procedure returns the environment that
 results by starting with an empty environment and then
 importing each list, considered as an import set, into it.
 In R6RS systems, the 
@@ -56,7 +57,12 @@ itself is immutable (no bindings may be added or removed).
 Creates and returns a newly allocated environment that inherits
 from *environment*.  If a lookup in this environment does not
 find a suitable binding, *environment* (known as the parent
-environment) will be searched next.
+environment) will be searched next.  The new environment is mutable.
+
+`(make-empty-environment)`
+
+Creates and returns a newly allocated environment with no bindings.
+The new environment is mutable.
 
 ## Predicates
 
@@ -73,7 +79,8 @@ Returns `#t` if *env* has a parent environment and
 `#f` if it does not.  It is unspecified whether the interaction
 environment, as well as environments returned by
 `scheme-report-environment` and `null-environment`, have parents or not.
-Environments returned by `environment` do not have parents.
+Environments returned by `environment` and `make-empty-environment`
+do not have parents.
 
 `(environment-bound? `*environment symbol*`)`
 
@@ -84,10 +91,9 @@ Returns `#t` if *symbol* is bound in *env*, and `#f` otherwise.
 Returns `#t` if *symbol* is not only bound in *env* but
 assigned to a value, and `#f` otherwise.
 
-Such unassigned symbols may arise from the
-expansion of `letrec` or `letrec*`, although they are not normally
-observable.  In addition, a Scheme implementation may treat all
-possible symbols as bound, but not necessarily assigned, in the
+Such unassigned symbols cannot be created by ordinary Scheme operations.
+However, a Scheme implementation may treat all
+possible symbols as bound but not necessarily assigned in the
 interaction environment.
 
 `(environment-assignable? `*env symbol*`)`
@@ -97,9 +103,10 @@ Returns `#t` if *symbol* is assignable in *env*
 
 `(environment-definable? `*env symbol*`)`
 
-Returns `#t` if *symbol* is definable in *env*
-(it is either bound and can be assigned, or is unbound and
-can be bound in the environment), and `#f` otherwise.
+Returns `#t` if *symbol* is definable in *env*.
+In other words, *symbol* is either bound and can be assigned
+or is unbound and can be bound and assigned in the environment).
+Otherwise, `#f` is returned.
 
 ## Accessors
 
@@ -111,12 +118,13 @@ Returns the parent environment of *env*; it is an error if
 `(environment-bound-names `*env*`)`
 
 Returns a list of all the names bound in *env*, excluding those
-bound only in the ancestors of *env*.  It is an error to mutate
-this list.
+bound only in the ancestors of *env*.  However, if the environment
+treats all symbols as bound, it need not return every possible
+synbol.  It is an error to mutate this list.
 
 `(environment-bindings `*env*`)`
 
-Returns a list of the bindings in *env*, *env*, excluding those
+Returns a list of the bindings in *env*, excluding those
 bound only in the ancestors of *env*.  However, if the environment
 treats all symbols as bound, it need not return every possible
 synbol.  It is an error to mutate this list.
@@ -128,14 +136,15 @@ is the assigned value.
 `(environment-reference-type `*env symbol*`)`
 
 Returns a symbol, one of `unbound`, `unassigned`, `macro`, or `normal`
-representing the status of *symbol* in *env* and its ancestors.
-The difference between `macro` and `normal` is that the former means that
-*symbol* is a syntactic keyword, whereas *normal* means it represents a variable.
+that represents the status of *symbol* in *env* and its ancestors.
+The difference between `macro` and `normal` is that `macro` means that
+*symbol* is a syntactic keyword, whereas `normal` means it represents a variable.
 
 `(environment-lookup `*env symbol*`)`
 
 Returns the assigned value of `symbol` in *env* or its ancestors.  It is an
-error if *symbol* is not a normal symbol in the sense of `environment-reference-type`.
+error if *symbol* is not a normal symbol in the environment
+in the sense of `environment-reference-type`.
 
 `(environment-lookup-macro `*env symbol*`)`
 
@@ -145,8 +154,8 @@ whose implementation is system-dependent.
 
 ## Mutators
 
-It is an error to invoke any of the following procedures on an immutable environment.
-They all return an unspecified value.
+Except as noted, it is an error to invoke any of the following procedures
+on an immutable environment.  They all return an unspecified value.
 
 `(environment-freeze! `*env*`)`
 
@@ -189,6 +198,8 @@ implementation of it, with the following exceptions:
 
   *  The `make-environment` procedure is called `make-top-level-environment`.
 
+  *  The `make-empty-environment` procedure is called `make-root-top-level-environment`.
+
   *  The `environment-unbind` procedure is called `unbind-variable`, although it
      can unbind any name, not just a variable.
 
@@ -204,9 +215,11 @@ implementation of it, with the following exceptions:
 
      3. Populate the new environment with the appropriate R5RS bindings
         using the `link-variables` procedure, which accepts four arguments:
-        the source environment, which is always `user-interaction-environment`, the bound
+        the source environment, which is `system-global-environment`, the bound
         symbol, the new environment, and the symbol to be bound (always the same
-        as the second argument in this use).
+        as the second argument in this use).  However, the names `interaction-environment`,
+        `scheme-report-environment`, and `null-environment` must be linked from
+        `initial-user-environment` rather than `system-global-environment`.
 
      4. Return the new environment.