Chapter 2.  Installation and Invocation

Table of Contents

Required Environment
The Read-Eval-Print-Loop
Display Conventions
Running SISC
Command-line Switches
Configuration Parameters
Running Scheme Programs
Loading
Scheme Shell Scripts

Required Environment

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.

The Read-Eval-Print-Loop

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 return

Instructs 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.

Display Conventions

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>}
    

Running SISC

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.

Command-line Switches

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 Commandline Switches

Long SwitchShort SwitchSwitch 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.
--properties <config-file>-p <config-file> Specifies a Java properties file that contains application properties. Typically some of these properties define defaults for 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 commandline is as follows:

  1. Process the entire commandline, noting the settings of each switch and accumulating all Scheme source files and arguments after the end of options sequence.

  2. Load the heap file.

  3. Load each Scheme source file found in the order they occured on the commandline. Note whether any errors occurred.

  4. If present, evaluate the expression in an --eval switch. Note its success or failure.

  5. 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.

  6. If --no-repl was not specified, invoke the REPL, otherwise exit.

  7. 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.

Configuration Parameters

SISC's behaviour is affected by a number of configuration parameters. These fall into two categories:

  1. Static configuration parameters that can only be specified at system startup and apply across all SISC applications that use the same classloader.

  2. 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 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 parameterdefaultdescription
permitInterruptspermit-interruptsfalse If set to true, thread/interrupt is permitted to interrupt running Scheme code, in addition to sending an interrupt signal to the host language.
minFloatPrecisionmin-float-precision16 Specifies the minimum precision, in decimal places, to be maintained by the Quantity lib if using arbitrary precision floats.
maxFloatPrecisionmax-float-precision32 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 sisc..

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”.

Dynamic Parameters

There are four ways to specify a configuration parameter, in decreasing order of precedence:

  1. 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.

  2. 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 “Java-to-Scheme Interface”. 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 Commandline Switches”.

  3. 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.

  4. System defaults. All dynamic configuration parameters have a reasonable default value.

SISC has the following dynamic configuration parameters:

Java property [a]Scheme parameterdefaultdescription
caseSensitivefalse Determines whether symbols read via the Scheme reader are to be treated case sensitively.  
characterSet"UTF8" Defines the default character set used by character ports (see the section called “Character Ports”) if no character set is otherwise specified.  
emitAnnotationsemit-annotationsfalse 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 ”.
emitDebuggingSymbolsemit-debugging-symbolsfalse 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 ”.
printSharedprint-sharedtrue 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.
replPromptrepl-prompt  String to be displayed as part of SISC's REPL prompt.
stackTraceOnErrorstack-trace-on-errorfalse If set to true, whenever an uncaught error is encountered a full stack trace is displayed automatically. See the section called “ Passive Debugging ”.
strictR5RSCompliancestrict-r5rs-compliancefalse If set to true, strictR5RS 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.
vectorLengthPrefixingvector-length-prefixingtrue 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”.

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.

Running Scheme Programs

Loading

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.

  • sll - SISC Compiled Library. This contains expanded and compiled Scheme definitions in a SISC specific representation.

  • scc - SISC Compiled Code. This contains expanded and compiled code in a SISC specific representation. The code gets executed when loaded.

  • shp - (Pronounced sheep) SISC heap file. This file contains all the compiled code loaded when SISC starts up.

Scheme Shell Scripts

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.