"MANUAL", manual for scm.
   Copyright (C) 1990, 1991, 1992 Aubrey Jaffer.
   See the file `COPYING' for terms applying to this program

Scm conforms to Revised^4 Report on the Algorithmic Language Scheme
and the IEEE P1178 specification (see BIBLIOGRAPHY at end).  All the
required features of these specifications are supported.  Some of the
optional features are supported as well.

Integers use 2 bits less than the long integer type of the host
machine.

	       OPTIONAL Revised^4 FEATURES SUPPORTED BY SCM

	(if <test> <consequent>)
	let*
	do
	(let <variable> <bindings> <body>)
	All varieties of define
	list-tail
	string-copy, string-fill!
	(make-vector k fill)
	vector-fill!
	(apply proc arg1 ... args) of more than 2 arguments
	exp, log, sin, cos, tan, asin, acos, atan, sqrt, expt
	make-rectangular, make-polar, real-part, imag-part
	magnitude, angle
	exact->inexact,	inexact->exact
	delay, force
	with-input-from-file, with-output-to-file
	transcript-on, transcript-off

	     OPTIONAL Revised^4 FEATURES NOT SUPPORTED BY SCM

	(- z1 z2 ...) and (/ z1 z2 ...) of more than 2 arguments
	numerator
	denominator
	rationalize
	char-ready?
	Macros

Scm has features not required by the IEEE and Revised^4
specifications:

			     ENHANCEMENTS

To start scm type: `scm [arg1] [arg2] ...'.  Scm is started up and the
file Init.scm in the implementation directory is loaded.  The
distribution version of Init.scm checks to see if there is file
"ScmInit.scm" in path specified by the environment variable "HOME" or
in the current directory.  If there is such a file it is loaded.
Otherwise each argument is given as an arguement to LOAD in the order
specified.  Scm will then evaluate and print all expressions typed
into it.  If arguments are given, verbose mode will initially be off;
if not, verbose mode will initially be on.  This can of course be
overridden in the init files.

Typing the end-of-file character at top level exits from scm.

Typing the interrupt character aborts evaluation of the current form
and resumes the top level read-eval-print loop. 

  (quit)						procedure
  (quit <n>)						procedure

Exits from scm returning error code <n> to the system.  The <n>
argument may be omitted in which case the default is 0.

  (error <arg1> <arg2> <arg3> ...)			procedure

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 Init.scm; change it to suit you.

  errobj						variable

If 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.  errobj is not set from calls to the
error function.

  (abort)						procedure

Resumes the top level Read-Eval-Print loop.

  (alarm <secs>)					procedure

Returns the number of seconds remaining till the next alarm interrupt.
If <secs> is 0, any alarm request is canceled.  Otherwise an
ALARM-INTERRUPT will be signaled <secs> from the current time.  ALARM
is not supported on all systems.

  (define (user-interrupt) ...)			user procedure
  (define (alarm-interrupt) ...)		user procedure

Establishes a response for SIGINT (control-C interrupt) and SIGALRM
interrupts.  Program execution will resume if the handler returns.
This procedure should (abort) or some other action which does not
return if it does not want processing to continue after it returns.

Interrupt handlers are disabled during execution SYSTEM and ED
procedures.

To unestablish a response for an interrupt set the handler symbol to
#f.  For instance, (set! user-interrupt #f).

  (define (out-of-storage) ...)			user procedure
  (define (could-not-open) ...)			user procedure
  (define (end-of-program) ...)			user procedure
  (define (hang-up) ...)			user procedure
  (define (arithmetic-error) ...)		user procedure

Establishes a response for storage allocation error, file opening
error, end of program, SIGHUP (hang up interrupt) and arithmetic
errors respectively.  This procedure should (abort) or some other
action which does not return if it does not want the default error
message to also be displayed.  If no procedure is defined for HANG-UP
then END-OF-PROGRAM (if defined) will be called.

To unestablish a response for an error set the handler symbol to
#f.  For instance, (set! could-not-open #f).

  (set-errno! <n>)					procedure

