2. Universal SLIB Procedures

The procedures described in these sections are supported by all implementations as part of the `*.init' files or by `require.scm'.

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

These procedures are provided by all implementations.

Function: make-vicinity dirpath

Returns dirpath as a vicinity for use as first argument to in-vicinity.

Function: pathname->vicinity path

Returns the vicinity containing path.

(pathname->vicinity "/usr/local/lib/scm/Link.scm") => "/usr/local/lib/scm/"

Function: program-vicinity

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. Warning: program-vicinity can return incorrect values if your program escapes back into a load.

Function: library-vicinity

Returns the vicinity of the shared Scheme library.

Function: implementation-vicinity

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

Function: user-vicinity

Returns the vicinity of the current directory of the user. On most systems this is `""' (the empty string).

Function: home-vicinity

Returns the vicinity of the user's HOME directory, the directory which typically contains files which customize a computer environment for a user. If scheme is running without a user (eg. a daemon) or if this concept is meaningless for the platform, then home-vicinity returns #f.

Function: vicinity:suffix? chr

Returns the `#t' if chr is a vicinity suffix character; and #f otherwise. Typical vicinity suffixes are `/', `:', and `\',

Function: in-vicinity vicinity filename

Returns a filename suitable for use by slib:load, slib:load-source, slib:load-compiled, open-input-file, open-output-file, etc. The returned filename is filename in vicinity. in-vicinity should allow filename to override vicinity when filename is an absolute pathname and vicinity is equal to the value of (user-vicinity). The behavior of in-vicinity when filename is absolute and vicinity is not equal to the value of (user-vicinity) is unspecified. For most systems in-vicinity can be string-append.

Function: sub-vicinity vicinity name

Returns the vicinity of vicinity restricted to name. This is used for large systems where names of files in subsystems could conflict. On systems with directory structure sub-vicinity will return a pathname of the subdirectory name of vicinity.

2.2 Configuration

These constants and procedures describe characteristics of the Scheme and underlying operating system. They are provided by all implementations.

Constant: char-code-limit

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

Constant: most-positive-fixnum

In implementations which support integers of practically unlimited size, most-positive-fixnum is a large exact integer within the range of exact integers that may result from computing the length of a list, vector, or string.

In implementations which do not support integers of practically unlimited size, most-positive-fixnum is the largest exact integer that may result from computing the length of a list, vector, or string.

Constant: slib:tab

The tab character.

Constant: slib:form-feed

The form-feed character.

Function: software-type

Returns a symbol denoting the generic operating system type. For instance, unix, vms, macos, amiga, or ms-dos.

Function: slib:report-version

Displays the versions of SLIB and the underlying Scheme implementation and the name of the operating system. An unspecified value is returned.

(slib:report-version) => slib "3a1" on scm "5b1" on unix

Function: slib:report

Displays the information of (slib:report-version) followed by almost all the information neccessary for submitting a problem report. An unspecified value is returned.

Function: slib:report #t

provides a more verbose listing.

Function: slib:report filename

Writes the report to file `filename'.

(slib:report) => slib "3a1" on scm "5b1" on unix (implementation-vicinity) is "/usr/local/lib/scm/" (library-vicinity) is "/usr/local/lib/slib/" (scheme-file-suffix) is ".scm" loaded *features* : trace alist qp sort common-list-functions macro values getopt compiled implementation *features* : bignum complex real rational inexact vicinity ed getenv tmpnam abort transcript with-file ieee-p1178 r4rs rev4-optional-procedures hash object-hash delay eval dynamic-wind multiarg-apply multiarg/and- logical defmacro string-port source current-time record rev3-procedures rev2-procedures sun-dl string-case array dump char-ready? full-continuation system implementation *catalog* : (i/o-extensions compiled "/usr/local/lib/scm/ioext.so") ...

2.3 Input/Output

These procedures are provided by all implementations.

Function: file-exists? filename

Returns #t if the specified file exists. Otherwise, returns #f. If the underlying implementation does not support this feature then #f is always returned.

Function: delete-file filename

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

Function: open-file filename modes

filename should be a string naming a file. open-file returns a port depending on the symbol modes:

r

an input port capable of delivering characters from the file.

rb

a binary input port capable of delivering characters from the file.

w

an output port capable of writing characters to a new file by that name.

wb

a binary output port capable of writing characters to a new file by that name.

If an implementation does not distinguish between binary and non-binary files, then it must treat rb as r and wb as w.

If the file cannot be opened, either #f is returned or an error is signalled. For output, if a file with the given name already exists, the effect is unspecified.

Function: port? obj

Returns #t if obj is an input or output port, otherwise returns #f.

Procedure: close-port port

Closes the file associated with port, rendering the port incapable of delivering or accepting characters.

close-file has no effect if the file has already been closed. The value returned is unspecified.

Function: call-with-open-ports proc ports ...

Function: call-with-open-ports ports ... proc

Proc should be a procedure that accepts as many arguments as there are ports passed to call-with-open-ports. call-with-open-ports calls proc with ports .... If proc returns, then the ports are closed automatically and the value yielded by the proc is returned. If proc does not return, then the ports will not be closed automatically unless it is possible to prove that the ports will never again be used for a read or write operation.

Function: tmpnam

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

Function: current-error-port

Returns the current port to which diagnostic and error output is directed.

Procedure: force-output

Procedure: force-output port

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

Function: output-port-width

Function: output-port-width port

Returns the width of port, which defaults to (current-output-port) if absent. If the width cannot be determined 79 is returned.

Function: output-port-height

Function: output-port-height port

Returns the height of port, which defaults to (current-output-port) if absent. If the height cannot be determined 24 is returned.

2.4 System

These procedures are provided by all implementations.

Procedure: slib:load-source name

Loads a file of Scheme source code from name with the default filename extension used in SLIB. For instance if the filename extension used in SLIB is `.scm' then (slib:load-source "foo") will load from file `foo.scm'.

