S9(1) Scheme 9 from Empty Space S9(1)
NAME
s9 - Scheme Interpreter
USAGE
s9 [-h?] [!name] [-gnqv] [-m size[m]] [-f prog [args]]
[-l prog] [-t count] [-d image] [-- [args]]
DESCRIPTION
Scheme 9 from Empty Space is an interpreter for R4RS Scheme
with some additional procedures for accessing typical Unix
system calls and Unix and Curses library functions (if
compiled-in). The s9 command starts the interpreter.
OPTIONS
-h or -?
Display a brief summary of options.
-d file
Dump heap image to file and exit.
-f program [arguments]
Run program and exit (implies -q). When there are any
arguments, they are passed to the program, where they
can be extracted using the command-line procedure.
-g
Print GC summaries (-gg = more verbose).
-n
Do not load $HOME/.s9fes/rc file, if any.
-l program
Load program before entering the REPL or processing -f
(may be repeated).
-m N[m]
Set memory limit to N kilo (or mega) nodes (-m 0 means
no limit; use with care!).
-q
Be quiet: skip banners and prompts, exit on errors.
-t count
Display count procedures at most in call traces.
-v
Display version and exit.
-- [argument ...]
Arguments following -- are not interpreted by S9fES, but
passed to the command-line procedure instead (requires
the unix extension).
When the first argument of s9 starts with an exclamation
point, the remainder of that argument is used as the name of
the interpreter (instead of the name that was used to invoke
s9). This option allows one to load alternative heap image
files.
ONLINE HELP
When the interpreter is running and the default heap image
is loaded, just type (help) or ,h to invoke the online help
system. When the online help system is not loaded, you will
have to run the following command first:
S9 Interpreter Page 1 S9(1)
S9(1) Scheme 9 from Empty Space S9(1)
(load-from-library "help.scm")
META COMMANDS
In order to facilitate the invocation of frequently-used
top-level procedures, s9 provides the following "meta
commands" (they work only when entered directly at the s9
prompt):
,a text = (apropos "text")
,h text = (help "text")
,l file = (load-from-library "file")
,q = (sys:exit)
The arguments of ,a and ,h are optional.
ADDITIONS
S9fES supports nestable block comments of the form
#| comment ... |#.
These S9fES procedures are not in R4RS:
(bit-op integer1 integer2 integer3) ==> integer | #f
Implement a variety of bitwise logic operations. See the
bit-op help page for details.
(delete-file string) ==> unspecific
Delete the file specified in the string argument. If the
file does not exist or cannot be deleted, report an
error.
(dump-image string) ==> unspecific
Write a heap image to the file given in the string
argument. If the file already exists, report an error.
(error string) ==> undefined
(error string object) ==> undefined
Print an error message of the form error: string: object
and terminate program execution.
(exponent real) ==> integer
Extract the exponent part from a real number.
(file-exists? string) ==> boolean
Return #t if the file specified in the string argument
exists and otherwise #f.
(fold-left proc base list ...) ==> object
Combine the elements of the lists using proc. Combine
elements left-associatively. Base is the leftmost
element.
(fold-right proc base list ...) ==> object
Combine the elements of the lists using proc. Combine
elements right-associatively. Base is the rightmost
element.
(gensym) ==> symbol
S9 Interpreter Page 2 S9(1)
S9(1) Scheme 9 from Empty Space S9(1)
(gensym string) ==> symbol
Return a fresh symbol. When a string argument is given,
use it as prefix for the fresh symbol.
(load-from-library string) ==> unspecific
Attempt to load the file string from each directory of
S9FES_LIBRARY_PATH.
(locate-file string) ==> string | #f
Search for the file string in each directory of
S9FES_LIBRARY_PATH in sequence. When the file can be
located, return its full path, else return #f.
(macro-expand object) ==> object
(macro-expand-1 object) ==> object
If object is a list resembling a macro application,
return the expanded form, else return the object.
Macro-expand-1 expands macros only once while macro-
expand expands them recursively.
(mantissa real) ==> integer
Extract the mantissa part from a real number.
(print object ...) ==> unspecific
Write multiple objects separated by spaces.
(require-extension name ...) ==> unspecific
Require the named extensions to be compiled-in. Signal
an error if not all of the required extensions are
present.
(reverse! list) ==> list
Reverse list destructively and return the reverse list.
(set-input-port! input-port) ==> unspecific
Destructively set the current input port.
(set-output-port! output-port) ==> unspecific
Destructively set the current output port.
(stats form) ==> form
Evaluate the given form and return a list containing its
normal form plus the resources used to compute that
normal form:
- reduction steps
- conses allocated
- total nodes allocated
- garbage collections
Each resource count will be returned as a group of
integers representing ones, thousands, millions, etc.
Note that form must be quoted or it will be evaluated
before passing it to stats.
(symbols) ==> list
Return a list of all defined symbols.
S9 Interpreter Page 3 S9(1)
S9(1) Scheme 9 from Empty Space S9(1)
(syntax? object) ==> boolean
Check whether object is a syntax object (i.e.: a macro).
(trace symbol ...) ==> list | #t
(trace #t) ==> list | #t
Trace the procedure or syntax object bound to the given
symbols. When #t is passed to trace, trace all
procedures and syntax objects (expect lots of output!).
When no arguments are passed to it, disable tracing.
Trace returns the symbols that were being traced before
its invocation.
(void) ==> unspecific
Return an unspecific value.
Refer to the help pages for descriptions of the Scheme 9
extension procedures.
SPECIAL VARIABLES
These variables are predefined in the dynamic top-level
scope of the interpreter.
** (form)
The normal form of the expression most recently
evaluated at the top level.
*extensions* (list of symbols)
Compiled-in extensions.
*library-path* (string)
A verbatim copy of the S9FES_LIBRARY_PATH environment
variable (see below).
*loading* (boolean)
Set to #t when loading a file, else #f.
MACROS
A macro is a procedure that is applied to its unevaluated
arguments. The macro application is replaced with the value
returned by the procedure. This happens before the
expression containing the macro application is evaluated, so
a macro rewrites its own application:
(define-syntax (when p . c)
`(if ,p (begin ,@c)))
(macro-expand '(when (= 1 1) (display "true") (newline) #t))
==> (if (= 1 1)
(begin (display "true")
(newline)
#t))
(when (= 1 1) 1 2 3) ==> 3
The define-syntax form introduces a new macro:
(define-syntax name procedure) ==> unspecific
(define-syntax (name args ...) body) ==> unspecific
Both of these forms introduce the keyword name and bind it
to a procedure. The first form requires the second argument
to be a procedure. Like in define forms the second variant
implies a procedure definition.
S9 Interpreter Page 4 S9(1)
S9(1) Scheme 9 from Empty Space S9(1)
Macros may contain applications of macros that were defined
earlier. Macros may not recurse directly, but they may
implement recursion internally using letrec or by rewriting
their own applications. The following macro, for example,
does not work, because d is undefined in the body of d:
(define-syntax (d x) (and (pair? x) (d (cdr x)))) ; wrong
The following version does work, though:
(define-syntax (d x) (and (pair? x) `(d ,(cdr x)))) ; OK
The body of define-syntax may be a syntax-rules transformer,
as described in R4RS, if the syntax-rules extension has been
loaded.
TECHNICAL DETAILS
S9fES is a tree-walking interpreter using deep binding and
hashed environments. It employs an extremely reliable[1]
constant-space mark and sweep garbage collector with in-situ
string and vector pool compaction. Memory pools grow on
demand. The interpreter uses arbitrary-precision integer
arithmetics and (optional) decimal-based real number
arithmetics.
INTERPRETER START-UP
When the s9 interpreter is started, the following steps will
be performed in this order:
Load library.
The interpreter searches its library path (either built-
in or specified in the S9FES_LIBRARY_PATH environment
variable) for a heap image file or the library source
code. The heap image file is the name of the interpreter
with a .image suffix appended. An alternative name can
be specified with the !-option (see OPTIONS). The
library source code is always named s9.scm. The first
directory containing either a heap image or the library
source code is used. When the directory contains both an
image and the library sources, the image is loaded.
Initialize extensions.
Any extensions compiled into the interpreter are
initialized by calling the nullary procedure ext:ext
(where ext is the name of the extension). The procedures
are optional. The first `extension' being initialized is
S9 itself, so when a procedure named s9:s9 exists, it
will be called at this point.
Evaluate command line options.
When a -l file option is found, the program contained in
the given file will be loaded. When a -f file args
option is found, the program contained in the file will
be run and then S9 will exit. Args will be passed to
the program.
Load rc file.
If an `rc file' ($HOME/.s9fes/rc) exists, it will be
S9 Interpreter Page 5 S9(1)
S9(1) Scheme 9 from Empty Space S9(1)
loaded at this point as if its name was passed to the
load procedure. (Unless the -n option was specified.)
Enter REPL.
Interactive mode is only entered if no -f options was
specified.
ALLOCATION STRATEGY
The S9fES memory pool grows exponentially until the memory
limit its reached. When the limit is reached, the current
computation is aborted. A memory limit can be specified
using the -m command line option. The limit is specified in
units of 1024 nodes (or in units of 1024*1024 nodes by
appending an m suffix).
Note that computations may abort before the limit is reached
due to the way the pool grows. Use the -g command line
option to experiment with pool sizes.
Specifying a limit of zero disables the memory limit
completely and the interpreter will allocate as much memory
as it can get. This option should be used with care.
LIMITATIONS
These parts of R4RS are not implemented:
I/O: char-ready? (this is in the sys-unix extension).
Transcripts: transcript-off, transcript-on.
Rational and complex numbers and related procedures.
BUGS
You may not quasiquote quasiquote unless in unquote (e.g.:
``x does not work, but `,`x does).
Syntax-rules is not fully hygienic.
Call/cc sometimes does not interact well with binding
constructs. (Try not to bind more than a single call/cc in
the same lambda.)
FILES
$HOME/.s9fes/rc
If present, this file is loaded when the interpreter
starts in interactive mode.
/usr/share/s9fes
The S9fES procedure library (source code).
/usr/lib/s9fes/contrib
Contributions to the procedure library (source code).
/usr/lib/s9fes/s9.image
The interpreter heap image.
*.scm
Scheme source code.
ENVIRONMENT
S9FES_LIBRARY_PATH
A colon-separated list of directories which will be
searched for the s9 library when the interpreter is
launched. The same directories will be searched by the
locate-file procedure.
Default: .:~/.s9fes:/usr/lib/s9fes:/usr/share/s9fes
S9 Interpreter Page 6 S9(1)
S9(1) Scheme 9 from Empty Space S9(1)
SIGNALS
These work only if POSIX signal handling was enabled at
compile time.
SIGINT
Abort input or terminate program execution.
SIGQUIT
Terminate the interpreter process (emergency exit).
FOOTNOTES
[1] See comp.lang.scheme Usenet message
<vhtzl9lupyp.fsf@maharal.csail.mit.edu>
(Thu, 27 Aug 2009 13:27:42 -0400) and its follow-ups.
REFERENCES
The Revised^4 Report on the Algorithmic Language Scheme.
http://www-swiss.ai.mit.edu/~jaffer/r4rs_toc.html
Scheme 9 from Empty Space -- A Guide to Implementing Scheme
in C.
http://www.lulu.com/content/9378374
AUTHOR
Nils M Holm < n m h at t 3 x . o r g >
S9 Interpreter Page 7 S9(1)