gpgscm: Free file names.
[gnupg.git] / tests / gpgscm / Manual.txt
1
2
3                        TinySCHEME Version 1.41
4
5                     "Safe if used as prescribed"
6                     -- Philip K. Dick, "Ubik"
7
8 This software is open source, covered by a BSD-style license.
9 Please read accompanying file COPYING.
10 -------------------------------------------------------------------------------
11
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.
15
16      D. Souflis (dsouflis@acm.org)
17
18 -------------------------------------------------------------------------------
19      What is TinyScheme?
20      -------------------
21
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.
29
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.
35
36      Known bugs
37      ----------
38
39      TinyScheme is known to misbehave when memory is exhausted.
40
41
42      Things that keep missing, or that need fixing
43      ---------------------------------------------
44
45      There are no hygienic macros. No rational or
46      complex numbers. No unwind-protect and call-with-values.
47
48      Maybe (a subset of) SLIB will work with TinySCHEME...
49
50      Decent debugging facilities are missing. Only tracing is supported
51      natively.
52
53
54      Scheme Reference
55      ----------------
56
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.
60
61           Environments
62      (interaction-environment)
63      See R5RS. In TinySCHEME, immutable list of association lists.
64
65      (current-environment)
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":
69
70           (macro (package form)
71                `(apply (lambda ()
72                          ,@(cdr form)
73                          (current-environment))))
74
75      The environment containing the (local) definitions inside the closure
76      is returned as an immutable value.
77
78      (defined? <symbol>) (defined? <symbol> <environment>)
79      Checks whether the given symbol is defined in the current (or given)
80      environment.
81
82           Symbols
83      (gensym)
84      Returns a new interned symbol each time. Will probably move to the
85      library when string->symbol is implemented.
86
87           Directives
88      (gc)
89      Performs garbage collection immediatelly.
90
91      (gc-verbose) (gc-verbose <bool>)
92      The argument (defaulting to #t) controls whether GC produces
93      visible outcome.
94
95      (quit) (quit <num>)
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.
98
99      (tracing <num>)
100      1, turns on tracing. 0 turns it off. (Only when USE_TRACING is 1).
101
102           Mathematical functions
103      Since rationals and complexes are absent, the respective functions
104      are also missing.
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.
110
111           Type predicates
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?.
115
116           Types
117      Types supported:
118
119           Numbers (integers and reals)
120           Symbols
121           Pairs
122           Strings
123           Characters
124           Ports
125           Eof object
126           Environments
127           Vectors
128
129           Literals
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
133      literals, e.g.
134
135           (define s "String with newline here
136           and here
137           that can function like a HERE-string")
138
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.
144      0       #\nul             17       #\dc1
145      1       #\soh             18       #\dc2
146      2       #\stx             19       #\dc3
147      3       #\etx             20       #\dc4
148      4       #\eot             21       #\nak
149      5       #\enq             22       #\syn
150      6       #\ack             23       #\etv
151      7       #\bel             24       #\can
152      8       #\bs              25       #\em
153      9       #\ht              26       #\sub
154      10      #\lf              27       #\esc
155      11      #\vt              28       #\fs
156      12      #\ff              29       #\gs
157      13      #\cr              30       #\rs
158      14      #\so              31       #\us
159      15      #\si
160      16      #\dle             127      #\del
161
162      Numeric literals support #x #o #b and #d. Flonums are currently read only
163      in decimal notation. Full grammar will be supported soon.
164
165           Quote, quasiquote etc.
166      As usual.
167
168           Immutable values
169      Immutable pairs cannot be modified by set-car! and set-cdr!.
170      Immutable strings cannot be modified via string-set!
171
172           I/O
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?
184      (not R5RS).
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.
187
188           Vectors
189      make-vector, vector, vector-length, vector-ref, vector-set!, list->vector,
190      vector-fill!, vector->list, vector-equal? (auxiliary function, not R5RS)
191
192           Strings
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).
198
199           Symbols
200      symbol->string, string->symbol
201
202           Characters
203      integer->char, char->integer.
204      char=?, char<?, char>?, char<=?, char>=?.
205      (No char-ci*?)
206
207           Pairs & Lists
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.
212
213           Streams
214      head, tail, cons-stream
215
216           Control features
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
222      machine itself.
223
224           Property lists
225      TinyScheme inherited from MiniScheme property lists for symbols.
226      put, get.
227
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.
234
235           Esoteric procedures
236      (oblist)
237      Returns the oblist, an immutable list of all the symbols.
238
239      (macro-expand <form>)
240      Returns the expanded form of the macro call denoted by the argument
241
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.
245
246      (new-segment <num>)
247      Allocates more memory segments.
248
249      defined?
250      See "Environments"
251
252      (get-closure-code <closure>)
253      Gets the code as scheme data.
254
255      (make-closure <code> <environment>)
256      Makes a new closure in the given environment.
257
258           Obsolete procedures
259      (print-width <object>)
260
261      Programmer's Reference
262      ----------------------
263
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.
270
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".
279
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.
285
286      The interpreter state should be deinitialized with "scheme_deinit".
287
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.
292
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.
297
298
299      Foreign Functions
300      -----------------
301
302      The user can add foreign functions in C. For example, a function
303      that squares its argument:
304
305           pointer square(scheme *sc, pointer args) {
306            if(args!=sc->NIL) {
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);
310                }
311            }
312            return sc->NIL;
313           }
314
315    Foreign functions are now defined as closures:
316
317    sc->interface->scheme_define(
318         sc,
319         sc->global_env,
320         sc->interface->mk_symbol(sc,"square"),
321         sc->interface->mk_foreign_func(sc, square));
322
323
324      Foreign functions can use the external data in the "scheme" struct
325      to implement any kind of external state.
326
327      External data are set with the following function:
328           void scheme_set_external_data(scheme *sc, void *p);
329
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.
332
333      Standalone
334      ----------
335
336      Usage: tinyscheme -?
337      or:    tinyscheme [<file1> <file2> ...]
338      followed by
339                -1 <file> [<arg1> <arg2> ...]
340                -c <Scheme commands> [<arg1> <arg2> ...]
341      assuming that the executable is named tinyscheme.
342
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.
348
349                #! /somewhere/tinyscheme -1
350                (display *args*)
351
352      The -c flag permits execution of arbitrary Scheme code.
353
354
355      Error Handling
356      --------------
357
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.
362
363      A simple exception handling mechanism can be found in "init.scm".
364      A new syntactic form is introduced:
365
366           (catch <expr returned exceptionally>
367                <expr1> <expr2> ... <exprN>)
368
369      "Catch" establishes a scope spanning multiple call-frames
370      until another "catch" is encountered.
371
372      Exceptions are thrown with:
373
374           (throw "message")
375
376      If used outside a (catch ...), reverts to (error "message").
377
378      Example of use:
379
380           (define (foo x) (write x) (newline) (/ x 0))
381
382           (catch (begin (display "Error!\n") 0)
383                (write "Before foo ... ")
384                (foo 5)
385                (write "After foo"))
386
387      The exception mechanism can be used even by system errors, by
388
389           (define *error-hook* throw)
390
391      which makes use of the error hook described above.
392
393      If necessary, the user can devise his own exception mechanism with
394      tagged exceptions etc.
395
396
397      Reader extensions
398      -----------------
399
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).
405
406
407      Colon Qualifiers - Packages
408      ---------------------------
409
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):
413
414           T(<qualifier>::<symbol>) = (*colon-hook* 'T(<symbol>) <qualifier>)
415
416      where <qualifier> is a symbol not containing any double-colons.
417
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:
424
425           (define toto
426                (package
427                     (define foo 1)
428                     (define bar +)))
429
430           foo                                     ==>  Error, "foo" undefined
431           (eval 'foo)                             ==>  Error, "foo" undefined
432           (eval 'foo toto)                        ==>  1
433           toto::foo                               ==>  1
434           ((eval 'bar toto) 2 (eval 'foo toto))   ==>  3
435           (toto::bar 2 toto::foo)                 ==>  3
436           (eval (bar 2 foo) toto)                 ==>  3
437
438      If the user installs another package infrastructure, he must define
439      a new 'package' procedure or macro to retain compatibility with supplied
440      code.
441
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.