Sets the system variable `errno' to <n>.  (set-errno! 0) will clear
outstanding errors.  This is recommended after try-load returns #f
since this occurs when the file could not be opened.

  (perror <string>)					procedure

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.

  (verbose <n>)						procedure

Controls how much monitoring information is printed.  If <n> is 0 no
information is printed.  If <n> is 1 the elapsed time is printed after
each top level form evaluated.  If <n> is 2 elapsed time and messages
about heap growth are printed.  If <n> is 3 elapsed time, heap growth,
and garbage collection (see gc) messages are printed.

  (gc)							procedure

Scans all of scm objects and reclaims for further use those that are
no longer accessible.

  (terms)						procedure

This command displays the GNU General Public License.

  (list-file "<filename>")				procedure

Displays the text contents of <filename>.

  (system "<command> <arg1> ...")			procedure

Executes the <command> on the computer and returns the integer status
code.

  (ed "<filename>")					procedure
  (vms-debug)						procedure

If scm is compiled under VMS these commands will invoke the editor or
debugger respectively.

  (program-arguments)					procedure

Returns a list of strings of the arguments scm was called with.

  (getenv <name>)					procedure

Looks up <name>, a string, in the program environment.  If <name> is
found a string of its value is returned.  Otherwise, #f is returned.

  (tmpnam)						procedure

Returns a pathname for a file which will likely not be used by any
other process.  Successive calls to (tmpnam) will return different
pathnames.

  (software-type)					procedure

Returns a symbol for the type of operating system scm is running on.

  char-code-limit					constant

Is an integer 1 larger that the largest value which can be returned by
char->integer.

			     NUMERIC

  most-positive-fixnum					constant

Is the Immediate integer closest to positive infinity.

  most-negative-fixnum					constant

Is the Immediate integer closest to negative infinity.

				 TIME

  internal-time-units-per-second			constant

Is the integer number of internal time units in a second.

  (get-internal-run-time)				procedure

Returns the integer run time in internal time units from an
unspecified starting time.  The difference of two calls to
get-internal-run-time divided by interal-time-units-per-second will
give elapsed run time in seconds.

  (get-internal-real-time)				procedure

Returns the integer time in internal time units from an unspecified
starting time.  The difference of two calls to get-internal-real-time
divided by interal-time-units-per-second will give elapsed real time
in seconds.

  (get-decoded-time)					procedure

Returns a vector of integers:
	seconds,
	minutes,
	hours since midnight,
	day of month,
	month,
	year,
	day of week,
	day of year,
	and nonzero implies daylight savings
for the local time.

  (get-universal-time)					procedure

The number of seconds since 00:00:00 Jan 1, 1970 GMT is returned.
When SCM has bignums this will be the time since 1900 GMT.

  (decode-universal-time time)				procedure

Converts time to a vector of integers:
	seconds,
	minutes,
	hours since midnight,
	day of month,
	month,
	year,
	day of week,
	day of year,
	and nonzero implies daylight savings.

			    UNIFORM VECTOR

Uniform vectors are vectors whose elements are all of the same type.
For types boolean, char, integer, and inexact numbers uniform vectors
occupy less storage than conventional vectors.  Uniform-vector
functions also work on vectors.

  (make-uniform-vector length prototype)		procedure

Returns a uniform vector whose elements are as specified by the
prototype argument according to the following table:
	prototype	type

	#t		boolean (bit-vector)
	#\a		char (string)
	integer >0	unsigned integer
	integer <0	signed integer
	1.0		float (single precision)
	1/3		double (double precision float)
	+i		complex (double precision)
	()		conventional vector

  (uniform-vector-length uve)				procedure

Returns the number of elements in uve.

  (uniform-vector-ref uve k)				procedure

k must be a valid index of vector.  Uniform-vector-ref returns the
contents of element k of uniform-vector using zero-origin indexing.

  (uniform-vector-set! uve k obj)			procedure

K must be a valid index of vector.  Uniform-vector-set! stores obj in
element k of uve.  The value returned by uniform-vector-set! is
unspecified.

  (uniform-vector-fill! uve fill)			procedure

Stores fill in every element of vector.  The value returned by
uniform-vector-fill! is unspecified.

  (uniform-vector-read! uve)				procedure
  (uniform-vector-read! uve port)			procedure

Reads (uniform-vector-length uve) binary objects from port.  If an end
of file is encountered during uniform-vector-read! the objects up to
that point only are put into uve (starting at the beginning) and the
remainder of the string is unchanged.

uniform-vector-read! returns the number of objects read.  Port may
be omitted, in which case it defaults to the value returned by
current-input-port.

  (uniform-vector-write uve)				procedure
  (uniform-vector-write uve port)			procedure

Writes (uniform-vector-length uve) binary objects to port.  The number
of objects actually written is returned.

uniform-vector-write returns the number of objects writen.  Port may
be omitted, in which case it defaults to the value returned by
current-output-port.

  (vector-set-length! uve length)			procedure

Change the length of the first argument to the second.  If this
shortens the object then the remaining contents are lost.  If it
enlarges the object the the contents of the extended part are
undefined but the original part is unchanged.  It is an error to
change the length of literal datums.  The new object is returned.

			       VICINITY

A vicinity is a descriptor for a place in the file system.  Vicinities
hide from the programmer the concepts of host, volume, directory, and
version.  Vicinities express only the concept of a file environment
where a file name can be resolved to a file in a system independent
manner.  Vicinities can even be used on `flat' file systems (which
have no directory structure) by having the vicinity express
constraints on the file name.  On most systems a vicinity would be a
string.  All of these procedures are file system dependent.

