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 ² also appear at the beginning of their files conditioned on the feature compiling using require-if (see 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 Schmooz). For non-schmooz files, putting ‘;@’ at the beginning of the line immediately preceding the definition (define, define-syntax, or defmacro) suffices.

  ;@
  (define (identity <obj>) <obj>)
  

• 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: feature->requires* feature provided? catalog ¶

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

Function: file->requires* file provided? catalog ¶

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

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 definer … ¶

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)

Function: file->exports file definer … ¶

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)

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.

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)

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

The following function parses an Info Index. ³

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

1.6.5 Module Analysis

(require 'vet)

Function: vet-slib file1 … ¶

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:

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.

The optional arguments file1, … provide a simple way to vet prospective SLIB modules.