Table of Contents
SISC primarily targets the Java Virtual Machine, and the Java v1.3 and higher class libraries. The 1.2 libraries and VM are required due to a reliance on memory reference functionality used to properly garbage collect unused symbols while still maintaining pointer equality between those that remain active, while the 1.3 libraries are needed for the proxy functionality of the Java bridge library.
SISC does not require any particular operating system, though the official distribution currently provides launching assistance for Windows and Unix based systems. Theoretically any machine that supports Java 1.3 or higher should be able to run SISC.
As in most Scheme systems, SISC'ss primary human interface is a
REPL, or Read-Eval-Print-Loop. SISC presents the user with a
prompt ('#;>'), then reads an
s-expression from the console. SISC then evaluates the
s-expression, producing a value or error, which it then prints.
Finally the process begins again with a new prompt.
The process terminates with a forced kill of the JVM (with
Control-C or similar), or when an end of file is detected on
the console. Also, the exit procedure may
be used to exit the current REPL.
procedure:
(exit [return-value]) => does not returnInstructs the current REPL to exit. If the optional return value is given, the value will be passed out of the REPL to the calling code or environment.
Evaluation may be prematurely interrupted on some platforms by sending SIGQUIT (usually by pressing Control-C) to the SISC process. If supported, this will cause an interrupted error to be raised at whichever expression is currently being evaluated in the REPL thread. If not caught, this will cause the error to be raised at the console and a new prompt will be displayed. Issuing the signal twice will terminate SISC.
Executing or loading code in the REPL ordinarily produces a value result which is displayed during the Print phase. However, two other message types may be displayed. First, if an error is raised that is not handled by the running program, the message will be described in one of several forms, depending on what combinations of a location, a message, and a parent message the error has:
Error.
Error in <error-location>.
Error: <description>
Error in <error-location>: <description>
Error in nested call.
<nested-error>
Error in nested call: <description>
<nested-error>
Error in nested call from <error-location>.
<nested-error>
Error in nested call from <error-location>: <description>
<nested-error>
The location of an error often refers to the name of a procedure, syntax, or parameter. Errors that do not contain a location often originate in an anonymous function. Nested errors occur when one function makes a call to another function and the second raises an error. If the first function wishes, it may catch this error and generate its own, with the second functions error as a parent. Thus a nested error consists of an error message on the first line, and the nested error message or messages on following lines.
In addition to errors, it is possible for code to produce warnings during compilation or run-time. A warning is a message to the user about a condition that is unusual but not terminal to the program flow. The compiler, for example, does a minimal amount of sanity checking on code and may produce warnings about code that has the potential to raise errors during execution. Warnings are always distinguished from ordinary messages by surrounding braces ({}) and starting with the word 'warning'.
{warning: <description>}
SISC's official distribution provides a startup script for Windows and Unix based hosts. Simply executing this script starts the SISC REPL. Zero or more Scheme source files can also be specified on the command line after the script name, which will be loaded in order before the REPL prompt is displayed.
It may be desirable to pass options to the underlying JVM. This
can be done by setting the JAVAOPT
environment variable to the options you wish to pass to the
JVM. This includes switches for heap size, system properties,
etc. SISC itself has a number of properties that can affect
its operation. See the section called “Configuration Parameters”
for a list of these properties and their meanings.
SISC can, in addition to loading Scheme source programs, also accept a few command-line switches to change its behavior. Any non-switch argument is considered a Scheme source file to load on startup, until the end of options characters "--" are reached. Any item after those characters are considered arguments to the function specified in the "call-with-args" switch.
All command-line switches have both a short and long form. These forms are equivalent in meaning.
Table 2.1. SISC Command line Switches
| Long Switch | Short Switch | Switch meaning |
|---|---|---|
--call-with-args <name> | -c <name> |
Call the top-level procedure name
with the remaining command-line arguments after the
"--" sequence.
|
--eval <expression> | -e <expression> | Evaluate the provided expression. |
--no-repl | -x | Exit after loading all the Scheme source files and processing all command-line switches. |
--heap <heap-file> | -h <heap-file> | File containing pre-compiled code and data for a complete Scheme top-level environment. This parameter is mandatory if the heap cannot be located automatically. |
--properties <config-file> | -p <config-file> | Specifies a Java properties file that contains application properties. Typically some of these properties define defaults for configuration parameters (the section called “Configuration Parameters”. The file can be specified as a URL. |
--listen [<host>:]<port> | -l [<host>:]<port> | Listen on host/port for REPL connections, i.e. connecting to the specified host/port will create a new REPL. |
The order of processing the command line is as follows:
Process the entire command line, noting the settings of each switch and accumulating all Scheme source files and arguments after the end of options sequence.
Load the heap file.
Load each Scheme source file found in the order they occured on the command line. Note whether any errors occurred.
If present, evaluate the expression in an
--eval switch. Note its success
or failure.
If present, apply the named function in a
--call-with-args switch to the
arguments after the end of options sequence. Note its
return value.
If --no-repl was not specified, invoke
the REPL, otherwise exit.
If the REPL was run if its return value is an integer, return that integer as SISC's overall return code. If the REPL was not run, and any return code supporting step above was run, return the most recent return code. If no return code step was performed, but a success/failure step was performed, return 1 if any failures occured, 0 otherwise.
SISC's behaviour is affected by a number of configuration parameters. These fall into two categories:
Static configuration parameters that can only be specified at system startup and apply across all SISC applications that use the same classloader.
Dynamic configuration parameters that can be altered on a per-thread basis without impacting other threads. These kind of parameters are also called "thread locals", or, in Scheme terminology, dynamic parameters.
Static configuration parameters can be set using Java system properties. Their value can be retrieved with a Scheme function, but it is not possible to alter it. Static configuration parameters default to pre-defined system-internal settings if left unspecified.
SISC has the following static configuration parameters:
| Java property [a] | Scheme parameter | default | description |
|---|---|---|---|
permitInterrupts | permit-interrupts | true |
If set to true,
thread/interrupt is
permitted to interrupt running Scheme code, in
addition to sending an interrupt signal to the
host language.
|
minFloatPrecision | min-float-precision | 16 | Specifies the minimum precision, in decimal places, to be maintained by the Quantity lib if using arbitrary precision floats. |
maxFloatPrecision | max-float-precision | 32 | Specifies the maximum precision, in decimal places, to be maintained by the Quantity lib if using arbitrary precision floats. |
[a]
The names of all properties for configuration
parameters must be prefixed with
| |||
When static configuration parameters are retrieved with their associated Scheme function, the value is of the type specified for the parameter. See the section called “Value Conversion”.
There are four ways to specify a configuration parameter, in decreasing order of precedence:
Invoking a scheme function. Dynamic configuration parameters are special Scheme parameters (see the section called “ Parameters ”. Invoking the parameter with a value sets the parameter for the current thread without affecting other dynamic contexts / threads.
Defining an application property. A single SISC runtime can host multiple applications simultaneously. Application properties define default values for dynamic configuration parameters across all dynamic contexts / threads of an application. They can be specified at application initialisation time. See the section called “Calling Scheme from Java”. When SISC is started from the command line, the location of a Java properties file containing application properties can be specified with a command line option. See Table 2.1, “SISC Command line Switches”.
Defining a Java system property. Java system properties define default values for dynamic configuration parameters that apply across all applications inside a single SISC runtime.
System defaults. All dynamic configuration parameters have a reasonable default value.
SISC has the following dynamic configuration parameters:
| Java property [a] | Scheme parameter | default | description |
|---|---|---|---|
caseSensitive
| case-sensitive | false | Determines whether symbols read via the Scheme reader are to be treated case sensitively. |
characterSet
| character-set | "UTF8" | Defines the default character set used by character ports (see the section called “Character Ports”) if no character set is otherwise specified. |
emitAnnotations | emit-annotations | true |
If set to true, this parameter
causes source files loaded with
load or
import, as well as source
entered in the console, to be annotated by the
Scheme reader. Annotations include source file
location information, which simplifies debugging.
See the section called “
Passive Debugging
”.
|
emitDebuggingSymbols | emit-debugging-symbols | true |
If set to true, additional
annotations useful for debugging, such as function
and variable names, are produced by SISC's
compiler. See the section called “
Passive Debugging
”.
|
maxStackTraceDepth | max-stack-trace-depth | 0 |
Specifies the maximum depth of virtual call
stacks, which are used to obtain proper stack
traces even in the presence of tail recursion and
continuation capture and invocation, while still
preserving tail-call semantics and safe-for-space
guarantees. See Chapter 4,
Debugging Facilities
. Collecting this information
is computationally expensive, so this feature is
turned off by default. A value of
16 is about right for debugging
most applications. Large values allow collection
of more information but carry a large performance
penalty, small values result in some call
information being lost.
|
permissiveParsing | permissive-parsing | false |
If set to true, the Scheme parser
will warn rather than raise an error for various syntactic errors
such as unbalanced parentheses. This allows one to
continue parsing a syntactically invalid file, finding many errors
at once.
|
printShared | print-shared | true |
If set to true,
write and the REPL detect
shared structures in data and invoke a version of
write capable of emitting the
shared structure's external representation of
data. See the section called “Writing”. The user may
wish to set this parameter to
false because of the overhead
of both scanning all data, and constructing this
representation when shared structures are
detected.
|
replPrompt | repl-prompt | String to be displayed as part of SISC's REPL prompt. | |
stackTraceOnError | stack-trace-on-error | true |
If set to true, whenever an
uncaught error is encountered a full stack trace
is displayed automatically. See the section called “
Passive Debugging
”.
|
strictR5RSCompliance | strict-r5rs-compliance | false |
If set to true,
strict R5RS syntax and
semantics are followed. This will cause SISC to
raise errors in all situations described as "an
error" in the Scheme standard. This will override
and invalidate all the interpretation liberties
described in Appendix B, R5RS Liberties and Violations.
|
synopsisLength | synopsis-length | 30 |
Limit on the length (in characters) of the
external representation of data structures in
error messages and warnings. When the limit is
reached, an ellipsis (...) is
appended to the curtailed external representation.
|
vectorLengthPrefixing | vector-length-prefixing | true |
If set to true, this parameter
will instruct the pretty-printer to emit length
prefixed, trailing-duplicate-eliminated vectors in
its output. If false, ordinary
full-length vectors without prefixes will be
emitted. See the section called “
Vectors
”.
|
When dynamic configuration parameters are retrieved or set with their associated Scheme function, the value is of the type specified for the parameter. See the section called “Value Conversion”.
When specifying configuration parameters via Java
properties, a Java-like notation is used, e.g. boolean
parameters are specified as true and
false. By contrast, when getting and
setting configuration parameters from Scheme, their values
are of the appropriate Scheme type, e.g. boolean parameters
are specified as #t and
#f. Strings and symbols undergo a
similiar conversion; they are specified without their
double/single quotes in the Java properties.
For parameter types other than boolean, string and symbol, Java properties are read as Scheme values, i.e. Scheme literal notation should be used in the properties.
SISC supports loading Scheme programs using the R5RS
optional procedure load. A number of
file types for loading Scheme code are supported. The common
extensions are:
scm - Scheme source code
sce - Scheme code expanded. This type
of code has been processed by the syntax expander and
contains only core Scheme forms.
scc - SISC Compiled Code. This
contains expanded and compiled code in a SISC specific
representation. The code gets executed when loaded.
In addition to code loaded, SISC requires a heap,
which contains the default set of libraries and functions for the
initial environment. SISC will look for a heap file called sisc.shp
in the current directory, the directory referenced by the SISC_HOME
environment variable, and as a resource paired with the HeapAnchor
class in the sisc.boot package of the classpath.
The standard SISC distribution contains sisc.shp in the
same directory as the supporting .jar files.
It isn't uncommon to want the heap to reside on the classpath, where it
can be more easily resolved in applets or in web applications. This file,
usually called sisc-heap.jar can be added to the classpath
in any usual fashion, and the heap loading routines will discover it if
not found elsewhere. To create a jar file containing the heap, create the
following file structure in the
jar:
sisc/
sisc/boot/
sisc/boot/HeapAnchor.class
sisc/boot/sisc.shp
The HeapAnchor.class class file is distributed in the
sisc-opt.jar file of the full binary distribution.
On Unix or Unix-like systems, SISC supports SRFI-22, a mechanism for writing shell-like scripts that can be invoked directly as executable programs. The text of the SRFI, which can be found at http://srfi.schemers.org, describes how such programs are written.