NOTE: a more complete implementation of VICINITY is in the Scheme
Library.

  (program-vicinity)					procedure

Returns the vicinity of the currently loading Scheme code.  For an
interpreter this would be the directory containing source code.  For a
compiled system (with multiple files) this would be the directory
where the object or executable files are.  If no file is currently
loading it the result is undefined.

  (library-vicinity)					procedure

Returns the vicinity of the shared Scheme library.

  (implementation-vicinity)				procedure

Returns the vicinity of the underlying Scheme implementation.  This
vicinity will likely contain startup code and messages and a compiler.

  (in-vicinity <vicinity> <filename>)			procedure

Returns a filename suitable for use by load, open-input-file,
open-output-file, etc.  The returned filename is <filename> in
<vicinity>.  For most systems in-vicinity is string-append.

  (try-load <filename>)					procedure

Filename should be a string.  If filename names an existing file, the
try-load procedure reads Scheme source code expressions and
definintions from the file and evaluates them sequentially and returns
#t.  If not, try-load returns #f.  The try-load procedure does not
affect the values returned by current-input-port and current-output-port.

  *load-pathname*					variable

Is set to the pathname given as argument to load try-load.

  (line-number)						procedure

Returns the current line number of the file currently being loaded.

  *features*						variable

Is a list of symbols denoting features supported in this
implementation.

			   SYTAX_EXTENSIONS

  #.<expression>					read syntax

Is read as the object resulting from the evaluation of <expression>.
This substitution occurs even inside quoted structure.

In order to allow compiled code to work with #. it is good practice to
define those symbols used inside of <expression> with #.(define ...).
For example:

    #.(define foo 9)			==> #<unspecified>
    '(#.foo #.(+ foo foo))		==> (9 18)

  #|<anything>|#					read syntax

Is a balanced comment.  Everything up to the matching |# is ignored by
the reader.  Nested #|...|# can occur inside <anything>.

  If SYNTAX_EXTENSIONS is #defined in config.h or the makefile the
following syntax is also defined:

  (defined? <symbol>)					syntax

Equivalent to #t if <symbol> is a syntactic keyword (such as IF) or a
symbol with a top-level value.  Otherwise equivalent to #f.

			    REV2_PROCEDURES

  If REV2_PROCEDURES is #defined in config.h or the makefile the
following functions are also defined:

  (substring-move-left! <string1> <start1> <end1> <string2> <start2>)
  (substring-move-right! <string1> <start1> <end1> <string2> <start2>)
							procedure

<String1> and <string2> must be strings, and <start1>, <start2> and
<end1> must be exact integers satisfying

	0 <= start1 <= end1 <= (string-length <string1>)
	0 <= start2 <= end1-start1+start2 <= (string-length <string2>).

Substring-move-left! and substring-move-right! store characters of
<string1> beginning with index <start1> (inclusive) and ending with
index <end1> (exclusive) into <string2> beginning with index <start2>
(inclusive).

Substring-move-left! stores characters in time order of increasing
indeces.  Substring-move-right! stores characters in time order of
decreasing indeces.

  (substring-fill! <string> <start> <end> <fill>)	procedure

Substring-fill! stores character <fill> into <string> beginning with
index <start> (inclusive) and ending with index <end) (exclusive).

  (object-hash obj)					procedure

