Changeset 9610 in project


Ignore:
Timestamp:
03/14/08 19:39:07 (12 years ago)
Author:
sjamaan
Message:

Add wikified docs for sandbox

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/sandbox

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