"MANUAL", manual for scm4e1.
   Copyright (C) 1990, 1991, 1992, 1993, 1994 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
	(- z1 z2 ...) and (/ z1 z2 ...) 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
	char-ready?
	transcript-on, transcript-off

	     OPTIONAL Revised^4 FEATURES NOT SUPPORTED BY SCM

	numerator
	denominator
	rationalize
	Macros

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

			     ENHANCEMENTS

Options, file loading and features can be specified from the command
line.  See the man page (scm.1 or scm.doc) for a description of
initialization and command line processing.

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.  If <n> is
ommited or #t, an EXIT_SUCCESS is returned to the system.  If <n> is
any other non-integer value EXIT_FAILURE is returned to the system.

  (restart)						procedure

Restarts SCM as though it had just been invoked.  The arguments are
the same as the original invocation.

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

  (ticks <n>)						procedure

Returns the number of ticks remaining till the next tick interrupt.
Ticks are an arbitrary unit of evaluation.  Ticks can vary greatly in
the amount of time they represent.

If <n> is 0, any ticks request is canceled.  Otherwise an
TICKS-INTERRUPT will be signaled <n> from the current time.  TICKS is
supported if SCM is compiled with the TICKS flag defined.

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

Establishes a response for tick interrupts.  Another tick interrupt
will not occur unless TICKS is called again.  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.

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

  (errno)						procedure
  (errno <n>)						procedure

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.

  (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 prompt or information is printed.
  If <n> is 1 or more a prompt is printed.
  If <n> is 2 or more the CPU time is printed after each top level
		      form evaluated.
  If <n> is 3 or more messages about heap growth are printed.
  If <n> is 4 or more garbage collection (see gc) messages are
		      printed. 
  If <n> is 5 or more a warning will be printed for each top-level
		      symbol which is defined more than one time.

  (gc)							procedure

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

  (room)						procedure
  (room #t)						procedure

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

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

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

Transfers control to <command> called with the arguments.  This
procedure does not return.

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

  *scm-version*						constant

Contains the version string (e.g. "4e1") of SCM.

  (acons obj1 obj2 obj3)				procedure

Returns (cons (cons obj1 obj2) obj3).  The expression (set! a-list
(acons key datum a-list)) adds a new association to a-list.

  (copy-tree obj)					procedure

If obj is not PAIR?, it is returned; otherwise COPY-TREE returns
(CONS (COPY-TREE (CAR OBJ)) (COPY-TREE (CDR OBJ))).

  (eval obj)						procedure

Returns the value of obj evaluated in the current top level
environment.

  (dynamic-wind <thunk1> <thunk2> <thunk3>)		procedure

The arguments <thunk1>, <thunk2>, and <thunk3> must all be procedures
of no arguments (thunks).

DYNAMIC-WIND calls <thunk1>, <thunk2>, and then <thunk3>.  The value
returned by <thunk2> is returned as the result of DYNAMIC-WIND.
<thunk3> is also called just before <thunk2> calls any continuations
created by CALL-WITH-CURRENT-CONTINUATION.  If <thunk2> captures its
continuation as an escape procedure, <thunk1> is invoked just before
continuing that continuation.

  char-code-limit					constant

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

			COMPILING AND LINKING

  (compile-file <name1> <name2> ...)			procedure

If the HOBBIT compiler is installed in the (IMPLEMENTATION-VICINITY),
compiles the files <name1> <name2> ... to an object file name
<name1><object-suffix>, where <object-suffix> is the object file
suffix for your computer (for instance, ".o").  <name1> must be in the
current directory.  <name2> ... can be in other directories.

  (link-named-scm <name> <module1> ...)			procedure

Creates a new SCM executable with name <name>.  <name> will include
the object modules <module1> ... which can be produced with
compile-file.

  (load	<filename> <lib1> ...)				procedure

In addition to the R4RS requirement of loading Scheme expressions if
<filename> is a Scheme source file, LOAD will also dynamically
load/link object files (produced by COMPILE-FILE, for instance).  The
object-suffix need not be given to load.  For example,

    (load (in-vicinity (implementation-vicinity) "sc2"))
    (load (in-vicinity (implementation-vicinity) "sc2.o"))

will both load/link "sc2.o" if it exists.

The <lib1> ... pathnames are for additional libraries which may be
needed for object files not produced by the Hobbit compiler.  For
instance, crs is linked on Linux by

(load (in-vicinity (implementation-vicinity) "crs.o")
      "/usr/lib/libncurses.a" "/usr/lib/libc.a")

Turtlegr graphics library is linked by:

(load (in-vicinity (implementation-vicinity) "turtlegr")
      "/usr/lib/libX11.a" "/usr/lib/libc.a" "/usr/lib/libm.a")

And the string regular expression package is linked by:

(load (in-vicinity (implementation-vicinity) "rgx") "/usr/lib/libc.a")

			       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.

  (sinh x)						procedure
  (cosh x)						procedure
  (tanh x)						procedure

Return the hyperbolic sine, cosine, and tangent of real number x.

  ($sqrt x)						procedure
  ($abs x)						procedure
  ($exp x)						procedure
  ($log x)						procedure
  ($sin x)						procedure
  ($cos x)						procedure
  ($tan x)						procedure
  ($asin x)						procedure
  ($acos x)						procedure
  ($atan x)						procedure
  ($sinh x)						procedure
  ($cosh x)						procedure
  ($tanh x)						procedure
  ($asinh x)						procedure
  ($acosh x)						procedure
  ($atanh x)						procedure

Real only versions of these popular functions.

  ($atan2 y x)						procedure

Computes (angle (make-rectangular x y)).

  ($expt x1 x2)						procedure

Returns real number x1 raised to the real power x2.

  (integer-expt z n)					procedure

Returns z raised to the integer power n.

				 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-decode-time)					procedure

Returns a vector of integers for the local time.  The elements of the
returned vector are as follows:

  0  seconds,
  1  minutes,
  2  hours since midnight,
  3  day of month,
  4  month,
  5  year,
  6  day of week,
  7  day of year,
  8  nonzero implies daylight savings

  (get-universal-time)					procedure

The number of seconds since a reference time is returned.  This
reference time is 00:00:00 Jan 1, 1970 GMT on most systems.

  (decode-universal-time time)				procedure

Converts time to a vector of integers.  The elements of the returned
vector are as follows:

  0  seconds,
  1  minutes,
  2  hours since midnight,
  3  day of month,
  4  month,
  5  year,
  6  day of week,
  7  day of year,
  8  nonzero implies daylight savings

				ARRAYS

When constructing an array, BOUND is either an inclusive range of
indices expressed as a two element list, or an upper bound expressed
as a single integer.  So
    (make-array 'foo 3 3) and
    (make-array 'foo '(0 2) '(0 2)) are equivalent

  (array? obj)						procedure
  (array? obj prototype)				procedure

Returns a boolean indicating whether obj is an array
(corresponding to the prototype if given).

Returns `#t' if the OBJ is an array, and `#f' if not.

  (make-array INITIAL-VALUE BOUND1 BOUND2 ...)		procedure

Creates and returns an array that has as many dimensions as there are
BOUNDs and fills it with INITIAL-VALUE.

  (make-uniform-array PROTOTYPE BOUND1 BOUND2 ...)	procedure

Creates and returns a uniform array of uniform type corresponding to
PROTOTYPE that has as many dimensions as there are BOUNDs and fills it
with PROTOTYPE.

  (array-ref ARRAY INDEX1 INDEX2 ...)			procedure

Returns the element at the `(INDEX1, INDEX2)' element in ARRAY.

  (array-in-bounds? ARRAY INDEX1 INDEX2 ...)		procedure

Returns #t if its arguments would be acceptable to array-ref.

  (array-set! ARRAY NEW-VALUE INDEX1 INDEX2 ...)	procedure

Sets the element at the `(INDEX1, INDEX2)' element in ARRAY to
NEW-VALUE.  The value returned by array-set! is unspecified.

  (make-shared-array ARRAY MAPPER BOUND1 BOUND2 ...)	procedure

`make-shared-array' can be used to create shared subarrays of other
arrays.  The MAPPER is a function that translates coordinates in the
new array into coordinates in the old array.  A MAPPER must be linear,
and its range must stay within the bounds of the old array, but it can
be otherwise arbitrary.  A simple example:
    (define fred (make-array #f 8 8))
    (define freds-diagonal
      (make-shared-array fred (lambda (i) (list i i)) 8))
    (array-set! freds-diagonal 'foo 3)
    (array-ref fred 3 3) => FOO
    (define freds-center
      (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
    (array-ref freds-center 0 0) => FOO

  (array-shape ARRAY)					procedure

Returns a list of inclusive bounds of integers.
    (array-shape (make-array 'foo '(-1 3) 5)) => ((-1 3) (0 4))

  (array-dimensions ARRAY)				procedure

Array-dimensions is similar to array-shape but replaces elements with
a 0 minimum with one greater than the maximum. So:
    (array-dimensions (make-array 'foo '(-1 3) 5)) => ((-1 3) 5)

  (array-rank obj)					procedure

Returns the number of dimensions of obj.  If obj is not an array, 0 is
returned.

  (array-prototype ARRAY)				procedure

Returns an object that would produce an array of the same type as ARRAY,
if used as the PROTOTYPE for make-uniform-array.

  (array->list array)					procedure

Returns a list consisting of all the elements, in order, of array.

  (list->uniform-array rank prot lst)			procedure
  (list->uniform-vector prot lst)			procedure

Returns a uniform array of the type indicated by prototype with
elements the same as those of lst.  Elements must be of the
appropriate type, no coercions are done.

  (array-copy! SOURCE DESTINATION)			procedure

Copies every element from vector or array SOURCE to the corresponding
element of DESTINATION.  DESTINATION must have the same rank as SOURCE,
and be at least as large in each dimension.  The order is unspecified.

  (serial-array-copy! SOURCE DESTINATION)		procedure

Same as ARRAY-COPY! but guaranteed to copy in row-major order.

  (array-fill! ARRAY FILL)				procedure

Stores FILL in every element of ARRAY.  The value returned is unspecified.

  (array-equal? ARRAY0 ARRAY1 ...)			procedure

Returns #T iff all arguments are arrays with the same shape, the same
type, and have corresponding elements which are either EQUAL? or
ARRAY-EQUAL?.  This function differs from EQUAL? in that a one
dimensional shared array may be ARRAY-EQUAL? but not EQUAL? to a
vector or uniform vector.

  (array-contiguous? ARRAY)				procedure

Returns #t if ARRAY is stored internally in lexicographic order, and,
for bit-arrays, properly aligned.  This will be true of strings,
vectors, and all arrays created by make-array or make-uniform-array, but
may be false for arrays created by make-shared-array.

  (array-map! ARRAY0 PROC ARRAY1 ... )			procedure

ARRAY1, ... must have the same number of dimensions as ARRAY0 and 
have a range for each index which includes the range for the 
corresponding index in ARRAY0.  PROC is applied to each tuple of 
elements of ARRAY1 ... and the result is stored as the corresponding 
element in ARRAY0.  The value returned is unspecified.  The order of
application is unspecified.

  (serial-array-map! ARRAY0 PROC ARRAY1 ... )		procedure

Same as ARRAY-MAP!, but guaranteed to apply PROC in row-major order.

  (array-for-each PROC ARRAY0 ... )			procedure

PROC is applied to each tuple of elements of ARRAY0 ... in
row-major order.  The value returned is unspecified.

  (array-index-map! ARRAY PROC)				procedure

applies PROC to the indices of each element of ARRAY in turn, storing the
result in the corresponding element.  The value returned and the order
of application are unspecified.

You can implement ARRAY-INDEXES as

(define (array-indexes array)
    (let ((ra (apply make-array #f (array-shape array))))
      (array-index-map! ra (lambda x x))
      ra))

Another example:

(define (apl:index-generator n)
    (let ((v (make-uniform-vector n 1)))
      (array-index-map! v (lambda (i) i))
      v))

  (dimensions->uniform-array dims prot fill)		procedure
  (dimensions->uniform-array dims prot)			procedure

			    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				printing character

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

Uniform vectors are written in a form similar to that of vectors,
except that a single character from the above table is put between
`#' and '(', for example,

  '#e(3 5 9)

returns a uniform vector of signed integers.
Bit vectors will be printed as, for example,

  #*0001010

for a vector of length 7, but this may be read as

  #b(#f #f #f #t #f #t #f)

  (uniform-vector-length uve)				procedure

Returns the number of elements in uve.

  (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-read! may be used to read multidimensional uniform-arrays, 
if array-contiguous? returns #t for them.

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

uniform-vector-write may be used to write multidimensional uniform-arrays,
if array-contiguous? returns #t for them.

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

			     BIT VECTORS

Some of these operations will eventually be generalized to other
uniform-arrays.

  (bit-count bool bv)					procedure

Returns the number occurences of bool in bv.

  (bit-position bool bv k)				procedure

Returns the minimum index of an occurence of bool in bv which is at
least k.  If no bool occurs within the specified range #f is returned.

  (bit-invert! bv)					procedure

Modifies bv by replacing each element with its negation.

  (bit-set*! bv uve bool)				procedure

If uve is a bit-vector bv and uve must be of the same length.  If bool
is #t, uve is OR'ed into bv; If bool is #f, the inversion of uve is
AND'ed into bv.

If uve is a unsigned integer vector all the elements of uve must be
between 0 and the length of bv.  The bits of bv corresponding to the
indexes in uve are set to bool.

The return value is unspecified.

  (bit-count* bv uve bool)				procedure

Returns (bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t)
#t).  Bv is not modified.

			       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.

			   SYNTAX EXTENSIONS

  (read:sharp c port)				user procedure

If a "#" followed by a character (not handled by read) is encountered
by read, read will call the value of the symbol "read:sharp" with
arguments the character and the port being read from.  The value
returned by this function will be the value read for this expression
unless the function returns <unspecified> in which case the expression
will be treated as whitespace.  <unspecified> is the value returned by
the expression (if #f #f).

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

  #+feature form					read syntax

If feature is "provided" (by *features*) then form is read as a scheme
expression.  If not, then form is treated as whitespace.

Feature is a boolean expression composed of symbols and AND, OR, and
NOT of boolean expressions.

  #-feature form					read syntax

is equivalent to #+(NOT feature) expression.

  #'form						read syntax

is equivalent to form (for compatability with common-lisp).

  #|<anything>|#					read syntax

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

  #!<anything>						read syntax

On the first line of a file will be ignored when loaded by SCM.  This
makes SCM files usable as POSIX shell scripts if the first line is:

    #!/usr/local/bin/scm

When such a file is invoked it exectues /usr/local/bin/scm with the
name of this file as the first argument.  The following shell script
will print factorial of its argument:

    #!/usr/local/bin/scm
    ;;; -*-scheme-*- tells emacs this is a scheme file.
    (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
    (display (fact (string->number (caddr (program-arguments)))))
    (newline)
    (quit)

  (procedure->syntax <proc>)				procedure

Returns a "macro" which, when a symbol defined to this value appears
as the first symbol in an expression, returns the result of applying
<proc> to the expression and the environment.

  (procedure->macro <proc>)				procedure
  (procedure->memoizing-macro <proc>)			procedure

Returns a "macro" which, when a symbol defined to this value appears
as the first symbol in an expression, evaluates the result of applying
<proc> to the expression and the environment.  The value returned from
<proc> which has been passed to PROCEDURE->MEMOIZING-MACRO replaces
the form passed to <proc>.  For example:

  (define trace
    (procedure->macro
     (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

When invoked, (trace foo) will evaluate (set! foo (tracef foo 'foo)).

There are 2 types of environment frames.  The one produced by LAMBDAs,
LETs and LETRECs consists of ((varlist . vallist) . nextframe).  the
one produced by LET* (and single variable LETs) is ((var1 . val1)
(var2 .  val2) ... . nextframe).

  (@apply procedure argument-list)			syntax

Returns the result of applying procedure to argument-list.  (apply
procedure argument-list) will produce the same result.

  (@call-with-current-continutation procedure)		syntax

Returns the result of applying procedure to the current continuation.
(call-with-current-continutation procedure) will have the same effect.

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

SCM also supports the following constructs from Common Lisp: defmacro,
macroexpand, macroexpand1, macro?, gentemp, and defvar.

			    REV2_PROCEDURES

  If sc2.c is compiled and linked into SCM then the following
functions are also defined:

  (last-pair <list>)					procedure

Returns the last pair in the nonempty, possily improper, list <list>.

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

  (string-null? <string>)				procedure

Returns #t if the string <string> has length 0.

  (append! <list1> ...)					procedure

Returns a list the is the argument <list>s concatenated together.  The
arguments are modified rather than copied.

			     STRING PORTS

  (call-with-output-string <proc>)			procedure

<proc> must be a procedure of one argument.  This procedure calls
<proc> with one argument: a (newly created) output port.  When the
function returns, the string composed of the characters written into
the port is returned.

  (call-with-input-string <string> <proc>)		procedure

<proc> must be a procedure of one argument.  This procedure calls
<proc> with one argument: an (newly created) input port from which
<string>'s contents may be read.  When <proc> returns, the port is
closed and the value yielded by the procedure <proc> is returned.

			      SOFT PORTS

A soft port is a port based on a vector of procedures capable of
accepting or delivering characters.

  (make-soft-port <vector> <modes>)			procedure

Returns a port capable of receiving or delivering characters as
specified by the <modes> string (see open-file below).  <vector> must
be a vector of length 6.  Its components are as follows:

  0 procedure accepting one character for output
  1 procedure accepting a string for output
  2 thunk for flushing output
  3 thunk for getting one character
  4 thunk for closing port (not by garbage collection)

For an output-only port only elements 0, 1, 2, and 4 need be
procedures.  For an input-only port only elements 3 and 4 need be
procedures.  Thunks 2 and 4 can instead be #f if there is no useful
operation for them to perform.

If thunk 3 returns #f or `eof-object' it indicates that the port has
reached end-of-file.

			    IO_EXTENSIONS

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

Returns a port capable of receiving or delivering characters as
specified 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.

  (close-port <port>)					procedure

Closes <port>.  The same as close-input-port and close-output-port.

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

  (current-error-port)					procedure

Returns the current port to which diagnostic output is directed.

  (with-erorr-to-file <string> <thunk>)			procedure

<Thunk> must be a procedre of no arguments, and string must be a
string naming a file.  The file is opened for output, an output port
connected to it is made the default value returned by
current-error-port, and the <thunk> is called with no arguments.  When
the thunk returns, the port is closed and the previous default is
restored.  With-error-to-file returns the value yielded by <thunk>.

  (with-input-from-port <port> <thunk>)			procedure
  (with-output-to-port <port> <thunk>)			procedure
  (with-error-to-port <port> <thunk>)			procedure

These routines differ from with-input-from-file, with-output-to-file,
and with-error-to-file in that the first argument is a port, rather
than a string naming a file.

  (file-exists? <filename>)				procedure

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

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

  (isatty? <port>)					procedure

Returns #t if <port> is input or output to a serial non-file device.

  (stat <port-or-string>)				procedure

Returns a vector of integers describing the argument.  The argument
can be either a string or an open input port. If the argument is an
open port then the returned vector describes the file to which the
port is opened; If the argument is a string then the returned vector
describes the file named by that string.  If there exists no file with
the name string, or if the file cannot be accessed #f is returnd.
The elements of the returned vector are as follows:

  0  st_dev	ID of device containing a
		directory entry for this file
  1  st_ino	Inode number
  2  st_mode	File type, attributes, and
		access control summary
  3  st_nlink	Number of links
  4  st_uid	User ID of file owner
  5  st_gid	Group ID of file group
  6  st_rdev	Device ID; this entry defined
		only for char or blk spec files
  7  st_size	File size (bytes)
  8  st_atime	Time of last access
  9  st_mtime	Last modification time
  10 st_ctime	Last file status change time

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

  (read-line port)					procedure
  (read-line)						procedure

Returns a string of the characters up to, but not including a newline
or end of file, updating the port to point to the character following
the newline.  If no characters are available, an end of file object is
returned.  Port may be omitted, in which case it defaults to the value
returned by current-input-port.

  (read-line! string port)				procedure
  (read-line! string)					procedure

Fills string with characters up to, but not including a newline or end
of file, updating the port to point to the last character read or
following the newline if it was read.  If no characters are available,
an end of file object is returned.  If a newline or end of file was
found, the number of characters read is returned.  Otherwise, #f is
returned.  Port may be omitted, in which case it defaults to the value
returned by current-input-port.

  (write-line string port)				procedure
  (write-line string)					procedure

Writes string followed by a newline to the given port and returns an
unspecified value.  Port may be omitted, in which case it defaults to
the value returned by current-output-port.

		       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.

		 REGULAR EXPRESSION PATTERN MATCHING

These functions are defined in rgx.c using a POSIX C regex library.
If your computer does not support regex a package is available via ftp
from prep.ai.mit.edu:/pub/gnu/regex-0.12.tar.gz.  See the
documentation for the regex library for a description of regular
expressions.

  (regcomp <pattern>)					procedure

Given a string <pattern>, Returns an integer error code or an object
of type regexp which is suitable as an argument to regexec.

  (regerror <errno>)					procedure

Returns a string describing the integer <errno> returned by regcomp in
case <pattern> could not be compiled.

  (regmatch? <regexp> <string>)				procedure

Returns #t if the <pattern> such that <regexp> = (regcomp <pattern>)
matches <string> as a POSIX extended regular expressions.  Returns #f
otherwise.

  (regexec <regexp> <string>)				procedure

Returns #f or a vector of integers.  These integers are in doublets.
The first of each doublet is the index of <string> of the start of the
matching expression or sub-expression (delimited by parentheses in the
pattern).  The last of each doublet is index of <string> o the end of
that expression.  #f is returned if the string does not match.

				CURSES

These functions are defined in crs.c using a "curses" library.  Unless
otherwise noted these routines return #t for successful completion and
#f for failure.

  (initscr)						procedure

Returns a port for a full screen window.  This routine must be called
to initialize curses.

  (endwin)						procedure

A program should call endwin before exiting or escaping from curses
mode temporarily, to do a system call, for example.  This routine will
restore termio modes, move the cursor to the lower left corner of the
screen and reset the terminal into the proper non-visual mode.  To
resume after a temporary escape, call refresh.

	OUTPUT OPTIONS SETTING

These routines set options within curses that deal with output.  All
options are initially #F, unless otherwise stated.  It is not
necessary to turn these options off before calling endwin.

  (clearok win bf)					procedure

If enabled (bf is #T), the next call to force-output with this window
will clear the screen completely and redraw the entire screen from
scratch.  This is useful when the contents of the screen are
uncertain, or in some cases for a more pleasing visual effect.

  (idlok win bf)					procedure

If enabled (bf is #T), curses will consider using the hardware
"insert/delete-line" feature of terminals so equipped.  If disabled
(bf is #F), curses will very seldom use this feature.  The
"insert/delete-character" feature is always considered.  This option
should be enabled only if your application needs "insert/delete-line",
for example, for a screen editor.  It is disabled by default because

"insert/delete-line" tends to be visually annoying when used in
applications where it is not really needed.  If "insert/delete-line"
cannot be used, curses will redraw the changed portions of all lines.

  (leaveok win bf)					procedure

Normally, the hardware cursor is left at the location of the window
cursor being refreshed.  This option allows the cursor to be left
wherever the update happens to leave it.  It is useful for
applications where the cursor is not used, since it reduces the need
for cursor motions.  If possible, the cursor is made invisible when
this option is enabled.

  (scrollok win bf)					procedure

This option controls what happens when the cursor of a window is moved
off the edge of the window or scrolling region, either from a newline
on the bottom line, or typing the last character of the last line.  If
disabled (bf is #F), the cursor is left on the bottom line at the
location where the offending character was entered.  If enabled (bf is
#T), force-output is called on the window, and then the physical
terminal and window are scrolled up one line.  Note: in order to get
the physical scrolling effect on the terminal, it is also necessary to
call idlok.

  (nodelay win bf)					procedure

This option causes wgetch to be a non-blocking call.  If no input is
ready, wgetch will return an eof-object. If disabled, wgetch will hang
until a key is pressed.

	TERMINAL MODE SETTING

These routines set options within curses that deal with input.  The
options involve using ioctl(2) and therefore interact with curses
routines.  It is not necessary to turn these options off before
calling endwin.  The routines in this section all return an
unspecified value.

  (cbreak)						procedure
  (nocbreak)						procedure

These two routines put the terminal into and out of CBREAK mode,
respectively.  In CBREAK mode, characters typed by the user are
immediately available to the program and erase/kill character
processing is not performed.  When in NOCBREAK mode, the tty driver
will buffer characters typed until a NEWLINE or RETURN is typed.
Interrupt and flowcontrol characters are unaffected by this mode.
Initially the terminal may or may not be in CBREAK mode, as it is
inherited, therefore, a program should call cbreak or nocbreak
explicitly.  Most interactive programs using curses will set CBREAK
mode.

Note: cbreak overrides raw.  See read-char under Input for a
discussion of how these routines interact with echo and noecho.

  (raw)							procedure
  (noraw)						procedure

The terminal is placed into or out of RAW mode.  RAW mode is similar
to CBREAK mode, in that characters typed are immediately passed
through to the user program.  The differences are that in RAW mode,
the interrupt, quit, suspend, and flow control characters are passed
through uninterpreted, instead of generating a signal.  RAW mode also
causes 8-bit input and output.  The behavior of the BREAK key depends
on other bits in the terminal driver that are not set by curses.

  (echo)						procedure
  (noecho)						procedure

These routines control whether characters typed by the user are echoed
by read-char as they are typed.  Echoing by the tty driver is always
disabled, but initially read-char is in ECHO mode, so characters typed
are echoed.  Authors of most interactive programs prefer to do their
own echoing in a controlled area of the screen, or not to echo at all,
so they disable echoing by calling noecho.  See read-char under Input
for a discussion of how these routines interact with cbreak and
nocbreak.

  (nl)							procedure
  (nonl)						procedure

These routines control whether NEWLINE is translated into RETURN and
LINEFEED on output, and whether RETURN is translated into NEWLINE on
input.  Initially, the translations do occur.  By disabling these
translations using nonl, curses is able to make better use of the
linefeed capability, resulting in faster cursor motion.

  (resetty)						procedure
  (savetty)						procedure

These routines save and restore the state of the terminal modes.
savetty saves the current state of the terminal in a buffer and
resetty restores the state to what it was at the last call to savetty.

	WINDOW MANIPULATION

  (newwin nlines ncols begy begx)			procedure

Create and return a new window with the given number of lines (or
rows), nlines, and columns, ncols.  The upper left corner of the
window is at line begy, column begx.  If either nlines or ncols is 0,
they will be set to the value of LINES-begy and COLS-begx.  A new
full-screen window is created by calling newwin(0,0,0,0).

  (subwin orig nlines ncols begy begx)			procedure

Create and return a pointer to a new window with the given number of
lines (or rows), nlines, and columns, ncols.  The window is at
position ( begy, begx) on the screen.  This position is relative to
the screen, and not to the window orig.  The window is made in the
middle of the window orig, so that changes made to one window will
affect both windows.  When using this routine, often it will be
necessary to call touchwin or touchline on orig before calling
force-output.

  (close-port win)					procedure

Deletes the named window, freeing up all memory associated with it.
In the case of sub-windows, they should be deleted before the main
window.

  (refresh)						procedure
  (force-output win)					procedure

These routines are called to write output to the terminal, as most
other routines merely manipulate data structures.  force-output copies
the named window to the physical terminal screen, taking into account
what is already there in order to minimize the amount of information
that's sent to the terminal (called optimization).  Unless leaveok has
been enabled, the physical cursor of the terminal is left at the
location of the window's cursor.  With refresh, the number of
characters output to the terminal is returned.

  (mvwin win y x)					procedure

Move the window so that the upper left corner will be at position (y,
x).  If the move would cause the window to be off the screen, it is an
error and the window is not moved.

  (overlay srcwin dstwin)				procedure
  (overwrite srcwin dstwin)				procedure

These routines overlay srcwin on top of dstwin; that is, all text in
srcwin is copied into dstwin.  scrwin and dstwin need not be the same
size; only text where the two windows overlap is copied.  The
difference is that overlay is non-destructive (blanks are not copied),
while overwrite is destructive.

  (touchwin win)					procedure
  (touchline win start count)				procedure

Throw away all optimization information about which parts of the
window have been touched, by pretending that the entire window has
been drawn on.  This is sometimes necessary when using

overlapping windows, since a change to one window will affect the
other window, but the records of which lines have been changed in the
other window will not reflect the change.  touchline only pretends
that count lines have been changed, beginning with line start.

  (wmove win y x)					procedure

The cursor associated with the window is moved to line (row) y, column
x.  This does not move the physical cursor of the terminal until
refresh is called.  The position specified is relative to the upper
left corner of the window, which is (0, 0).

	OUTPUT (These routines are used to "draw" text on windows)

  (display ch win)					procedure
  (display str win)					procedure
  (wadd win ch)						procedure
  (wadd win str)					procedure

The character ch or characters in str are put into the window at the
current cursor position of the window and the position of the window
cursor is advanced.  At the right margin, an automatic newline is
performed.  At the bottom of the scrolling region, if scrollok is
enabled, the scrolling region will be scrolled up one line.

If ch is a TAB, NEWLINE, or backspace, the cursor will be moved
appropriately within the window.  A NEWLINE also does a clrtoeol
before moving.  TAB characters are considered to be at every eighth
column.  If ch is another control character, it will be drawn in the
CTRL-X notation.  (Calling winch after adding a control character will
not return the control character, but instead will return the
representation of the control character.)

Video attributes can be combined with a character by or-ing them into
the parameter.  This will result in these attributes also being set.
The intent here is that text, including attributes, can be copied from
one place to another using inch and display.  See standout, below.

Note: For wadd ch can be an integer and will insert the character of
the corresponding value.

  (werase win)						procedure

This routine copies blanks to every position in the window.

  (wclear win)						procedure

This routine is like werase, but it also calls clearok, arranging that
the screen will be cleared completely on the next call to force-output
for that window, and repainted from scratch.

  (wclrtobot win)					procedure

All lines below the cursor in this window are erased.  Also, the
current line to the right of the cursor, inclusive, is erased.

  (wclrtoeol win)					procedure

The current line to the right of the cursor, inclusive, is erased.

  (wdelch win)						procedure

The character under the cursor in the window is deleted.  All
characters to the right on the same line are moved to the left one
position and the last character on the line is filled with a blank.
The cursor position does not change.  This does not imply use of the
hardware "delete-character" feature.

  (wdeleteln win)					procedure

The line under the cursor in the window is deleted.  All lines below
the current line are moved up one line.  The bottom line of the window
is cleared.  The cursor position does not change.  This does not imply
use of the hardware "deleteline" feature.

  (winsch win ch)					procedure

The character ch is inserted before the character under the cursor.
All characters to the right are moved one SPACE to the right, possibly
losing the rightmost character of the line.  The cursor position does
not change .  This does not imply use of the hardware
"insertcharacter" feature.

  (winsertln win)					procedure

A blank line is inserted above the current line and the bottom line is
lost.  This does not imply use of the hardware "insert-line" feature.

  (scroll win)						procedure

The window is scrolled up one line.  This involves moving the lines in
the window data structure.  As an optimization, if the window is
stdscr and the scrolling region is the entire window, the physical
screen will be scrolled at the same time.

	INPUT

  (read-char win)					procedure

A character is read from the terminal associated with the window.
Depending on the setting of cbreak, this will be after one character
(CBREAK mode), or after the first newline (NOCBREAK mode).  Unless
noecho has been set, the character will also be echoed into the
designated window.

When using read-char, do not set both NOCBREAK mode (nocbreak) and
ECHO mode (echo) at the same time.  Depending on the state of the
terminal driver when each character is typed, the program may produce
undesirable results.

  (winch win)						procedure

The character, of type chtype, at the current position in the named
window is returned.  If any attributes are set for that position,
their values will be OR'ed into the value returned.

  (getyx win)						procedure

A list of the y and x coordinates of the cursor position of the window
is returned

	MISCELLANEOUS

  (wstandout win)					procedure
  (wstandend win)					procedure

These functions set the current attributes of the named window.  The
current attributes of a window are applied to all characters that are
written into the window.  Attributes are a property of the character,
and move with the character through any scrolling and insert/delete
line/character operations.  To the extent possible on the particular
terminal, they will be displayed as the graphic rendition of
characters put on the screen.

Wstandout sets the current attributes of the given window to be
visibly different from other text.  Wstandend turns off the
attributes.

  (box win vertch horch)				procedure

A box is drawn around the edge of the window, win.  vertch and horch
are the characters the box is to be drawn with.  If vertch and horch
are 0, then appropriate default characters, ACS_VLINE and ACS_HLINE,
will be used.

Note: vertch and horch can be an integers and will insert the
character (with attributes) of the corresponding values.

  (unctrl c)						procedure

This macro expands to a character string which is a printable
representation of the character c.  Control characters are displayed
in the ^X notation.  Printing characters are displayed as is.

			 SCHEME BIBLIOGRAPHY

Revised^4 Report on the Algorithmic Language Scheme can be obtained
via anonymous ftp from: altdorf.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
