[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
#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 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
:
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.
(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.
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.
(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 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?
.
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.
[ < ] | [ > ] | [ << ] | [ 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>)
(feature . "<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> ...)
slib: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>.
[ < ] | [ > ] | [ << ] | [ 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:
Another special feature of require
erases SLIB's catalog,
forcing it to be reloaded the next time the catalog is queried.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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'
library-vicinity
`mklibcat.scm'
library-vicinity
`sitecat'
implementation-vicinity
`implcat'
implementation-vicinity
.
implementation-vicinity
`mkimpcat.scm'
implementation-vicinity
`sitecat'
home-vicinity
`homecat'
user-vicinity
`usercat'
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.
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
(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) |
define
,
define-syntax
, or defmacro
) suffices.
;@ (define (make-vicinity <pathname>) <pathname>) |
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 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.
(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.
(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.
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 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.
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).
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) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
require
d modules;
And for the library as a whole:
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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |