3 TinySCHEME Version 1.41
5 "Safe if used as prescribed"
6 -- Philip K. Dick, "Ubik"
8 This software is open source, covered by a BSD-style license.
9 Please read accompanying file COPYING.
10 -------------------------------------------------------------------------------
12 This Scheme interpreter is based on MiniSCHEME version 0.85k4
13 (see miniscm.tar.gz in the Scheme Repository)
14 Original credits in file MiniSCHEMETribute.txt.
16 D. Souflis (dsouflis@acm.org)
18 -------------------------------------------------------------------------------
22 TinyScheme is a lightweight Scheme interpreter that implements as large
23 a subset of R5RS as was possible without getting very large and
24 complicated. It is meant to be used as an embedded scripting interpreter
25 for other programs. As such, it does not offer IDEs or extensive toolkits
26 although it does sport a small top-level loop, included conditionally.
27 A lot of functionality in TinyScheme is included conditionally, to allow
28 developers freedom in balancing features and footprint.
30 As an embedded interpreter, it allows multiple interpreter states to
31 coexist in the same program, without any interference between them.
32 Programmatically, foreign functions in C can be added and values
33 can be defined in the Scheme environment. Being a quite small program,
34 it is easy to comprehend, get to grips with, and use.
39 TinyScheme is known to misbehave when memory is exhausted.
42 Things that keep missing, or that need fixing
43 ---------------------------------------------
45 There are no hygienic macros. No rational or
46 complex numbers. No unwind-protect and call-with-values.
48 Maybe (a subset of) SLIB will work with TinySCHEME...
50 Decent debugging facilities are missing. Only tracing is supported
57 If something seems to be missing, please refer to the code and
58 "init.scm", since some are library functions. Refer to the MiniSCHEME
59 readme as a last resort.
62 (interaction-environment)
63 See R5RS. In TinySCHEME, immutable list of association lists.
66 The environment in effect at the time of the call. An example of its
67 use and its utility can be found in the sample code that implements
68 packages in "init.scm":
73 (current-environment))))
75 The environment containing the (local) definitions inside the closure
76 is returned as an immutable value.
78 (defined? <symbol>) (defined? <symbol> <environment>)
79 Checks whether the given symbol is defined in the current (or given)
84 Returns a new interned symbol each time. Will probably move to the
85 library when string->symbol is implemented.
89 Performs garbage collection immediately.
91 (gc-verbose) (gc-verbose <bool>)
92 The argument (defaulting to #t) controls whether GC produces
96 Stops the interpreter and sets the 'retcode' internal field (defaults
97 to 0). When standalone, 'retcode' is returned as exit code to the OS.
100 1, turns on tracing. 0 turns it off. (Only when USE_TRACING is 1).
102 Mathematical functions
103 Since rationals and complexes are absent, the respective functions
105 Supported: exp, log, sin, cos, tan, asin, acos, atan, floor, ceiling,
106 trunc, round and also sqrt and expt when USE_MATH=1.
107 Number-theoretical quotient, remainder and modulo, gcd, lcm.
108 Library: exact?, inexact?, odd?, even?, zero?, positive?, negative?,
109 exact->inexact. inexact->exact is a core function.
112 boolean?,eof-object?,symbol?,number?,string?,integer?,real?,list?,null?,
113 char?,port?,input-port?,output-port?,procedure?,pair?,environment?',
114 vector?. Also closure?, macro?.
119 Numbers (integers and reals)
130 String literals can contain escaped quotes \" as usual, but also
131 \n, \r, \t, \xDD (hex representations) and \DDD (octal representations).
132 Note also that it is possible to include literal newlines in string
135 (define s "String with newline here
137 that can function like a HERE-string")
139 Character literals contain #\space and #\newline and are supplemented
140 with #\return and #\tab, with obvious meanings. Hex character
141 representations are allowed (e.g. #\x20 is #\space).
142 When USE_ASCII_NAMES is defined, various control characters can be
143 referred to by their ASCII name.
162 Numeric literals support #x #o #b and #d. Flonums are currently read only
163 in decimal notation. Full grammar will be supported soon.
165 Quote, quasiquote etc.
169 Immutable pairs cannot be modified by set-car! and set-cdr!.
170 Immutable strings cannot be modified via string-set!
173 As per R5RS, plus String Ports (see below).
174 current-input-port, current-output-port,
175 close-input-port, close-output-port, input-port?, output-port?,
176 open-input-file, open-output-file.
177 read, write, display, newline, write-char, read-char, peek-char.
178 char-ready? returns #t only for string ports, because there is no
179 portable way in stdio to determine if a character is available.
180 Also open-input-output-file, set-input-port, set-output-port (not R5RS)
181 Library: call-with-input-file, call-with-output-file,
182 with-input-from-file, with-output-from-file and
183 with-input-output-from-to-files, close-port and input-output-port?
185 String Ports: open-input-string, open-output-string, get-output-string,
186 open-input-output-string. Strings can be used with I/O routines.
189 make-vector, vector, vector-length, vector-ref, vector-set!, list->vector,
190 vector-fill!, vector->list, vector-equal? (auxiliary function, not R5RS)
193 string, make-string, list->string, string-length, string-ref, string-set!,
194 substring, string->list, string-fill!, string-append, string-copy.
195 string=?, string<?, string>?, string>?, string<=?, string>=?.
196 (No string-ci*? yet). string->number, number->string. Also atom->string,
197 string->atom (not R5RS).
200 symbol->string, string->symbol
203 integer->char, char->integer.
204 char=?, char<?, char>?, char<=?, char>=?.
208 cons, car, cdr, list, length, map, for-each, foldr, list-tail,
209 list-ref, last-pair, reverse, append.
210 Also member, memq, memv, based on generic-member, assoc, assq, assv
211 based on generic-assoc.
214 head, tail, cons-stream
217 Apart from procedure?, also macro? and closure?
218 map, for-each, force, delay, call-with-current-continuation (or call/cc),
219 eval, apply. 'Forcing' a value that is not a promise produces the value.
220 There is no call-with-values, values, nor dynamic-wind. Dynamic-wind in
221 the presence of continuations would require support from the abstract
225 TinyScheme inherited from MiniScheme property lists for symbols.
228 Dynamically-loaded extensions
229 (load-extension <filename without extension>)
230 Loads a DLL declaring foreign procedures. On Unix/Linux, one can make use
231 of the ld.so.conf file or the LD_RUN_PATH system variable in order to place
232 the library in a directory other than the current one. Please refer to the
233 appropriate 'man' page.
237 Returns the oblist, an immutable list of all the symbols.
239 (macro-expand <form>)
240 Returns the expanded form of the macro call denoted by the argument
242 (define-with-return (<procname> <args>...) <body>)
243 Like plain 'define', but makes the continuation available as 'return'
244 inside the procedure. Handy for imperative programs.
247 Allocates more memory segments.
252 (get-closure-code <closure>)
253 Gets the code as scheme data.
255 (make-closure <code> <environment>)
256 Makes a new closure in the given environment.
259 (print-width <object>)
261 Programmer's Reference
262 ----------------------
264 The interpreter state is initialized with "scheme_init".
265 Custom memory allocation routines can be installed with an alternate
266 initialization function: "scheme_init_custom_alloc".
267 Files can be loaded with "scheme_load_file". Strings containing Scheme
268 code can be loaded with "scheme_load_string". It is a good idea to
269 "scheme_load" init.scm before anything else.
271 External data for keeping external state (of use to foreign functions)
272 can be installed with "scheme_set_external_data".
273 Foreign functions are installed with "assign_foreign". Additional
274 definitions can be added to the interpreter state, with "scheme_define"
275 (this is the way HTTP header data and HTML form data are passed to the
276 Scheme script in the Altera SQL Server). If you wish to define the
277 foreign function in a specific environment (to enhance modularity),
278 use "assign_foreign_env".
280 The procedure "scheme_apply0" has been added with persistent scripts in
281 mind. Persistent scripts are loaded once, and every time they are needed
282 to produce HTTP output, appropriate data are passed through global
283 definitions and function "main" is called to do the job. One could
284 add easily "scheme_apply1" etc.
286 The interpreter state should be deinitialized with "scheme_deinit".
288 DLLs containing foreign functions should define a function named
289 init_<base-name>. E.g. foo.dll should define init_foo, and bar.so
290 should define init_bar. This function should assign_foreign any foreign
291 function contained in the DLL.
293 The first dynamically loaded extension available for TinyScheme is
294 a regular expression library. Although it's by no means an
295 established standard, this library is supposed to be installed in
296 a directory mirroring its name under the TinyScheme location.
302 The user can add foreign functions in C. For example, a function
303 that squares its argument:
305 pointer square(scheme *sc, pointer args) {
307 if(sc->isnumber(sc->pair_car(args))) {
308 double v=sc->rvalue(sc->pair_car(args));
309 return sc->mk_real(sc,v*v);
315 Foreign functions are now defined as closures:
317 sc->interface->scheme_define(
320 sc->interface->mk_symbol(sc,"square"),
321 sc->interface->mk_foreign_func(sc, square));
324 Foreign functions can use the external data in the "scheme" struct
325 to implement any kind of external state.
327 External data are set with the following function:
328 void scheme_set_external_data(scheme *sc, void *p);
330 As of v.1.17, the canonical way for a foreign function in a DLL to
331 manipulate Scheme data is using the function pointers in sc->interface.
337 or: tinyscheme [<file1> <file2> ...]
339 -1 <file> [<arg1> <arg2> ...]
340 -c <Scheme commands> [<arg1> <arg2> ...]
341 assuming that the executable is named tinyscheme.
343 Use - in the place of a filename to denote stdin.
344 The -1 flag is meant for #! usage in shell scripts. If you specify
345 #! /somewhere/tinyscheme -1
346 then tinyscheme will be called to process the file. For example, the
347 following script echoes the Scheme list of its arguments.
349 #! /somewhere/tinyscheme -1
352 The -c flag permits execution of arbitrary Scheme code.
358 Errors are recovered from without damage. The user can install his
359 own handler for system errors, by defining *error-hook*. Defining
360 to '() gives the default behavior, which is equivalent to "error".
361 USE_ERROR_HOOK must be defined.
363 A simple exception handling mechanism can be found in "init.scm".
364 A new syntactic form is introduced:
366 (catch <expr returned exceptionally>
367 <expr1> <expr2> ... <exprN>)
369 "Catch" establishes a scope spanning multiple call-frames
370 until another "catch" is encountered.
372 Exceptions are thrown with:
376 If used outside a (catch ...), reverts to (error "message").
380 (define (foo x) (write x) (newline) (/ x 0))
382 (catch (begin (display "Error!\n") 0)
383 (write "Before foo ... ")
387 The exception mechanism can be used even by system errors, by
389 (define *error-hook* throw)
391 which makes use of the error hook described above.
393 If necessary, the user can devise his own exception mechanism with
394 tagged exceptions etc.
400 When encountering an unknown character after '#', the user-specified
401 procedure *sharp-hook* (if any), is called to read the expression.
402 This can be used to extend the reader to handle user-defined constants
403 or whatever. It should be a procedure without arguments, reading from
404 the current input port (which will be the load-port).
407 Colon Qualifiers - Packages
408 ---------------------------
410 When USE_COLON_HOOK=1:
411 The lexer now recognizes the construction <qualifier>::<symbol> and
412 transforms it in the following manner (T is the transformation function):
414 T(<qualifier>::<symbol>) = (*colon-hook* 'T(<symbol>) <qualifier>)
416 where <qualifier> is a symbol not containing any double-colons.
418 As the definition is recursive, qualifiers can be nested.
419 The user can define his own *colon-hook*, to handle qualified names.
420 By default, "init.scm" defines *colon-hook* as EVAL. Consequently,
421 the qualifier must denote a Scheme environment, such as one returned
422 by (interaction-environment). "Init.scm" defines a new syntantic form,
423 PACKAGE, as a simple example. It is used like this:
430 foo ==> Error, "foo" undefined
431 (eval 'foo) ==> Error, "foo" undefined
432 (eval 'foo toto) ==> 1
434 ((eval 'bar toto) 2 (eval 'foo toto)) ==> 3
435 (toto::bar 2 toto::foo) ==> 3
436 (eval (bar 2 foo) toto) ==> 3
438 If the user installs another package infrastructure, he must define
439 a new 'package' procedure or macro to retain compatibility with supplied
442 Note: Older versions used ':' as a qualifier. Unfortunately, the use
443 of ':' as a pseudo-qualifier in existing code (i.e. SLIB) essentially
444 precludes its use as a real qualifier.