1. The Library System

1.1 Feature

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

• 'inexact
• 'rational
• 'real
• 'complex
• 'bignum

SLIB initialization (in `require.scm') tests and provides any of these numeric features which are appropriate.

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

Function: provided? feature

Returns #t if feature is present in the current Scheme session; otherwise #f. More specifically, provided? returns #t if the symbol feature is the software-type or if feature has been provided by a module already loaded; and #f otherwise.

In some implementations provided? tests whether a module has been required by any module or in any thread; other implementations will have provided? reflect only the modules required by that particular session or thread.

To work portably in both scenarios, use provided? only to test whether intrinsic properties (like those above) are present.

The feature argument can also be an expression calling and, or, and not of features. The boolean result of the logical question asked by feature is returned.

The generalization of provided? for arbitrary features and catalog is feature-eval:

Function: feature-eval expression provided?

Evaluates and, or, and not forms in expression, using the values returned by calling provided? on the leaf symbols. feature-eval returns the boolean result of the logical combinations.

Procedure: provide feature

Informs SLIB that feature is supported in this session.

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

1.2 Require

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

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, compiled, or one of the other cases described in 1.3 Library Catalogs. The cdr of the pathname should be either a string or a list.

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.
• Otherwise, if feature is found in the catalog, then the corresponding files will be loaded and (provided? feature) will henceforth return #t. That feature is thereafter provided.
• Otherwise (feature not found in the catalog), an error is signaled.

There is a related form require-if, used primarily for enabling compilers to statically include modules which would be dynamically loaded by interpreters.

Procedure: require-if condition feature

Requires feature if condition is true.

The random module uses require-if to flag object->string as a (dynamic) required module.

(require 'byte)
(require 'logical)
(require-if 'compiling 'object->string)

The batch module uses require-if to flag posix-time as a module to load if the implementation supports large precision exact integers.

(require-if '(and bignum compiling) 'posix-time)

The commutative-ring module uses require-if to ensure that it has an exponentiation routine, regardless of whether the implementation supports inexact numbers:

(require-if '(not inexact) 'logical)    ;for integer-expt
(define number^ (if (provided? 'inexact) expt integer-expt))

The catalog can also be queried using slib:in-catalog?.

Function: slib:in-catalog? feature

Returns a CDR of the catalog entry if one was found for the symbol feature in the alist *catalog* (and transitively through any symbol aliases encountered). Otherwise, returns #f. The format of catalog entries is explained in 1.3 Library Catalogs.

1.3 Library Catalogs

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

(feature aggregate <symbol> ...)

slib:requires the features <symbol> ....

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

1.4 Catalog Creation

At the start of an interactive 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.
• packages which are part of an application program.

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. It is a reasonable practice to change the definition of *SLIB-VERSION* whenever the library is changed. If multiple implementations of Scheme use SLIB, remember that recompiling one `slibcat' will update 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 require of a special feature:

Procedure: require 'new-catalog

This will load `mklibcat', which compiles and writes a new `slibcat'.

Another special feature 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.

1.5 Catalog Vicinities

Each file in the table below is descibed in terms of its file-system independent vicinity (see section 2.1 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 affecting only those sessions whose working directory is user-vicinity.

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

Copying `usercat' to many directories is inconvenient. Application programs which aren't always run in specially prepared directories can nonetheless register their features during initialization.

Procedure: catalog:read vicinity catalog

Reads file named by string catalog in vicinity, resolving all paths relative to vicinity, and adds those feature associations to *catalog*.

catalog:read would typically be used by an application program having dynamically loadable modules. For instance, to register factoring and other modules in *catalog*, JACAL does:

(catalog:read (program-vicinity) "jacalcat")

For an application program there are three appropriate venues for registering its catalog associations:

• in a `usercat' file in the directory where the program runs; or
• in an `implcat' file in the implementation-vicinity; or
• in an application program directory; loaded by calling catalog:read.

1.6 Compiling Scheme

To use Scheme compilers effectively with SLIB the compiler needs to know which SLIB modules are to be compiled and which symbols are exported from those modules.

The procedures in this section automate the extraction of this information from SLIB modules. They are guaranteed to work on SLIB modules; to use them on other sources, those sources should follow SLIB conventions.

1.6.1 Module Conventions

• All the top-level require commands have one quoted argument and are positioned before other Scheme definitions and expressions in the file.
• Any conditionally required SLIB modules (1) also appear at the beginning of their files conditioned on the feature compiling using require-if (see section require-if).

  (require 'logical) (require 'multiarg/and-) (require-if 'compiling 'sort) (require-if 'compiling 'ciexyz)

• Schmooz-style comments preceding a definition, identify that definition as an exported identifier (see section 4.14 Schmooz). For non-schmooz files, putting `;@' at the beginning of the line immediately preceding the definition (define, define-syntax, or defmacro) suffices.

  ;@ (define (make-vicinity <pathname>) <pathname>)

• Syntax (macro) definitions are grouped at the end of a module file.

• Modules defining macros do not invoke those macros. SLIB macro implementations are exempt from this rule.

  An example of how to expand macro invocations is:

  (require 'macros-that-work) (require 'yasos) (require 'pprint-file) (pprint-filter-file "collect.scm" macwork:expand)

1.6.2 Module Manifests

(require 'manifest)

In some of these examples, slib:catalog is the SLIB part of the catalog; it is free of compiled and implementation-specific entries. It would be defined by:

(define slib:catalog (cdr (member (assq 'null *catalog*) *catalog*)))

Function: file->requires file provided? catalog

Returns a list of the features required by file assuming the predicate provided? and association-list catalog.

(define (provided+? . features)
  (lambda (feature)
    (or (memq feature features) (provided? feature))))

(file->requires "obj2str.scm" (provided+? 'compiling) '())
        => (string-port generic-write)

(file->requires "obj2str.scm" provided? '())
        => (string-port)

Function: feature->requires feature provided? catalog

Returns a list of the features required by feature assuming the predicate provided? and association-list catalog.

(feature->requires 'batch (provided+? 'compiling) *catalog*)
        => (tree line-i/o databases parameters string-port
                   pretty-print common-list-functions posix-time)

(feature->requires 'batch provided? *catalog*)
        => (tree line-i/o databases parameters string-port
                   pretty-print common-list-functions)

(feature->requires 'batch provided? '((batch . "batch")))
        => (tree line-i/o databases parameters string-port
                   pretty-print common-list-functions)

Function: file->loads file

Returns a list of strings naming existing files loaded (load slib:load slib:load-source macro:load defmacro:load syncase:load synclo:load macwork:load) by file or any of the files it loads.

(file->loads (in-vicinity (library-vicinity) "scainit.scm"))
        => ("/usr/local/lib/slib/scaexpp.scm"
            "/usr/local/lib/slib/scaglob.scm"
            "/usr/local/lib/slib/scaoutp.scm")

Function: load->path exp

Given a (load '<expr>), where <expr> is a string or vicinity stuff), (load->path <expr>) figures a path to the file. load->path returns that path if it names an existing file; otherwise #f.

(load->path '(in-vicinity (library-vicinity) "mklibcat"))
        => "/usr/local/lib/slib/mklibcat.scm"

Function: file->definitions file

Returns a list of the identifier symbols defined by SLIB (or SLIB-style) file file.

(file->definitions "random.scm")
        => (*random-state* make-random-state
           seed->random-state copy-random-state random
           random:chunk)

Function: file->exports file

Returns a list of the identifier symbols exported (advertised) by SLIB (or SLIB-style) file file.

(file->exports "random.scm")
        => (make-random-state seed->random-state
            copy-random-state random)

(file->exports "randinex.scm")
        => (random:solid-sphere! random:hollow-sphere!
            random:normal-vector! random:normal
            random:exp random:uniform)

Function: feature->export-alist feature catalog

Returns a list of lists; each sublist holding the name of the file implementing feature, and the identifier symbols exported (advertised) by SLIB (or SLIB-style) feature feature, in catalog.

Function: feature->exports feature catalog

Returns a list of all exports of feature.

(feature->export-alist 'r5rs slib:catalog))
        => (("/usr/local/lib/slib/values.scm"
             call-with-values values)
            ("/usr/local/lib/slib/mbe.scm"
             define-syntax macro:expand
             macro:load macro:eval)
            ("/usr/local/lib/slib/eval.scm"
             eval scheme-report-environment
             null-environment interaction-environment))

(feature->export-alist 'stdio *catalog*)
        => (("/usr/local/lib/slib/scanf.scm"
             fscanf sscanf scanf scanf-read-list)
            ("/usr/local/lib/slib/printf.scm"
             sprintf printf fprintf)
            ("/usr/local/lib/slib/stdio.scm"
             stderr stdout stdin))

(feature->exports 'stdio slib:catalog)
        => (fscanf sscanf scanf scanf-read-list
             sprintf printf fprintf stderr stdout stdin)

1.6.3 Module Semantics

For the purpose of compiling Scheme code, each top-level require makes the identifiers exported by its feature's module defined (or defmacroed or defined-syntaxed) within the file (being compiled) headed with those requires.

Top-level occurrences of require-if make defined the exports from the module named by the second argument if the feature-expression first argument is true in the target environment. The target feature compiling should be provided during this phase of compilation.

Non-top-level SLIB occurences of require and require-if of quoted features can be ignored by compilers. The SLIB modules will all have top-level constructs for those features.

Note that aggregate catalog entries import more than one module. Implementations of require may or may not be transitive; code which uses module exports without requiring the providing module is in error.

In the SLIB modules modular, batch, hash, common-lisp-time, commutative-ring, charplot, logical, common-list-functions, coerce and break there is code conditional on features being provided?. Most are testing for the presence of features which are intrinsic to implementations (inexacts, bignums, ...).

In all cases these provided? tests can be evaluated at compile-time using feature-eval (see section feature-eval). The simplest way to compile these constructs may be to treat provided? as a macro.

1.6.4 Top-level Variable References

(require 'top-refs)

These procedures complement those in 1.6.2 Module Manifests by finding the top-level variable references in Scheme source code. They work by traversing expressions and definitions, keeping track of bindings encountered. It is certainly possible to foil these functions, but they return useful information about SLIB source code.

Function: top-refs obj

Returns a list of the top-level variables referenced by the Scheme expression obj.

Function: top-refs<-file filename

filename should be a string naming an existing file containing Scheme source code. top-refs<-file returns a list of the top-level variable references made by expressions in the file named by filename.

Code in modules which filename requires is not traversed. Code in files loaded from top-level is traversed if the expression argument to load, slib:load, slib:load-source, macro:load, defmacro:load, synclo:load, syncase:load, or macwork:load is a literal string constant or composed of combinations of vicinity functions and string literal constants; and the resulting file exists (possibly with ".scm" appended).

Function: exports<-info-index file n ...

n ... must be an increasing series of positive integers. exports<-info-index returns a list of all the identifiers appearing in the nth ... (info) indexes of file. The identifiers have the case that the implementation's read uses for symbols. Identifiers containing spaces (eg. close-base on base-table) are not included.

Each info index is headed by a `* Menu:' line. To list the symbols in the first and third info indexes do:

(exports<-info-index "slib.info" 1 3)

1.6.5 Module Analysis

(require 'vet)

Function: vet-slib

Using the procedures in the top-refs and manifest modules, vet-slib analyzes each SLIB module, reporting about any procedure or macro defined whether it is:

orphaned

defined, not called, not exported;

missing

called, not defined, and not exported by its required modules;

undocumented-export

Exported by module, but no index entry in `slib.info';

And for the library as a whole:

documented-unexport

Index entry in `slib.info', but no module exports it.

This straightforward analysis caught three full days worth of never-executed branches, transitive require assumptions, spelling errors, undocumented procedures, missing procedures, and cyclic dependencies in SLIB.