Returns an integer for obj.  (= (object-hash obj) (object-hash obj))
will always be #t.  Object-hash does not cause obj to continue to
exist if there are no more references to obj.  At most 2 different
objects map to any integer.

  (object-unhash k)					procedure

Returns an object whose (object-hash obj) is k or #f if that object no
longer exists.

			    IO_EXTENSIONS

  (open-file <string> <modes>)				procedure

Returns a port capable of receiving or delivering characters as
specifie by the <modes> string.  If a file cannot be opened #f is
returned.

  OPEN_READ						constant
  OPEN_WRITE						constant
  OPEN_BOTH						constant

Contain modes strings specifying that a file is to be opened for
reading, writing, and both reading and writing respectively.

  (open-io-file <filename>)				procedure
  (close-io-port <port>)				procedure

These functions are analogous to the standard scheme file functions.
The ports are open to <filename> in read/write mode.  Both input and
output functions can be used with io-ports.  An end of file must be
read or a file-set-position done on the port between a read operation
and a write operation or vice-versa.

  (file-exists? <filename>)				procedure

Returns #t if the specified file exists.  Otherwise, returns #f.

  If IO_EXTENSIONS is #defined in config.h or the makefile the
following functions are also defined:

  (open-pipe <string> <modes>)				procedure

If the string <modes> contains an "r" returns an input port capable of
delivering characters from the standard output of the system command
<string>.  Otherwise, returns an output port capable of receiving
characters which become the standard input of the system command
<string>.  If a pipe cannot be created #f is returned.

  (open-input-pipe <string>)				procedure

Returns an input port capable of delivering characters from the
standard output of the system command <string>.  If a pipe cannot be
created #f is returned.

  (open-output-pipe <string>)				procedure

Returns an output port capable of receiving characters which become
the standard input of the system command <string>.  If a pipe cannot
be created #f is returned.

  (close-pipe <pipe>)					procedure

Closes the <pipe>, rendering it incapable of delivering or accepting
characters.  This routine has no effect if the pipe has already been
closed.  The value returned is unspecified.

  (file-position <port>)				procedure

Returns the current position of the character in <port> which will
next be read or written.  If <port> is not open to a file the result
is unspecified.

  (file-set-position <port> <integer>)			procedure

Sets the current position in <port> which will next be read or
written.  If <port> is not open to a file the action of
file-set-position is unspecified.  The result of file-set-position is
unspecified.

  (force-output)					procedure
  (force-output <port>)					procedure

Forces any pending output on <port> to be delivered to the output
device and returns an unspecified value.  The <port> argument may be
omitted, in which case it defaults to the value returned by
CURRENT-OUTPUT-PORT.

  (chdir <filename>)					procedure

Changes the current directory to <filename>.  If <filename> does not
exist or is not a directory, #f is returned.  Otherwise, #t is
returned.

  (delete-file <filename>)				procedure

Deletes the file specified by <filename>.  If <filename> can not be
deleted, #f is returned.  Otherwise, #t is returned.

  (rename-file <oldfilename> <newfilename>)		procedure

Renames the file specified by <oldfilename> to <newfilename>.  If the
renaming is successful, #t is returned.  Otherwise, #f is returned.

		       PROCESS SYNCHRONIZATION

  (make-arbiter <name>)					procedure

Returns an oject of type arbiter and name <name>.  Its state is
initially unlocked.

  (try-arbiter <arbiter>)				procedure

Returns #t and locks <arbiter> if <arbiter> was unlocked.  Otherwise,
returns #f.

  (release-arbiter <arbiter>)				procedure

Returns #t and unlocks <arbiter> if <arbiter> was locked.  Otherwise,
returns #f.

			 SCHEME BIBLIOGRAPHY

Revised^4 Report on the Algorithmic Language Scheme can be obtained
via anonymous ftp from: altorf.ai.mit.edu:archive/scheme-reports/

IEEE Std 1178-1990,
IEEE Standard for the Scheme Programming Language,
Institute of Electrical and Electronic Engineers, Inc.,
New York, NY, 1991

Two books about Scheme are:

R. Kent Dybvig, The Scheme Programming Language,
Prentice-Hall Inc, Englewood Cliffs, New Jersey 07632, USA

H. Abelson, G. J. Sussman, and J. Sussman,
Structure and Interpretation of Computer Programs,
The MIT Press, Cambridge, Massachusetts, USA, 1985
