chickadee » environments

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

environments

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

(Note: this egg is obsolete - the internal representation of evaluation environments changed with CHICKEN version 4.7.4 and is not any longer supported by this extension. There is currently no replacement for the functionality this extension provides, but it is planned to create one.)

Documentation

This extension provides procedures for creating and manipulating evaluation environments. An extension of the Unit eval API.

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!

make-environment

make-environment #!optional EXTENSIBLE?procedure

Returns a fresh, empty environment. If EXTENSIBLE? is #t, then evaluated code can create new bindings inside this environment.

EXTENSIBLE? is boolean. Default is #f.

environment-copy

environment-copy ENV #!optional EXTENSIBLE? SYMBOLS MUTABLE?procedure

Returns a copy of the environment ENV.

EXTENSIBLE? is a boolean. Default is #f.

SYMBOLS is a list of symbol, or #f. Default is #f.

MUTABLE? is a boolean. Default is EXTENSIBLE?.

If EXTENSIBLE? is #t, then evaluated code can create new variable bindings inside the environment.

If SYMBOLS is not #f, then the environment copy will only contain those symbols from the environment ENV. Otherwise a full copy is made.

If MUTABLE? is #t, then evaluated code can set the copied bindings in the environment. If EXTENSIBLE? is not supplied then the copied variable's mutable property is used.

Note that the only way to supply a MUTABLE? value is to supply an EXTENSIBLE? value.

environment?

environment? Xprocedure

Is X an evaluation environment?

interaction-environment?

interaction-environment? Xprocedure

Is X the interaction-environment?

environment-empty?

environment-empty? ENVprocedure

Is the environment ENV sans bindings?

When ENV is the (interaction-environment) this procedure always returns #f.

environment-extendable?

environment-extendable? ENVprocedure

Is the environment ENV extensible?

environment-has-binding?

environment-has-binding? ENV SYMBOLprocedure

Is the variable SYMBOL bound in the environment ENV?

environment-includes?

environment-includes? ENV SYMBOLprocedure

Is a variable SYMBOL in the environment ENV?

When ENV is the (interaction-environment) this procedure always returns #t.

environment-mutable?

environment-mutable? ENV SYMBOLprocedure

Is the variable SYMBOL in environment ENV mutable?

When ENV is the (interaction-environment) this procedure always returns #t.

environment-set-mutable!

environment-set-mutable! ENV SYMBOL MUTABLE?procedure

Makes the variable SYMBOL in environment ENV mutable, if MUTABLE? is #t, immutable otherwise.

No effect when called with the (interaction-environment).

environment-ref

environment-ref ENV SYMBOLprocedure

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.

environment-set!

environment-set! ENV SYMBOL VALUEprocedure

Updates the binding SYMBOL in environment ENV with VALUE. A non-existent binding will be created as mutable.

It is an error to attempt to create a new binding in an inextensible environment.

Changing the value of an existing immutable variable will succeed.

environment-extend!

environment-extend! ENV SYMBOL #!optional VALUE MUTABLE?procedure

Adds a new binding SYMBOL in environment ENV.

If the optional argument MUTABLE? is not given or #t, then the binding is mutable and can be changed by evaluating (set! VARIABLE ...).

The variable SYMBOL is initialized to VALUE, or is unbound, if VALUE is not given.

Here the creation of a new variable in an inextensible environment will succeed.

Changing the value of an immutable variable will succeed.

environment-remove!

environment-remove! ENV SYMBOLS #!optional SILENT? INEXTENSIBLE?procedure

Removes bindings SYMBOLS in environment ENV.

SYMBOLS is a list of symbol, or a symbol.

SILENT? is a boolean. Default is #f.

INEXTENSIBLE? is a boolean. Default is #t.

Wiil not remove from an inextensible environment, unless INEXTENSIBLE? is #t.

It is an error to attempt to remove an undefined symbol, unless SILENT? is #t.

It is an error to attempt to remove from an inextensible environment when INEXTENSIBLE? is #f, unless SILENT? is #t.

environment-symbols

environment-symbols ENVprocedure

Returns a list of the symbols in the given environment.

environment-for-each

environment-for-each ENV PROCprocedure

Calls PROC with each binding in the given environment.

PROC is a (procedure (symbol *)) where the first argument is the variable name and the second is the value.

Examples

(use environments)

; 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

Author

Felix Winkelmann

Kon Lovett

Changelog

1.6.2

obsoleted (the whole egg is obsolete)

1.6.0

Added interaction-environment? & environment-empty?. Added inextensible flag to environmet-remove!, [Kon Lovett]

1.53

Ported to Chicken 4

1.52

Minor code cleanup - no semantic changes [Kon Lovett]

1.51

1.5

Bug fix environment-set! [Kon Lovett]

1.4

environment-copy symbol filtering, extended interaction-environment support, added environment-symbols [Kon Lovett]

1.3

Fixed bug in environment-has-binding? [reported by Mario Domenech Goulart]

1.2

Added environment-for-each

1.1

Fixed bug in environment-includes? with the interaction-environment, added environment-mutable? and environment-extendable?

1.0

Initial release

License

 Copyright (c) 2003-2011, 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.