source: project/wiki/eggref/4/sandbox @ 32241

Last change on this file since 32241 was 32241, checked in by felix winkelmann, 6 years ago

removed some call/cc.org links

File size: 8.5 KB
Line 
1[[tags: egg]]
2
3== sandbox
4
5[[toc:]]
6
7=== Description
8
9Safe evaluation of basic Scheme expressions.
10
11=== Author
12
13[[/users/felix winkelmann|felix winkelmann]]
14
15=== Requirements
16
17[[matchable]]
18
19=== Documentation
20
21This extension provides a ''safe'' evaluation context for basic Scheme
22expressions (R5RS without optional, input- or output forms). The
23following standard Scheme procedures are not available:
24
25  display
26  write
27  read
28  read-char
29  peek-char
30  write-char
31  eof-object?
32  char-ready?
33  newline
34  open-input-file
35  open-output-file
36  close-input-port
37  close-output-port
38  with-input-from-file
39  with-output-from-file
40  call-with-input-file
41  call-with-output-file
42  input-port?
43  output-port?
44  current-input-port
45  current-output-port
46  load
47  transcript-on
48  transcript-off
49  null-environment
50  scheme-report-environment
51  interaction-environment
52
53{{eval}} is provided but does only accept a single argument.
54
55Runaway evaluation (for example by executing endless loops) and
56excessive allocation can be caught by specifying appropriate limits on
57execution time and storage.  The execution environment is fully thread
58safe.
59
60==== safe-eval
61
62<procedure> (safe-eval EXPRESSION #!key ENVIRONMENT FUEL ALLOCATION-LIMIT)</procedure>
63
64Evaluates {{EXPRESSION}} in a safe evaluation context. {{FUEL}}
65specifies how much ''fuel'' the pre-translation and evaluation has
66before an exception will be raised. {{ALLOCATION-LIMIT}} gives (a
67rough) estimation over the maximal size of storage that may be
68allocated during the evalution of {{EXPRESSION}}. {{FUEL}} and
69{{ALLOCATION-LIMIT}} default to {{#f}}, meaning no limit is given.
70
71{{ENVIRONMENT}} specifies the evaluation environment that should be
72used, and defaults to the value of {{default-safe-environment}}.
73
74Should an error occur during the execution of EXPRESSION, a composite
75condition of the original error condition and a condition of the kind
76{{sandbox}} will be signalled.
77
78Note that de-allocation is not tracked, only allocation.
79
80==== current-fuel
81
82<parameter>current-fuel</parameter>
83
84A parameter holding the current amount ''fuel''. If this counter
85reaches zero during the pre-translation or execution of an evaluated
86expression an error is signalled. The initial value is {{#f}}, meaning
87no limit is given.
88
89==== current-allocation-limit
90
91<parameter>current-allocation-limit</parameter>
92
93A parameter holding the current maximum storage that an evaluated
94expression may allocate. If the total size of allocated storage
95exceeds this limit (given in bytes) and error is signalled. The
96initial value is {{#f}}, meaning no limit is given.
97
98Note that this limit is a rough estimate.
99
100==== safe-environment?
101
102<procedure>(safe-environment? X)</procedure>
103
104Returns {{#t}} if {{X}} is a safe environment object or {{#f}} otherwise.
105
106==== current-safe-environment
107
108<parameter>current-safe-environment</parameter>
109
110A parameter holding the current evaluation environment. The initial
111value is the value of {{default-safe-environment}}.
112
113==== default-safe-environment
114
115<constant>default-safe-environment</constant>
116
117An evaluation environment containing a basic R5RS environment without I/O procedures.</dd>
118
119==== make-safe-environment
120
121<procedure>(make-safe-environment #!key NAME PARENT MUTABLE EXTENDABLE)</procedure>
122
123Creates a fresh evaluation environment with a given {{NAME}} and
124parent environment {{PARENT}}. Whn a binding is looked up and can not
125be found in the current environment, then the chain of parent
126environments will be checked for a matching binding.
127
128If {{MUTABLE}} is not given or false, then this environment is not
129mutable and bindings in this environment may not be changed with
130{{set!}}. If {{EXTENDABLE}} is not given or true, then the environment
131may be extended with new global bindings.
132
133==== safe-environment-ref
134
135<procedure>(safe-environment-ref ENVIRONMENT ID [DEFAULT])</procedure>
136
137Returns the current value of the variable named {{ID}} in
138{{ENVIRONMENT}} or {{DEFAULT}} if the {{ENVIRONMENT}} or it's parent
139environments do not contain a binding with this name. If {{DEFAULT}}
140is not given, {{#f}} will be returned.
141
142==== safe-environment-set!
143
144<procedure>(safe-environment-set! ENVIRONMENT ID VALUE)</procedure>
145
146Sets the value of the variable named {{ID}} in {{ENVIRONMENT}} to
147value, creating a new binding if no variable with this name exists (it
148doesn't check the parent environment).  Use this procedure to add
149additional primitives to an evaluation context:
150
151<enscript highlight=scheme>
152(define my-env
153  (make-safe-environment parent: default-safe-environment) )
154
155(safe-environment-set!
156  my-env 'hello
157  (lambda (arg)
158    (display "Hello, ")
159    (display arg)
160    (display "!\n") ) )
161
162(safe-eval '(hello "you") environment: my-env)
163
164; prints:
165
166Hello, you!
167</enscript>
168
169This procedure doesn't care whether an environment is mutable (or extendable) or not.
170
171==== safe-environment-remove!
172
173<procedure>(safe-environment-remove! ENVIRONMENT ID)</procedure>
174
175Removes the binding for {{ID}} in the given environment or does nothing if no such binding exists.
176
177==== safe-environment-macro-set!
178
179<procedure>(safe-environment-macro-set! ENVIRONMENT ID PROC)</procedure>
180
181Defines or changes the macro-expander procedure for the macro with the
182name {{ID}} to {{PROC}}, which should be a procedure of one argument,
183the list of arguments (unevaluated) passed to the macro.
184
185==== safe-environment-macro-remove!
186
187<procedure>(safe-environment-macro-remove! ENVIRONMENT ID)</procedure>
188
189Removes the macro-binding for {{ID}} in the given environment or does
190nothing if no such binding exists.
191
192=== Example
193
194<enscript highlight="scheme">
195(safe-eval 123)
196 => 123
197
198(safe-eval 'abc)
199 => ;; error
200
201(define env (make-safe-environment))
202(safe-eval '(+ 3 4) environment: env)
203 => ;; error: environment is empty and has no parent
204
205(define env2 (make-safe-environment parent: default-safe-environment))
206(safe-eval '(+ 3 4) environment: env2)
207 => 7
208
209(safe-eval '(define abc 99) environment: env2)
210(safe-eval 'abc environment: env2)
211 => 99
212
213(safe-eval '(define abc 99) environment: (make-safe-environment extendable: #f))
214 => ;; error
215
216(safe-eval '(set! + 100))
217 => ;; error: binding not mutable
218
219(safe-eval '(set! + 100) environment: env2)
220 => ;; error: the same (binding is inherited)
221
222(safe-eval '(set! abc 100) environment: env2)
223 => ;; error
224
225(safe-eval '(let loop () (loop)))
226 => ;; never terminates
227
228(safe-eval '(let loop () (loop)) fuel: 1000)
229 => ;; error ("out of fuel")
230
231(safe-eval '(make-vector 100))
232 => ;; a 100-element vector
233
234(safe-eval '(make-vector 100) allocation-limit: 100)
235 => ;; error ("allocation limit exceeded")
236</enscript>
237
238=== Changelog
239
240* 1.7 setup-script fixes [Thanks to Christian, once again]
241* 1.6 ported to CHICKEN 4 [Thanks to Christian Kellermann]
242* 1.5 {{apply}} didn't handle circular lists [Thanks to Goran Weinholt]
243* 1.4 Added proper setup script; uses trace-buffer and lambda-info
244* 1.3 Fixed problem with older chicken versions [Thanks to Alejandro Forero Cuervo]
245* 1.2 Keyword fix was incorrect [Thanks to Alex again]
246* 1.1 {{safe-eval}} now handles keywords [Thanks to Alex Shinn]; added internal support for extended number types
247* 1.0 Initial release
248
249=== License
250
251  Copyright (c) 2004, Felix L. Winkelmann
252  All rights reserved.
253 
254  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
255  conditions are met:
256 
257    Redistributions of source code must retain the above copyright notice, this list of conditions and the following
258      disclaimer.
259    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
260      disclaimer in the documentation and/or other materials provided with the distribution.
261    Neither the name of the author nor the names of its contributors may be used to endorse or promote
262      products derived from this software without specific prior written permission.
263 
264  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
265  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
266  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
267  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
268  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
269  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
270  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
271  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
272  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.