Go to the first, previous, next, last section, table of contents.

The Library System

Introduction

SLIB is a portable library for the programming language Scheme. It provides a platform independent framework for using packages of Scheme procedures and syntax. As distributed, SLIB contains useful packages for all implementations. Its catalog can be transparently extended to accomodate packages specific to a site, implementation, user, or directory.

Aubrey Jaffer <jaffer@ai.mit.edu>
Hyperactive Software -- The Maniac Inside!
http://swissnet.ai.mit.edu/~jaffer/SLIB.html

Feature

SLIB denotes features by symbols. SLIB maintains a list of features supported by the Scheme session. The set of features provided by a session may change over time. Some features are properties of the Scheme implementation being used. The following features detail what sort of numbers are available from an implementation.

'inexact
'rational
'real
'complex
'bignum

Other features correspond to the presence of sets of Scheme procedures or syntax (macros).

Function: provided? feature: Returns #t if feature is supported by the current Scheme session.

Procedure: provide feature: Informs SLIB that feature is supported. Henceforth (provided? feature) will return #t.

(provided? 'foo)    => #f
(provide 'foo)
(provided? 'foo)    => #t

Requesting Features

SLIB creates and maintains a catalog mapping features to locations of files introducing procedures and syntax denoted by those features.

At the beginning of each section of this manual, there is a line like (require 'feature). The Scheme files comprising SLIB are cataloged so that these feature names map to the corresponding files.

SLIB provides a form, require, which loads the files providing the requested feature.

Procedure: require feature

If (provided? feature) is true, then require just returns an unspecified value.
Otherwise, if feature is found in the catalog, then the corresponding files will be loaded and an unspecified value returned. Subsequently (provided? feature) will return #t.
Otherwise (feature not found in the catalog), an error is signaled.

The catalog can also be queried using require:feature->path.

Function: require:feature->path feature

If feature is already provided, then returns #t.
Otherwise, if feature is in the catalog, the path or list of paths associated with feature is returned.
Otherwise, returns #f.

Library Catalogs

At the start of a session no catalog is present, but is created with the first catalog inquiry (such as (require 'random)). Several sources of catalog information are combined to produce the catalog:

standard SLIB packages.
additional packages of interest to this site.
packages specifically for the variety of Scheme which this session is running.
packages this user wants to always have available. This catalog is the file `homecat' in the user's HOME directory.
packages germane to working in this (current working) directory. This catalog is the file `usercat' in the directory to which it applies. One would typically cd to this directory before starting the Scheme session.

Catalog files consist of one or more association lists. In the circumstance where a feature symbol appears in more than one list, the latter list's association is retrieved. Here are the supported formats for elements of catalog lists:

(feature . <symbol>): Redirects to the feature named <symbol>.
(feature . "<path>"): Loads file <path>.
(feature source "<path>"): slib:loads the Scheme source file <path>.
(feature compiled "<path>" ...): slib:load-compileds the files <path> ....

The various macro styles first require the named macro package, then just load <path> or load-and-macro-expand <path> as appropriate for the implementation.

(feature defmacro "<path>"): defmacro:loads the Scheme source file <path>.
(feature macro-by-example "<path>"): defmacro:loads the Scheme source file <path>.

(feature macro "<path>"): macro:loads the Scheme source file <path>.
(feature macros-that-work "<path>"): macro:loads the Scheme source file <path>.
(feature syntax-case "<path>"): macro:loads the Scheme source file <path>.
(feature syntactic-closures "<path>"): macro:loads the Scheme source file <path>.

Here is an example of a `usercat' catalog. A Program in this directory can invoke the `run' feature with (require 'run).

;;; "usercat": SLIB catalog additions for SIMSYNCH.     -*-scheme-*-

(
 (simsynch      . "../synch/simsynch.scm")
 (run           . "../synch/run.scm")
 (schlep        . "schlep.scm")
)

Catalog Compilation

SLIB combines the catalog information which doesn't vary per user into the file `slibcat' in the implementation-vicinity. Therefore `slibcat' needs change only when new software is installed or compiled. Because the actual pathnames of files can differ from installation to installation, SLIB builds a separate catalog for each implementation it is used with.

The definition of *SLIB-VERSION* in SLIB file `require.scm' is checked against the catalog association of *SLIB-VERSION* to ascertain when versions have changed. I recommend that the definition of *SLIB-VERSION* be changed whenever the library is changed. If multiple implementations of Scheme use SLIB, remember that recompiling one `slibcat' will fix only that implementation's catalog.

The compilation scripts of Scheme implementations which work with SLIB can automatically trigger catalog compilation by deleting `slibcat' or by invoking a special form of require:

Procedure: require 'new-catalog: This will load `mklibcat', which compiles and writes a new `slibcat'.

Another special form of require erases SLIB's catalog, forcing it to be reloaded the next time the catalog is queried.

Procedure: require #f: Removes SLIB's catalog information. This should be done before saving an executable image so that, when restored, its catalog will be loaded afresh.

Each file in the table below is descibed in terms of its file-system independent vicinity (see section Vicinity). The entries of a catalog in the table override those of catalogs above it in the table.

implementation-vicinity `slibcat': This file contains the associations for the packages comprising SLIB, the `implcat' and the `sitecat's. The associations in the other catalogs override those of the standard catalog.
library-vicinity `mklibcat.scm': creates `slibcat'.
library-vicinity `sitecat': This file contains the associations specific to an SLIB installation.
implementation-vicinity `implcat': This file contains the associations specific to an implementation of Scheme. Different implementations of Scheme should have different implementation-vicinity.
implementation-vicinity `mkimpcat.scm': if present, creates `implcat'.
implementation-vicinity `sitecat': This file contains the associations specific to a Scheme implementation installation.
home-vicinity `homecat': This file contains the associations specific to an SLIB user.
user-vicinity `usercat': This file contains associations effecting only those sessions whose working directory is user-vicinity.

Built-in Support

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

Require

Variable: *features*

Is a list of symbols denoting features supported in this implementation. *features* can grow as modules are required. *features* must be defined by all implementations (see section Porting).

Here are features which SLIB (`require.scm') adds to *features* when appropriate.

'inexact
'rational
'real
'complex
'bignum

For each item, (provided? 'feature) will return #t if that feature is available, and #f if not.

Variable: *modules*: Is a list of pathnames denoting files which have been loaded.

Variable: *catalog*: Is an association list of features (symbols) and pathnames which will supply those features. The pathname can be either a string or a pair. If pathname is a pair then the first element should be a macro feature symbol, source, or compiled. The cdr of the pathname should be either a string or a list.

In the following functions if the argument feature is not a symbol it is assumed to be a pathname.

Function: provided? feature: Returns #t if feature is a member of *features* or *modules* or if feature is supported by a file already loaded and #f otherwise.

Procedure: require feature

feature is a symbol. If (provided? feature) is true require returns. Otherwise, if

(assq feature
*catalog*)

is not #f, the associated files will be loaded and (provided? feature) will henceforth return #t. An unspecified value is returned. If feature is not found in *catalog*, then an error is signaled.

Procedure: require pathname

pathname is a string. If pathname has not already been given as an argument to require, pathname is loaded. An unspecified value is returned.

Procedure: provide feature: Assures that feature is contained in *features* if feature is a symbol and *modules* otherwise.

Function: require:feature->path feature: Returns #t if feature is a member of *features* or *modules* or if feature is supported by a file already loaded. Returns a path if one was found in *catalog* under the feature name, and #f otherwise. The path can either be a string suitable as an argument to load or a pair as described above for *catalog*.

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 path: Returns the vicinity of path for use by in-vicinity.

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

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 "2c4" 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 "2c4" on scm "5b1" on unix 
(implementation-vicinity) is "/home/jaffer/scm/" 
(library-vicinity) is "/home/jaffer/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 rev4-report 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 "/home/jaffer/scm/ioext.so") 
        ...

Input/Output

These procedures are provided by all implementations.

Procedure: 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.

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

Procedure: 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.

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

Procedure: output-port-width

Procedure: 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.

Procedure: output-port-height

Procedure: 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.

Legacy

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)

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

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

About this manual

Entries that are labeled as Functions are called for their return values. Entries that are labeled as Procedures are called primarily for their side effects.
Examples in this text were produced using the scm Scheme implementation.
At the beginning of each section, there is a line that looks like (require 'feature). Include this line in your code prior to using the package.

Go to the first, previous, next, last section, table of contents.