[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 Scheme implementations. Its catalog can be transparently extended to accomodate packages specific to a site, implementation, user, or directory.
1.1 Feature | SLIB names. | |
1.2 Require | ||
1.3 Library Catalogs | ||
1.4 Catalog Creation | ||
1.5 Catalog Vicinities | ||
1.6 Compiling Scheme |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
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).
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
, the scheme-implementation-type
(1), or if feature has been provided by a module already
loaded; and #f
otherwise.
In some implementations provided?
tests whether a module has
been require
d by any module or in any thread; other
implementations will have provided?
reflect only the modules
require
d 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
:
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.
Informs SLIB that feature is supported in this session.
(provided? 'foo) ⇒ #f (provide 'foo) (provided? 'foo) ⇒ #t |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
SLIB creates and maintains a catalog mapping features to locations of files introducing procedures and syntax denoted by those features.
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 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.
(provided? feature)
is true,
then require
just returns.
(provided?
feature)
will henceforth return #t
. That feature
is thereafter provided
.
There is a related form require-if
, used primarily for enabling
compilers to statically include modules which would be dynamically
loaded by interpreters.
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 catalog can also be queried using slib:in-catalog?
.
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
Library Catalogs.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:load
s the Scheme source file <path>.
(feature compiled "<path>" …)
slib:load-compiled
s the files <path> ….
(feature aggregate <symbol> …)
require
s 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:load
s the Scheme source file <path>.
(feature macro-by-example "<path>")
defmacro:load
s the Scheme source file <path>.
(feature macro "<path>")
macro:load
s the Scheme source file <path>.
(feature macros-that-work "<path>")
macro:load
s the Scheme source file <path>.
(feature syntax-case "<path>")
macro:load
s the Scheme source file <path>.
(feature syntactic-closures "<path>")
macro:load
s the Scheme source file <path>.
Note that file names indicated as <path> may have “.scm” or another suffix appended to them, depending on the specific Scheme system you are using.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
cd
to this directory before starting the
Scheme session.
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:
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.
Removes SLIB’s catalog information. This should be done before saving an executable image so that, when restored, its catalog will be loaded afresh.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 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.
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:
implementation-vicinity
; or
catalog:read
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 | ||
1.6.2 Module Manifests | ||
1.6.3 Module Semantics | ||
1.6.4 Top-level Variable References | ||
1.6.5 Module Analysis |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
require
commands have one quoted argument and
are positioned before other Scheme definitions and expressions in the
file.
require
d SLIB modules
(2)
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) |
define
,
define-syntax
, or defmacro
) suffices.
;@ (define (identity <obj>) <obj>) |
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) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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*))) |
Returns a list of the features require
d 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) |
Returns a list of the features require
d 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) |
Returns a list of the features transitively require
d by feature
assuming the predicate provided? and association-list catalog.
Returns a list of the features transitively require
d by file
assuming the predicate provided? and association-list catalog.
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") |
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" |
Returns a list of the identifier symbols defined by SLIB (or
SLIB-style) file file. The optional arguments definers should be symbols
signifying a defining form. If none are supplied, then the symbols
define-operation
, define
, define-syntax
, and
defmacro
are captured.
(file->definitions "random.scm") ⇒ (*random-state* make-random-state seed->random-state copy-random-state random random:chunk) |
Returns a list of the identifier symbols exported (advertised) by
SLIB (or SLIB-style) file file. The optional arguments definers should be
symbols signifying a defining form. If none are supplied, then the
symbols define-operation
, define
,
define-syntax
, and defmacro
are captured.
(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) |
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.
Returns a list of all exports of feature.
In the case of aggregate
features, more than one file may
have export lists to report:
(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) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These procedures complement those in 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.
Returns a list of the top-level variables referenced by the Scheme expression obj.
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 require
s 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).
The following function parses an Info Index. (3)
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. #f is returned if the index is not found.
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) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Using the procedures in the top-refs
and manifest
modules, vet-slib
analyzes each SLIB module and file1, …, reporting
about any procedure or macro defined whether it is:
defined, not called, not exported;
called, not defined, and not exported by its require
d modules;
Exported by module, but no index entry in ‘slib.info’;
And for the library as a whole:
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.
The optional arguments file1, … provide a simple way to vet prospective SLIB modules.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on May 5, 2010 using texi2html 1.82.