Procedure: slib:load-compiled name

On implementations which support separtely loadable compiled modules, loads a file of compiled code from name with the implementation's filename extension for compiled code appended.

Procedure: slib:load name

Loads a file of Scheme source or compiled code from name with the appropriate suffixes appended. If both source and compiled code are present with the appropriate names then the implementation will load just one. It is up to the implementation to choose which one will be loaded.

If an implementation does not support compiled code then slib:load will be identical to slib:load-source.

Procedure: slib:eval obj

eval returns the value of obj evaluated in the current top level environment. 7.4.11 Eval provides a more general evaluation facility.

Procedure: slib:eval-load filename eval

filename should be a string. If filename names an existing file, the Scheme source code expressions and definitions are read from the file and eval called with them sequentially. The slib:eval-load procedure does not affect the values returned by current-input-port and current-output-port.

Procedure: slib:warn arg1 arg2 ...

Outputs a warning message containing the arguments.

Procedure: slib:error arg1 arg2 ...

Outputs an error message containing the arguments, aborts evaluation of the current form and responds in a system dependent way to the error. Typical responses are to abort the program or to enter a read-eval-print loop.

Procedure: slib:exit n

Procedure: slib:exit

Exits from the Scheme session returning status n to the system. If n is omitted or #t, a success status is returned to the system (if possible). If n is #f a failure is returned to the system (if possible). If n is an integer, then n is returned to the system (if possible). If the Scheme session cannot exit an unspecified value is returned from slib:exit.

Function: browse-url url

Web browsers have become so ubiquitous that programming languagues should support a uniform interface to them.

If a `netscape' browser is running, browse-url causes the browser to display the page specified by string url and returns #t.

If the browser is not running, browse-url starts a browser displaying the argument url. If the browser starts as a background job, browse-url returns #t immediately; if the browser starts as a foreground job, then browse-url returns #t when the browser exits; otherwise it returns #f.

2.5 Miscellany

These procedures are provided by all implementations.

Function: identity x

identity returns its argument.

Example:

(identity 3) => 3 (identity '(foo bar)) => (foo bar) (map identity lst) == (copy-list lst)

2.5.1 Mutual Exclusion

An exchanger is a procedure of one argument regulating mutually exclusive access to a resource. When a exchanger is called, its current content is returned, while being replaced by its argument in an atomic operation.

Function: make-exchanger obj

Returns a new exchanger with the argument obj as its initial content.

(define queue (make-exchanger (list a)))

A queue implemented as an exchanger holding a list can be protected from reentrant execution thus:

(define (pop queue) (let ((lst #f)) (dynamic-wind (lambda () (set! lst (queue #f))) (lambda () (and lst (not (null? lst)) (let ((ret (car lst))) (set! lst (cdr lst)) ret))) (lambda () (and lst (queue lst)))))) (pop queue) => a (pop queue) => #f

2.5.2 Legacy

The following procedures were present in Scheme until R4RS (see section `Language changes' in Revised(4) Scheme). They are provided by all SLIB implementations.

Constant: t

Derfined as #t.

Constant: nil

Defined as #f.

Function: last-pair l

Returns the last pair in the list l. Example:

(last-pair (cons 1 2)) => (1 . 2) (last-pair '(1 2)) => (2) == (cons 2 '())