RISC DISC 2

home *** CD-ROM | disk | FTP | other *** search

/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / language / scm / !Scm / docs / MANUAL < prev next >

Wrap

Text File | 1994-04-15 | 53.1 KB | 1,533 lines

"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