back

environments

Description:

User defined first-class environments for dynamically evaluated or interpreted code.

Author:

felix

Version:

Requires:

Usage:

(require-extension environments)

Download:

environments.egg

Documentation:

This extension provides procedures for creating and manipulating evaluation environments. An extension of the eval unit's procedures.

An evaluation environment can be passed as the second argument to the eval procedure.

Environments can optionally be extendable (evaluated code may create new bindings), and selected variables may be mutable or immutable.

The (interaction-environment) is a special case. All symbols are mutable but the environment itself is not mutable.

These environments do not handle syntactic keywords, only normal global variables; i.e. No Macros!

[procedure] (environment? X)
Returns #t if X is an environment, or #f otherwise.
[procedure] (environment-copy ENV [FLAG [SYMBOLS]])
Returns a copy of the environment ENV. If the optional argument FLAG is given and true, then evaluated code can create new variable bindings inside the newly created environment and bindings in the environment may not be modified by evaluated code. If the optional argument SYMBOLS is given and is a list of symbols, then the environment copy will only contain those symbols from the environment ENV.
[procedure] (environment-extendable? ENV)
Returns #t if the environment ENV is extendable or #f otherwise.
[procedure] (environment-extend! ENV SYMBOL [VALUE [MUTABLE]])
Adds a new binding for the variable SYMBOL in environment ENV. If the optional argument MUTABLE is not given or true, then the binding is mutable and can be changed by evaluating (set! VARIABLE ...). The variable is initialized to VALUE, or is unbound, if VALUE is not given. Creation of a new symbol in an inextensible environment will succeed. Changing the value of an immutable variable will succeed.
[procedure] (environment-has-binding? ENV SYMBOL)
Returns #t when the variable SYMBOL has a value in environment ENV, or #f otherwise.
[procedure] (environment-includes? ENV SYMBOL)
Returns #t if the environment has a binding for the variable SYMBOL, or #f otherwise. When called with the value of (interaction-environment) then this procedure returns always #t.
[procedure] (environment-ref ENV SYMBOL)
Returns the value of the variable SYMBOL in environment ENV. If the environment does not contain the variable, or if the variable is not bound, an error is signaled.
[procedure} (environment-remove! ENV SYMBOL [SILENT? #f])
Removes binding for variable SYMBOL in environment ENV. SYMBOL may also be a list of symbols. It is an error to attempt to remove an undefined symbol, unless SILENT? is #t.
[procedure] (environment-set! ENV SYMBOL VALUE)
Changes the binding for the variable SYMBOL in environment ENV to VALUE. When the SYMBOL does not exist in environment ENV the SYMBOL is created with VALUE if ENV is extensible, otherwise an error is signaled. Changing the value of an immutable variable will succeed.
[procedure] (environment-mutable? ENV SYMBOL)
Returns #t if the variable SYMBOL in environment ENV is mutable or #f otherwise. 
[procedure] (environment-set-mutable! ENV SYMBOL FLAG)
Makes the variable SYMBOL in environment ENV mutable, if FLAG is true, or immutable, if not. This procedure has no effect when called with the value of (interaction-environment).
[procedure] (make-environment [FLAG])
Returns a fresh empty environment. If the optional argument FLAG is given and true, then evaluated code can create new bindings inside this environment.
[procedure] (environment-for-each ENV PROC)
Calls PROC with the name and value of each global binding in the given environment.
[procedure] (environment-symbols ENV)
Returns a list of the symbols in the given environment.

Examples:

; create an immutable environment with all R5RS procedures:
(define my-env
  (environment-copy (scheme-report-environment 5) #f) )

(eval '(set! car 99) my-env)     ;==>   Error
(eval '(define abc 100) my-env)  ;==>   Error

(environment-extend! my-env 'abc 100)

(eval 'abc my-env)               ;==>   100
(eval '(set! abc 101) my-env)
(eval 'abc my-env)               ;==>   101

(environment-set-mutable! my-env 'abc #f)
(eval '(set! abc #f) my-env)     ;==>   Error

License:

Copyright (c) 2003, Felix L. Winkelmann
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:

  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
    disclaimer.
  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
    disclaimer in the documentation and/or other materials provided with the distribution.
  Neither the name of the author nor the names of its contributors may be used to endorse or promote
    products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
back