Go to the first, previous, next, last section, table of contents.


Operational Features

Invoking SCM

scm [-a kbytes] [-ibvqmu] [-p number] [-c expression] [-e expression] [-f filename] [-l filename] [-r feature] [-- | - | -s] [filename] [arguments ...]

Upon startup scm loads the file specified by by the environment variable SCM_INIT_PATH.

If SCM_INIT_PATH is not defined or if the file it names is not present, scm tries to find the directory containing the executable file. If it is able to locate the executable, scm looks for the initialization file (usually `Init5c4.scm') in platform-dependent directories relative to this directory. See section File-System Habitat for a blow-by-blow description.

As a last resort (if initialization file cannot be located), the C compile parameter IMPLINIT (defined in the makefile or `scmfig.h') is tried.

Unless the option -no-init-file or --no-init-file occurs in the command line, `Init5c4.scm' checks to see if there is file `ScmInit.scm' in the path specified by the environment variable HOME (or in the current directory if HOME is undefined). If it finds such a file it is loaded.

`Init5c4.scm' then looks for command input from one of three sources: From an option on the command line, from a file named on the command line, or from standard input.

This explanation applies to SCMLIT or other builds of SCM.

Scheme-code files can also invoke SCM and its variants. See section Syntax Extensions.

Options

The options are processed in the order specified on the command line.

Command Option: -a kb
specifies that scm should allocate an initial heapsize of kb kilobytes. This option, if present, must be the first on the command line. If not specified, the default is INIT_HEAP_SIZE in source file `setjump.h' which the distribution sets at 25000*sizeof(cell).

Command Option: -no-init-file
Command Option: --no-init-file
Inhibits the loading of `ScmInit.scm' as described above.

Command Option: -e expression
Command Option: -c expression
specifies that the scheme expression expression is to be evaluated. These options are inspired by perl and sh respectively. On Amiga systems the entire option and argument need to be enclosed in quotes. For instance `"-e(newline)"'.

Command Option: -r feature
requires feature. This will load a file from [SLIB] if that feature is not already supported. If feature is 2, 3, 4, or 5 scm will require the features neccessary to support [R2RS], [R3RS], [R4RS], or proposed [R5RS], respectively.

Command Option: -l filename
Command Option: -f filename
loads filename. Scm will load the first (unoptioned) file named on the command line if no -c, -e, -f, -l, or -s option preceeds it.

Command Option: -p level
sets the prolixity (verboseness) to level. This is the same as the scm command (verobse level).

Command Option: -v
(verbose mode) specifies that scm will print prompts, evaluation times, notice of loading files, and garbage collection statistics. This is the same as -p3.

Command Option: -q
(quiet mode) specifies that scm will print no extra information. This is the same as -p0.

Command Option: -m
specifies that subsequent loads, evaluations, and user interactions will be with [R4RS] macro capability. To use a specific [R4RS] macro implementation from [SLIB] (instead of [SLIB]'s default) put -r macropackage before -m on the command line.

Command Option: -u
specifies that subsequent loads, evaluations, and user interactions will be without [R4RS] macro capability. [R4RS] macro capability can be restored by a subsequent -m on the command line or from Scheme code.

Command Option: -i
specifies that scm should run interactively. That means that scm will not terminate until the (quit) or (exit) command is given, even if there are errors. It also sets the prolixity level to 2 if it is less than 2. This will print prompts, evaluation times, and notice of loading files. The prolixity level can be set by subsequent options. If scm is started from a tty, it will assume that it should be interactive unless given a subsequent -b option.

Command Option: -b
specifies that scm should run non-interactively. That means that scm will terminate after processing the command line or if there are errors.

Command Option: -s
specifies, by analogy with sh, that further options are to be treated as program aguments.

Command Option: -
Command Option: --
specifies that there are no more options on the command line.

Command Option: -d filename
loads SLIB database-utilities and opens filename as a database.

Command Option: -o filename
saves the current SCM session as the executable program `filename'. This option works only in SCM builds supporting dump (see section Dump).

If options appear on the command line after `-o filename', then the saved session will continue with processing those options when it is invoked. Otherwise the (new) command line is processed as usual when the saved image is invoked.

Command Option: --help
prints usage information and URL; then exit.

Command Option: --version
prints version information and exit.

Invocation Examples

% scm foo.scm
Loads and executes the contents of `foo.scm' and then enters interactive session.
% scm -f foo.scm arg1 arg2 arg3
Parameters arg1, arg2, and arg3 are stored in the global list *argv*; Loads and executes the contents of `foo.scm' and exits.
% scm -s foo.scm arg1 arg2
Sets *argv* to ("foo.scm" "arg1" "arg2") and enters interactive session.
% scm -e `(write (list-ref *argv* *optind*))' bar
Prints `"bar"'.
% scm -rpretty-print -r format -i
Loads pretty-print and format and enters interactive session.
% scm -r5
Loads dynamic-wind, values, and [R4RS] macros and enters interactive (with macros) session.
% scm -r5 -r4
Like above but rev4-optional-procedures are also loaded.

Environment Variables

Environment Variable: SCM_INIT_PATH
is the pathname where scm will look for its initialization code. The default is the file `Init5c4.scm' in the source directory.

Environment Variable: SCHEME_LIBRARY_PATH
is the [SLIB] Scheme library directory.

Environment Variable: HOME
is the directory where `Init5c4.scm' will look for the user initialization file `ScmInit.scm'.

Environment Variable: EDITOR
is the name of the program which ed will call. If EDITOR is not defined, the default is `ed'.

Scheme Variables

Variable: *argv*
contains the list of arguments to the program. *argv* can change during argument processing. This list is suitable for use as an argument to [SLIB] getopt.

Variable: *R4RS-macro*
controls whether loading and interaction support [R4RS] macros. Define this in `ScmInit.scm' or files specified on the command line. This can be overridden by subsequent -m and -u options.

Variable: *interactive*
controls interactivity as explained for the -i and -b options. Define this in `ScmInit.scm' or files specified on the command line. This can be overridden by subsequent -i and -b options.

SCM Session

Function: quit
Function: quit n
Function: exit
Function: exit n
Aliases for exit (see section `System' in SLIB). On many systems, SCM can also tail-call another program. See section I/O-Extensions.

Function: program-arguments
Returns a list of strings of the arguments scm was called with.

For documentation of the procedures getenv and system See section `System Interface' in SLIB.

Function: vms-debug
If SCM is compiled under VMS this vms-debug will invoke the VMS debugger.

Editing Scheme Code

Function: ed arg1 ...
The value of the environment variable EDITOR (or just ed if it isn't defined) is invoked as a command with arguments arg1 ....

Function: ed filename
If SCM is compiled under VMS ed will invoke the editor with a single the single argument filename.

Gnu Emacs:
Editing of Scheme code is supported by emacs. Buffers holding files ending in .scm are automatically put into scheme-mode. EMACS for MS-DOS and MS-Windows systems is available (free) from: http://simtel.coast.net/SimTel/gnu/demacs.html If your Emacs can run a process in a buffer you can use the Emacs command `M-x run-scheme' with SCM. Otherwise, use the emacs command `M-x suspend-emacs'; or see "other systems" below.
Epsilon (MS-DOS):
There is lisp (and scheme) mode available by use of the package `LISP.E'. It offers several different indentation formats. With this package, buffers holding files ending in `.L', `.LSP', `.S', and `.SCM' (my modification) are automatically put into lisp-mode. It is possible to run a process in a buffer under Epsilon. With Epsilon 5.0 the command line options `-e512 -m0' are neccessary to manage RAM properly. It has been reported that when compiling SCM with Turbo C, you need to `#define NOSETBUF' for proper operation in a process buffer with Epsilon 5.0. One can also call out to an editor from SCM if RAM is at a premium; See "under other systems" below.
other systems:
Define the environment variable `EDITOR' to be the name of the editing program you use. The SCM procedure (ed arg1 ...) will invoke your editor and return to SCM when you exit the editor. The following definition is convenient:
(define (e) (ed "work.scm") (load "work.scm"))
Typing `(e)' will invoke the editor with the file of interest. After editing, the modified file will be loaded.

Debugging Scheme Code

The cautious and stack-limit options of build (see section Build Options) support debugging in Scheme.

CAUTIOUS
If SCM is built with the `CAUTIOUS' flag, then when an error occurs, a stack trace of certain pending calls are printed as part of the default error response. A (memoized) expression and newline are printed for each partially evaluated combination whose procedure is not builtin. See section Memoized Expressions for how to read memoized expressions. Also as the result of the `CAUTIOUS' flag, both error and user-interrupt (invoked by C-c) to print stack traces and conclude by calling breakpoint (see section `Breakpoints' in SLIB) instead of aborting to top level. Under either condition, program execution can be resumed by (continue). In this configuration one can interrupt a running Scheme program with C-c, inspect or modify top-level values, trace or untrace procedures, and continue execution with (continue).
STACK_LIMIT
If SCM is built with the `STACK_LIMIT' flag, the interpreter will check stack size periodically. If the size of stack exceeds a certain amount (default is HEAP_SEG_SIZE/2), SCM generates a segment violation interrupt. The usefulness of `STACK_LIMIT' depends on the user. I don't use it; but the user I added this feature for got primarily this type of error.

There are several SLIB macros which so useful that SCM automatically loads the appropriate module from SLIB if they are invoked.

Macro: trace proc1 ...
Traces the top-level named procedures given as arguments.
Macro: trace
With no arguments, makes sure that all the currently traced identifiers are traced (even if those identifiers have been redefined) and returns a list of the traced identifiers.

Macro: untrace proc1 ...
Turns tracing off for its arguments.
Macro: untrace
With no arguments, untraces all currently traced identifiers and returns a list of these formerly traced identifiers.

The routines I use most frequently for debugging are:

Procedure: print arg1 ...
Print writes all its arguments, separated by spaces. Print outputs a newline at the end and returns the value of the last argument.

One can just insert `(print '<proc-name>' and `)' around an expression in order to see its value as a program operates.

Syntax: print-args name1 ...
Writes name1 ... (separated by spaces) and then writes the values of the closest lexical bindings enclosing the call to Print-args.

(define (foo a b) (print-args foo) (+ a b))
(foo 3 6)
-| In foo: a = 3; b = 6; 
=> 9

Sometimes more elaborate measures are needed to print values in a useful manner. When the values to be printed may have very large (or infinite) external representations, section `Quick Print' in SLIB, can be used.

When trace is not sufficient to find program flow problems, SLIB-PSD, the Portable Scheme Debugger offers source code debugging from GNU Emacs. PSD runs slowly, so start by instrumenting only a few functions at a time.

swissnet.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz
ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz
ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz

Errors

A computer-language implementation designer faces choices of how reflexive to make the implementation in handling exceptions and errors; that is, how much of the error and exception routines should be written in the language itself. The design of a portable implementation is further constrained by the need to have (almost) all errors print meaningful messages, even when the implementation itself is not functioning correctly. Therefore, SCM implements much of its error response code in C.

The following common error and conditions are handled by C code. Those with callback names after them can also be handled by Scheme code (see section Interrupts). If the callback identifier is not defined at top level, the default error handler (C code) is invoked. There are many other error messages which are not treated specially.

  1. Wrong type in arg 0
  2. Wrong type in arg 1
  3. Wrong type in arg 2
  4. Wrong type in arg 3
  5. Wrong type in arg 4
  6. Wrong type in arg 5
  7. Wrong number of args
  8. numerical overflow
  9. Argument out of range
  10. Could not allocate (out-of-storage)
  11. EXIT (end-of-program)
  12. hang up (hang-up)
  13. user interrupt (user-interrupt)
  14. arithmetic error (arithmetic-error)
  15. bus error
  16. segment violation
  17. alarm (alarm-interrupt)
  18. virtual-alarm (virtual-alarm-interrupt)
  19. profile-alarm (profile-alarm-interrupt)

Variable: errobj
When SCM encounters a non-fatal error, it aborts evaluation of the current form, prints a message explaining the error, and resumes the top level read-eval-print loop. The value of errobj is the offending object if appropriate. The builtin procedure error does not set errobj.

errno and perror report ANSI C errors encountered during a call to a system or library function.

Function: errno
Function: errno n
With no argument returns the current value of the system variable errno. When given an argument, errno sets the system variable errno to n and returns the previous value of errno. (errno 0) will clear outstanding errors. This is recommended after try-load returns #f since this occurs when the file could not be opened.

Function: perror string
Prints on standard error output the argument string, a colon, followed by a space, the error message corresponding to the current value of errno and a newline. The value returned is unspecified.

warn and error provide a uniform way for Scheme code to signal warnings and errors.

Function: warn arg1 arg2 arg3 ...
Alias for section `System' in SLIB. Outputs an error message containing the arguments. warn is defined in `Init5c4.scm'.

Function: error arg1 arg2 arg3 ...
Alias for section `System' in SLIB. Outputs an error message containing the arguments, aborts evaluation of the current form and resumes the top level read-eval-print loop. Error is defined in `Init5c4.scm'.

If SCM is built with the `CAUTIOUS' flag, then when an error occurs, a stack trace of certain pending calls are printed as part of the default error response. A (memoized) expression and newline are printed for each partially evaluated combination whose procedure is not builtin. See section Memoized Expressions for how to read memoized expressions.

Also as the result of the `CAUTIOUS' flag, both error and user-interrupt (invoked by C-c) are defined to print stack traces and conclude by calling breakpoint (see section `Breakpoints' in SLIB). This allows the user to interract with SCM as with Lisp systems.

Function: stack-trace
Prints information describing the stack of partially evaluated expressions. stack-trace returns #t if any lines were printed and #f otherwise. See `Init5c4.scm' for an example of the use of stack-trace.

Memoized Expressions

SCM memoizes the address of each occurence of an identifier's value when first encountering it in a source expression. Subsequent executions of that memoized expression is faster because the memoized reference encodes where in the top-level or local environment its value is.

When procedures are displayed, the memoized locations appear in a format different from references which have not yet been executed. I find this a convenient aid to locating bugs and untested expressions.

For instance, open-input-file is defined as follows in `Init5c4.scm':

(define (open-input-file str)
  (or (open-file str OPEN_READ)
      (and (procedure? could-not-open) (could-not-open) #f)
      (error "OPEN-INPUT-FILE couldn't open file " str)))

If open-input-file has not yet been used, the displayed procedure is similar to the original definition (lines wrapped for readability):

open-input-file =>
#<CLOSURE (str) (or (open-file str open_read)
 (and (procedure? could-not-open) (could-not-open) #f)
 (error "OPEN-INPUT-FILE couldn't open file " str))>

If we open a file using open-input-file, the sections of code used become memoized:

(open-input-file "r4rstest.scm") => #<input-port 3>
open-input-file =>
#<CLOSURE (str) (#@or (#@open-file #@0+0 #@open_read)
 (and (procedure? could-not-open) (could-not-open) #f)
 (error "OPEN-INPUT-FILE couldn't open file " str))>

If we cause open-input-file to execute other sections of code, they too become memoized:

(open-input-file "foo.scm") =>

ERROR: No such file or directory
ERROR: OPEN-INPUT-FILE couldn't open file  "foo.scm"

open-input-file =>
#<CLOSURE (str) (#@or (#@open-file #@0+0 #@open_read)
 (#@and (#@procedure? #@could-not-open) (could-not-open) #f)
 (#@error "OPEN-INPUT-FILE couldn't open file " #@0+0))>

Internal State

Variable: *interactive*
The variable *interactive* determines whether the SCM session is interactive, or should quit after the command line is processed. *interactive* is controlled directly by the command-line options `-b', `-i', and `-s' (see section Invoking SCM). If none of these options are specified, the rules to determine interactivity are more complicated; see `Init5c4.scm' for details.

Function: abort
Resumes the top level Read-Eval-Print loop.

Function: restart
Restarts the SCM program with the same arguments as it was originally invoked. All `-l' loaded files are loaded again; If those files have changed, those changes will be reflected in the new session.

Note: When running a saved executable (see section Dump), restart is redefined to be exec-self.

Function: exec-self
Exits and immediately re-invokes the same executable with the same arguments. If the executable file has been changed or replaced since the beginning of the current session, the new executable will be invoked. This differentiates exec-self from restart.

Function: verbose n
Controls how much monitoring information is printed. If n is:

0
no prompt or information is printed.
>= 1
a prompt is printed.
>= 2
the CPU time is printed after each top level form evaluated.
>= 3
messages about heap growth are printed.
>= 4
garbage collection (see section Garbage Collection) messages are printed.
>= 5
a warning will be printed for each top-level symbol which is defined more than one time.

Function: gc
Scans all of SCM objects and reclaims for further use those that are no longer accessible.

Function: room
Function: room #t
Prints out statistics about SCM's current use of storage. (room #t) also gives the hexadecimal heap segment and stack bounds.

Constant: *scm-version*
Contains the version string (e.g. `5c4') of SCM.

Executable path

In order to dump a saved executable or to dynamically-link using DLD, SCM must know where its executable file is. Sometimes SCM (see section Executable Pathname) guesses incorrectly the location of the currently running executable. In that case, the correct path can be set by calling execpath with the pathname.

Function: execpath
Returns the path (string) which SCM uses to find the executable file whose invocation the currently running session is, or #f if the path is not set.

Function: execpath #f
Function: execpath newpath
Sets the path to #f or newpath, respectively. The old path is returned.

For other configuration constants and procedures See section `Configuration' in SLIB.

Shell Scripts

Unix Shell Scripts

In reading this section, keep in mind that the first line of a script file has (different) meanings to SCM and the operating system (execve).

file: #! interpreter
file: #! interpreter arg

On unix systems, a Shell-Script is a file (with execute permissions) whose first two characters are `#!'. The interpreter argument must be the pathname of the program to process the rest of the file. The directories named by environment variable PATH are not searched to find interpreter. The arg is an optional argument encapsulating the rest of the first line's contents, if not just whitespace.

When executing a shell-script, the operating system invokes interpreter with (if present) arg, the pathname of the shell script file, and then any arguments which the shell-script was invoked with.

Read syntax: #! ignored
When the first two characters of the file being loaded are #!, the first line of that file will be ignored.

This combination of interpretatons allows SCM source files to be used as POSIX shell-scripts if the first line is:

#!/usr/local/bin/scm

or

#!/usr/local/bin/scm -l

When such a file is invoked, /usr/local/bin/scm is executed with the name of this file as the first argument.

#!/usr/local/bin/scm
(print (program-arguments))
(quit)
=> ("scm" "./script")
#!/usr/local/bin/scm -l
(print (program-arguments))
=> ("scm" "-l" "./script")

The following shell-script will print factorial of its argument:

#!/usr/local/bin/scm -l
(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
(print (fact (string->number (cadddr (program-arguments)))))
./fact 6
=> 720 

Shell-scripts suffer from several drawbacks:

The following approach solves these problems at the expense of slower startup. Make `#!/bin/sh' the first line and prepend every subsequent line to be executed by the shell with :; (type; in older versions). The last line to be executed by the shell should contain an exec command; exec tail-calls its argument.

/bin/sh is thus invoked with the name of the script file, which it executes as a *sh script. Usually the second line starts `:;exec scm -f$0', which executes scm, which in turn loads the script file. When SCM loads the script file, it ignores the first and second lines, and evaluates the rest of the file as Scheme source code.

The second line of the script file does not have the length restriction mentioned above. Also, /bin/sh searches the directories listed in the `PATH' environment variable for `scm', eliminating the need to use absolute locations in order to invoke a program.

#!/bin/sh
:;exec scm -l$0 $*
(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
(print (fact (string->number (caddr (program-arguments)))))
./fact 6
=> 720 

SCSH scripts

Olin Shivers' Scheme Shell project solves the one-argument limitation by introducing `\' as a meta-argument. This extensions is also supported by SCM.

file: #! interpreter \

This is an enhancement to the shell-script format. When the optional arg is `\', the interpreter substitutes the second line of file for `\', then appends any arguments given on the command line invoking this shell-script.

Read syntax: #! ignored !#
When the first two characters of the file being loaded are #! and a `\' is present before a newline in the file, all characters up to `!#' will be ignored by SCM read.

This combination of interpretatons allows SCM source files to be used as POSIX shell-scripts if the first line is:

#!/usr/local/bin/scm \

The following shell-script will print its expanded argument list, then factorial of its argument:

#!/usr/local/bin/scm \
  -p0 -l !#
(print (program-arguments))
(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
(print (fact (string->number (list-ref (program-arguments) *optind*))))
./fact 5
=> ("scm" "-p0" "-l" "./fact" "5") 
120 

MS-DOS Compatible Scripts

It turns out that we can create shell-scripts which run both under unix and MS-DOS. To implement this, I have written the MS-DOS programs: #!.bat and !#.exe.

With these two programs installed in a PATH directory, we have the following syntax for <program>.BAT files.

file: #! interpreter \ %0 %1 %2 %3 %4 %5 %6 %7 %8

The first two characters of the shell-script are `#!'. The interpreter can be either a unix style program path (using `/' between filename components) or a DOS program name or path. The rest of the first line of the shell-script should be literally `\ %0 %1 %2 %3 %4 %5 %6 %7 %8', as shown.

If interpreter has `/' in it, interpreter is converted to a DOS style filename (`/' => `\').

In looking for an executable named interpreter, #! first checks this (converted) filename; if interpreter doesn't exist, it then tries to find a program named like the string starting after the last `\' (or `/') in interpreter. When searching for executables, #! tries all directories named by environment variable PATH.

Once the interpreter executable path is found, arguments are processed in the manner of scheme-shell, with the all the text after the `\' taken as part of the meta-argument. More precisely, #! calls interpreter with any options on the second line of the shell-script up to `!#', the name of the shell-script file, and then any of at most 8 arguments given on the command line invoking this shell-script.

The following shell-script will print its expanded argument list, then factorial of its argument. This shell-script in both MS-DOS and unix systems.

#! /usr/local/bin/scm \ %0 %1 %2 %3 %4 %5 %6 %7 %8
 -p1 -l !#
(print (program-arguments))
(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
(print (fact (string->number (list-ref (program-arguments) *optind*))))


Go to the first, previous, next, last section, table of contents.