source: project/wiki/eggref/4/environments @ 24853

Last change on this file since 24853 was 24853, checked in by Mario Domenech Goulart, 9 years ago

environments (wiki): )

File size: 8.6 KB
Line 
1[[tags: egg]]
2
3== environments
4
5User defined first-class environments for dynamically evaluated or interpreted code.
6
7(Note: this egg is obsolete - the internal representation of evaluation environments
8changed with CHICKEN version 4.7.4 and is not any longer supported by this extension.
9There is currently no replacement for the functionality this extension provides, but
10it is planned to create one.)
11
12
13[[toc:]]
14
15
16=== Documentation
17
18This extension provides procedures for creating and manipulating evaluation
19environments. An extension of the Unit eval API.
20
21An evaluation environment can be passed as the second argument to the {{eval}}
22procedure.
23
24Environments can optionally be extendable (evaluated code may create new
25bindings), and selected variables may be mutable or immutable.
26
27The {{(interaction-environment)}} is a special case. All symbols are mutable
28but the environment itself is not mutable.
29
30These environments do not handle syntactic keywords, only normal global
31variables; ''i.e. No Macros!''
32
33==== make-environment
34
35<procedure>(make-environment [EXTENSIBLE?])</procedure>
36
37Returns a fresh, empty environment. If {{EXTENSIBLE?}} is {{#t}}, then
38evaluated code can create new bindings inside this environment.
39
40{{EXTENSIBLE?}} is {{boolean}}. Default is {{#f}}.
41
42==== environment-copy
43
44<procedure>(environment-copy ENV [EXTENSIBLE? [SYMBOLS [MUTABLE?]]])</procedure>
45
46Returns a copy of the environment {{ENV}}.
47
48{{EXTENSIBLE?}} is a {{boolean}}. Default is {{#f}}.
49
50{{SYMBOLS}} is a {{list}} of {{symbol}}, or {{#f}}. Default is {{#f}}.
51
52{{MUTABLE?}} is a {{boolean}}. Default is {{EXTENSIBLE?}}.
53
54If {{EXTENSIBLE?}} is {{#t}}, then evaluated code can create new variable
55bindings inside the environment.
56
57If {{SYMBOLS}} is not {{#f}}, then the environment copy will only contain those
58symbols from the environment {{ENV}}. Otherwise a full copy is made.
59
60If {{MUTABLE?}} is {{#t}}, then evaluated code can set the copied bindings in
61the environment. If {{EXTENSIBLE?}} is not supplied then the copied variable's
62mutable property is used.
63
64''Note'' that the only way to supply a {{MUTABLE?}} value is to supply an
65{{EXTENSIBLE?}} value.
66
67==== environment?
68
69<procedure>(environment? X) => boolean</procedure>
70
71Is {{X}} an evaluation environment?
72
73==== interaction-environment?
74
75<procedure>(interaction-environment? X) => boolean</procedure>
76
77Is {{X}} the {{interaction-environment}}?
78
79==== environment-empty?
80
81<procedure>(environment-empty? ENV) => boolean</procedure>
82
83Is the environment {{ENV}} sans bindings?
84
85When {{ENV}} is the {{(interaction-environment)}} this procedure
86always returns {{#f}}.
87
88==== environment-extendable?
89
90<procedure>(environment-extendable? ENV) => boolean</procedure>
91
92Is the environment {{ENV}} extensible?
93
94==== environment-has-binding?
95
96<procedure>(environment-has-binding? ENV SYMBOL) => boolean</procedure>
97
98Is the variable {{SYMBOL}} bound in the environment {{ENV}}?
99
100==== environment-includes?
101
102<procedure>(environment-includes? ENV SYMBOL) => boolean</procedure>
103
104Is a variable {{SYMBOL}} in the environment {{ENV}}?
105
106When {{ENV}} is the {{(interaction-environment)}} this procedure
107always returns {{#t}}.
108
109==== environment-mutable?
110
111<procedure>(environment-mutable? ENV SYMBOL) => boolean</procedure>
112
113Is the variable {{SYMBOL}} in environment {{ENV}} mutable?
114
115When {{ENV}} is the {{(interaction-environment)}} this procedure
116always returns {{#t}}.
117
118==== environment-set-mutable!
119
120<procedure>(environment-set-mutable! ENV SYMBOL MUTABLE?)</procedure>
121
122Makes the variable {{SYMBOL}} in environment {{ENV}} mutable, if {{MUTABLE?}}
123is {{#t}}, immutable otherwise.
124
125No effect when called with the {{(interaction-environment)}}.
126
127==== environment-ref
128
129<procedure>(environment-ref ENV SYMBOL) => *</procedure>
130
131Returns the value of the variable {{SYMBOL}} in environment {{ENV}}.
132
133If the environment does not contain the variable, or if the variable is not
134bound, an error is signaled.
135
136==== environment-set!
137
138<procedure>(environment-set! ENV SYMBOL VALUE)</procedure>
139
140Updates the binding {{SYMBOL}} in environment {{ENV}} with {{VALUE}}. A non-existent
141binding will be created as mutable.
142
143It is an error to attempt to create a new binding in an inextensible
144environment.
145
146Changing the value of an existing immutable variable will succeed.
147
148==== environment-extend!
149
150<procedure>(environment-extend! ENV SYMBOL [VALUE [MUTABLE?]])</procedure>
151
152Adds a new binding {{SYMBOL}} in environment {{ENV}}.
153
154If the optional argument {{MUTABLE?}} is not given or {{#t}}, then the binding
155is mutable and can be changed by evaluating {{(set! VARIABLE ...)}}.
156
157The variable {{SYMBOL}} is initialized to {{VALUE}}, or is unbound, if
158{{VALUE}} is not given.
159
160Here the creation of a new variable in an inextensible environment will
161succeed.
162
163Changing the value of an immutable variable will succeed.
164
165==== environment-remove!
166
167<procedure>(environment-remove! ENV SYMBOLS [SILENT? [INEXTENSIBLE?]])</procedure>
168
169Removes bindings {{SYMBOLS}} in environment {{ENV}}.
170
171{{SYMBOLS}} is a {{list}} of {{symbol}}, or a {{symbol}}.
172
173{{SILENT?}} is a {{boolean}}. Default is {{#f}}.
174
175{{INEXTENSIBLE?}} is a {{boolean}}. Default is {{#t}}.
176
177Wiil not remove from an inextensible environment, unless {{INEXTENSIBLE?}} is
178{{#t}}.
179
180It is an error to attempt to remove an undefined symbol, unless {{SILENT?}} is
181{{#t}}.
182
183It is an error to attempt to remove from an inextensible environment when
184{{INEXTENSIBLE?}} is {{#f}}, unless {{SILENT?}} is {{#t}}.
185
186==== environment-symbols
187
188<procedure>(environment-symbols ENV) => list</procedure>
189
190Returns a list of the symbols in the given environment.
191
192==== environment-for-each
193
194<procedure>(environment-for-each ENV PROC)</procedure>
195
196Calls {{PROC}} with each binding in the given environment.
197
198{{PROC}} is a {{(procedure (symbol *))}} where the first argument is the
199variable name and the second is the value.
200
201
202=== Examples
203
204<enscript highlight="scheme">
205(use environments)
206
207; create an immutable environment with all R5RS procedures:
208(define my-env
209(environment-copy (scheme-report-environment 5) #f) )
210
211(eval '(set! car 99) my-env)
212 => ; .. Error
213
214(eval '(define abc 100) my-env)
215 => ; .. Error
216
217(environment-extend! my-env 'abc 100)
218
219(eval 'abc my-env)
220 => 100
221(eval '(set! abc 101) my-env)
222(eval 'abc my-env)
223 => 101
224
225(environment-set-mutable! my-env 'abc #f)
226(eval '(set! abc #f) my-env)
227 => ; .. Error
228</enscript>
229
230
231=== Author
232
233[[/users/felix-winkelmann|Felix Winkelmann]]
234
235[[/users/kon-lovett|Kon Lovett]]
236
237
238=== Changelog
239
240; 1.6.2 : obsoleted
241; 1.6.0 : Added {{interaction-environment?}} & {{environment-empty?}}. Added inextensible flag to {{environmet-remove!}}, [Kon Lovett]
242; 1.53 : Ported to Chicken 4
243; 1.52 : Minor code cleanup - no semantic changes [Kon Lovett]
244; 1.51 :
245; 1.5 : Bug fix {{environment-set!}} [Kon Lovett]
246; 1.4 : {{environment-copy}} symbol filtering, extended interaction-environment support, added {{environment-symbols}} [Kon Lovett]
247; 1.3 : Fixed bug in {{environment-has-binding?}} [reported by Mario Domenech Goulart]
248; 1.2 : Added {{environment-for-each}}
249; 1.1 : Fixed bug in {{environment-includes?}} with the interaction-environment, added {{environment-mutable?}} and {{environment-extendable?}}
250; 1.0 : Initial release
251
252
253=== License
254
255  Copyright (c) 2003-2011, Felix L. Winkelmann
256  All rights reserved.
257
258  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
259  conditions are met:
260
261    Redistributions of source code must retain the above copyright notice, this list of conditions and the following
262      disclaimer.
263    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
264      disclaimer in the documentation and/or other materials provided with the distribution.
265    Neither the name of the author nor the names of its contributors may be used to endorse or promote
266      products derived from this software without specific prior written permission.
267
268  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
269  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
270  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
271  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
272  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
273  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
274  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
275  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
276  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.