slib2c0 cats! (was Re: Module Considerations)

[Aubrey Jaffer <jaffer@martigny.ai.mit.edu>]

Our discussion of search paths prompted me to augment (and hopefully
complete) SLIB's catalog extension mechanisms.  I also reorganized
SLIB2c0 documentation so that the `library' interface is presented
separately from the packages in the library.

	 http://www-swiss.ai.mit.edu/~jaffer/slib_1.html#SEC5

			      -=-=-=-=-

File: slib.info,  Node: Library Catalogs,  Next: Catalog Compilation,  Prev: Requesting Features,  Up: The Library System

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 list"s.  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> ....

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

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