"MANUAL", manual for scm.
   Copyright (C) 1990, 1991, 1992, 1993 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.  The <n>
argument may be omitted in which case the default is 0.

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

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

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

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

			       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

			    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? uve)					procedure
  (uniform-vector? uve prototype)			procedure

Returns a boolean indicating whether uve is a uniform vector
(corresponding to the prototype if given).

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

			       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

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

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

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

			    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.

  (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 config.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.
See the documentation with this 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.

	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
