diff options
Diffstat (limited to 'slib_1.html')
| -rw-r--r-- | slib_1.html | 1172 |
1 files changed, 1172 insertions, 0 deletions
diff --git a/slib_1.html b/slib_1.html new file mode 100644 index 0000000..452374a --- /dev/null +++ b/slib_1.html @@ -0,0 +1,1172 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html40/loose.dtd"> +<HTML> +<!-- Created on January, 10 2005 by texi2html 1.66 --> +<!-- +Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) + Karl Berry <karl@freefriends.org> + Olaf Bachmann <obachman@mathematik.uni-kl.de> + and many others. +Maintained by: Many creative people <dev@texi2html.cvshome.org> +Send bugs and suggestions to <users@texi2html.cvshome.org> + +--> +<HEAD> +<TITLE>SLIB: The Library System</TITLE> + +<META NAME="description" CONTENT="SLIB: The Library System"> +<META NAME="keywords" CONTENT="SLIB: The Library System"> +<META NAME="resource-type" CONTENT="document"> +<META NAME="distribution" CONTENT="global"> +<META NAME="Generator" CONTENT="texi2html 1.66"> + +</HEAD> + +<BODY LANG="en" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"> + +<A NAME="SEC1"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC2"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<A NAME="The Library System"></A> +<H1> 1. The Library System </H1> +<!--docid::SEC1::--> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC2">1.1 Feature</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">SLIB names.</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC3">1.2 Require</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC4">1.3 Library Catalogs</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC5">1.4 Catalog Creation</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC6">1.5 Catalog Vicinities</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC7">1.6 Compiling Scheme</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +</TABLE> +<P> + +<A NAME="Feature"></A> +<HR SIZE="6"> +<A NAME="SEC2"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC3"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 1.1 Feature </H2> +<!--docid::SEC2::--> +<P> + +<A NAME="IDX1"></A> +SLIB denotes <EM>features</EM> by symbols. SLIB maintains a list of +features supported by a Scheme <EM>session</EM>. The set of features +<A NAME="IDX2"></A> +provided by a session may change during that session. Some features +are properties of the Scheme implementation being used. The following +<A NAME="IDX3"></A> +<EM>intrinsic feature</EM>s detail what sort of numbers are available +from an implementation: +</P> +<P> + +<UL> +<LI> +'inexact +<LI> +'rational +<LI> +'real +<LI> +'complex +<LI> +'bignum +</UL> +<P> + +SLIB initialization (in `<TT>require.scm</TT>') tests and <EM>provide</EM>s +any of these numeric features which are appropriate. +</P> +<P> + +Other features correspond to the presence of packages of Scheme +procedures or syntax (macros). +</P> +<P> + +<A NAME="IDX4"></A> +</P> +<DL> +<DT><U>Function:</U> <B>provided?</B> <I>feature</I> +<DD>Returns <CODE>#t</CODE> if <VAR>feature</VAR> is present in the current Scheme +session; otherwise <CODE>#f</CODE>. More specifically, <CODE>provided?</CODE> +returns <CODE>#t</CODE> if the symbol <VAR>feature</VAR> is the +<CODE>software-type</CODE> or if <VAR>feature</VAR> has been provided by a module +already loaded; and <CODE>#f</CODE> otherwise. +<P> + +In some implementations <CODE>provided?</CODE> tests whether a module has +been <CODE>require</CODE>d by any module or in any thread; other +implementations will have <CODE>provided?</CODE> reflect only the modules +<CODE>require</CODE>d by that particular session or thread. +</P> +<P> + +To work portably in both scenarios, use <CODE>provided?</CODE> only to test +whether intrinsic properties (like those above) are present. +</P> +<P> + +The <VAR>feature</VAR> argument can also be an expression calling +<CODE>and</CODE>, <CODE>or</CODE>, and <CODE>not</CODE> of features. The boolean result +of the logical question asked by <VAR>feature</VAR> is returned. +</P> +</DL> +<P> + +The generalization of <CODE>provided?</CODE> for arbitrary features and catalog +is <CODE>feature-eval</CODE>: +</P> +<P> + +<A NAME="IDX5"></A> +</P> +<DL> +<DT><U>Function:</U> <B>feature-eval</B> <I>expression provided?</I> +<DD>Evaluates <CODE>and</CODE>, <CODE>or</CODE>, and <CODE>not</CODE> forms in +<VAR>expression</VAR>, using the values returned by calling <VAR>provided?</VAR> +on the leaf symbols. <CODE>feature-eval</CODE> returns the boolean result +of the logical combinations. +</DL> +<P> + +<A NAME="IDX6"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>provide</B> <I>feature</I> +<DD>Informs SLIB that <VAR>feature</VAR> is supported in this session. +</DL> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(provided? 'foo) => #f +(provide 'foo) +(provided? 'foo) => #t +</pre></td></tr></table><P> + +<A NAME="Require"></A> +<HR SIZE="6"> +<A NAME="SEC3"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC2"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC4"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 1.2 Require </H2> +<!--docid::SEC3::--> +<P> + +<A NAME="IDX7"></A> +SLIB creates and maintains a <EM>catalog</EM> mapping features to locations +of files introducing procedures and syntax denoted by those features. +</P> +<P> + +<A NAME="IDX8"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*catalog*</B> +<DD>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, <CODE>source</CODE>, <CODE>compiled</CODE>, or one of the other cases +described in <A HREF="slib_1.html#SEC4">1.3 Library Catalogs</A>. The cdr of the pathname should +be either a string or a list. +</DL> +<P> + +At the beginning of each section of this manual, there is a line like +<CODE>(require '<VAR>feature</VAR>)</CODE>. +<A NAME="IDX9"></A> +The Scheme files comprising SLIB are cataloged so that these feature +names map to the corresponding files. +</P> +<P> + +SLIB provides a form, <CODE>require</CODE>, which loads the files providing +the requested feature. +</P> +<P> + +<A NAME="IDX10"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>require</B> <I>feature</I> +<DD><UL> +<LI> +If <CODE>(provided? <VAR>feature</VAR>)</CODE> is true, +then <CODE>require</CODE> just returns. +<LI> +Otherwise, if <VAR>feature</VAR> is found in the catalog, then the +corresponding files will be loaded and <CODE>(provided? +<VAR>feature</VAR>)</CODE> will henceforth return <CODE>#t</CODE>. That <VAR>feature</VAR> +is thereafter <CODE>provided</CODE>. +<LI> +Otherwise (<VAR>feature</VAR> not found in the catalog), an error is +signaled. +</UL> +</DL> +<P> + +There is a related form <CODE>require-if</CODE>, used primarily for enabling +compilers to statically include modules which would be dynamically +loaded by interpreters. +</P> +<P> + +<A NAME="IDX11"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>require-if</B> <I>condition feature</I> +<DD><P> + +Requires <VAR>feature</VAR> if <VAR>condition</VAR> is true. +</P> +</DL> +<P> + +The <CODE>random</CODE> module uses <CODE>require-if</CODE> to flag +<CODE>object->string</CODE> as a (dynamic) required module. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require 'byte) +(require 'logical) +(require-if 'compiling 'object->string) +</pre></td></tr></table><P> + +The <CODE>batch</CODE> module uses <CODE>require-if</CODE> to flag +<CODE>posix-time</CODE> as a module to load if the implementation supports +large precision exact integers. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require-if '(and bignum compiling) 'posix-time) +</pre></td></tr></table><P> + +The <CODE>commutative-ring</CODE> module uses <CODE>require-if</CODE> to ensure +that it has an exponentiation routine, regardless of whether the +implementation supports inexact numbers: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require-if '(not inexact) 'logical) ;for integer-expt +(define number^ (if (provided? 'inexact) expt integer-expt)) +</pre></td></tr></table><P> + +The catalog can also be queried using <CODE>slib:in-catalog?</CODE>. +</P> +<P> + +<A NAME="IDX12"></A> +</P> +<DL> +<DT><U>Function:</U> <B>slib:in-catalog?</B> <I>feature</I> +<DD>Returns a <CODE>CDR</CODE> of the catalog entry if one was found for the +symbol <VAR>feature</VAR> in the alist <CODE>*catalog*</CODE> (and transitively +through any symbol aliases encountered). Otherwise, returns +<CODE>#f</CODE>. The format of catalog entries is explained in <A HREF="slib_1.html#SEC4">1.3 Library Catalogs</A>. +</DL> +<P> + +<A NAME="Library Catalogs"></A> +<HR SIZE="6"> +<A NAME="SEC4"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC3"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC5"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 1.3 Library Catalogs </H2> +<!--docid::SEC4::--> +<P> + +Catalog files consist of one or more <EM>association list</EM>s. +<A NAME="IDX13"></A> +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: +</P> +<P> + +</P> +<DL COMPACT> +<DT><CODE>(<VAR>feature</VAR> . <I><symbol></I>)</CODE> +<DD>Redirects to the feature named <I><symbol></I>. +<DT><CODE>(<VAR>feature</VAR> . "<I><path></I>")</CODE> +<DD>Loads file <I><path></I>. +<DT><CODE>(<VAR>feature</VAR> source "<I><path>"</I>)</CODE> +<DD><A NAME="IDX14"></A> +<CODE>slib:load</CODE>s the Scheme source file <I><path></I>. +<DT><CODE>(<VAR>feature</VAR> compiled "<I><path>"</I> <small>...</small>)</CODE> +<DD><A NAME="IDX15"></A> +<CODE>slib:load-compiled</CODE>s the files <I><path></I> <small>...</small>. +<DT><CODE>(<VAR>feature</VAR> aggregate <I><symbol></I> <small>...</small>)</CODE> +<DD><A NAME="IDX16"></A> +<CODE>slib:require</CODE>s the features <I><symbol></I> <small>...</small>. +</DL> +<P> + +The various macro styles first <CODE>require</CODE> the named macro package, +then just load <I><path></I> or load-and-macro-expand <I><path></I> as +appropriate for the implementation. +</P> +<P> + +</P> +<DL COMPACT> +<DT><CODE>(<VAR>feature</VAR> defmacro "<I><path>"</I>)</CODE> +<DD><A NAME="IDX17"></A> +<CODE>defmacro:load</CODE>s the Scheme source file <I><path></I>. +<DT><CODE>(<VAR>feature</VAR> macro-by-example "<I><path>"</I>)</CODE> +<DD><A NAME="IDX18"></A> +<CODE>defmacro:load</CODE>s the Scheme source file <I><path></I>. +</DL> +<P> + +</P> +<DL COMPACT> +<DT><CODE>(<VAR>feature</VAR> macro "<I><path>"</I>)</CODE> +<DD><A NAME="IDX19"></A> +<CODE>macro:load</CODE>s the Scheme source file <I><path></I>. +<DT><CODE>(<VAR>feature</VAR> macros-that-work "<I><path>"</I>)</CODE> +<DD><A NAME="IDX20"></A> +<CODE>macro:load</CODE>s the Scheme source file <I><path></I>. +<DT><CODE>(<VAR>feature</VAR> syntax-case "<I><path>"</I>)</CODE> +<DD><A NAME="IDX21"></A> +<CODE>macro:load</CODE>s the Scheme source file <I><path></I>. +<DT><CODE>(<VAR>feature</VAR> syntactic-closures "<I><path>"</I>)</CODE> +<DD><A NAME="IDX22"></A> +<CODE>macro:load</CODE>s the Scheme source file <I><path></I>. +</DL> +<P> + +<A NAME="Catalog Creation"></A> +<HR SIZE="6"> +<A NAME="SEC5"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC4"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC6"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 1.4 Catalog Creation </H2> +<!--docid::SEC5::--> +<P> + +At the start of an interactive session no catalog is present, but is +created with the first catalog inquiry (such as <CODE>(require +'random)</CODE>). Several sources of catalog information are combined to +produce the catalog: +</P> +<P> + +<UL> +<LI> +standard SLIB packages. +<LI> +additional packages of interest to this site. +<LI> +packages specifically for the variety of Scheme which this +session is running. +<LI> +packages this user wants to always have available. This catalog is the +file `<TT>homecat</TT>' in the user's <EM>HOME</EM> directory. +<A NAME="IDX23"></A> +<LI> +packages germane to working in this (current working) directory. This +catalog is the file `<TT>usercat</TT>' in the directory to which it applies. +One would typically <CODE>cd</CODE> to this directory before starting the +Scheme session. +<LI> +packages which are part of an application program. +</UL> +<P> + +SLIB combines the catalog information which doesn't vary per user into +the file `<TT>slibcat</TT>' in the implementation-vicinity. Therefore +`<TT>slibcat</TT>' 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. +</P> +<P> + +The definition of <CODE>*SLIB-VERSION*</CODE> in SLIB file +`<TT>require.scm</TT>' is checked against the catalog association of +<CODE>*SLIB-VERSION*</CODE> to ascertain when versions have changed. It is +a reasonable practice to change the definition of +<CODE>*SLIB-VERSION*</CODE> whenever the library is changed. If multiple +implementations of Scheme use SLIB, remember that recompiling one +`<TT>slibcat</TT>' will update only that implementation's catalog. +</P> +<P> + +The compilation scripts of Scheme implementations which work with SLIB +can automatically trigger catalog compilation by deleting +`<TT>slibcat</TT>' or by invoking <CODE>require</CODE> of a special feature: +</P> +<P> + +<A NAME="IDX24"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>require</B> <I>'new-catalog</I> +<DD><A NAME="IDX25"></A> +This will load `<TT>mklibcat</TT>', which compiles and writes a new +`<TT>slibcat</TT>'. +</DL> +<P> + +Another special feature of <CODE>require</CODE> erases SLIB's catalog, +forcing it to be reloaded the next time the catalog is queried. +</P> +<P> + +<A NAME="IDX26"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>require</B> <I>#f</I> +<DD>Removes SLIB's catalog information. This should be done before saving +an executable image so that, when restored, its catalog will be loaded +afresh. +</DL> +<P> + +<A NAME="Catalog Vicinities"></A> +<HR SIZE="6"> +<A NAME="SEC6"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC5"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 1.5 Catalog Vicinities </H2> +<!--docid::SEC6::--> +<P> + +Each file in the table below is descibed in terms of its +file-system independent <EM>vicinity</EM> (see section <A HREF="slib_2.html#SEC14">2.1 Vicinity</A>). The entries +of a catalog in the table override those of catalogs above it in the +table. +</P> +<P> + +</P> +<DL COMPACT> + +<DT><CODE>implementation-vicinity</CODE> `<TT>slibcat</TT>' +<DD><A NAME="IDX27"></A> +This file contains the associations for the packages comprising SLIB, +the `<TT>implcat</TT>' and the `<TT>sitecat</TT>'s. The associations in the +other catalogs override those of the standard catalog. +<P> + +</P> +<DT><CODE>library-vicinity</CODE> `<TT>mklibcat.scm</TT>' +<DD><A NAME="IDX28"></A> +creates `<TT>slibcat</TT>'. +<P> + +</P> +<DT><CODE>library-vicinity</CODE> `<TT>sitecat</TT>' +<DD><A NAME="IDX29"></A> +This file contains the associations specific to an SLIB installation. +<P> + +</P> +<DT><CODE>implementation-vicinity</CODE> `<TT>implcat</TT>' +<DD><A NAME="IDX30"></A> +This file contains the associations specific to an implementation of +Scheme. Different implementations of Scheme should have different +<CODE>implementation-vicinity</CODE>. +<P> + +</P> +<DT><CODE>implementation-vicinity</CODE> `<TT>mkimpcat.scm</TT>' +<DD><A NAME="IDX31"></A> +if present, creates `<TT>implcat</TT>'. +<P> + +</P> +<DT><CODE>implementation-vicinity</CODE> `<TT>sitecat</TT>' +<DD><A NAME="IDX32"></A> +This file contains the associations specific to a Scheme implementation +installation. +<P> + +</P> +<DT><CODE>home-vicinity</CODE> `<TT>homecat</TT>' +<DD><A NAME="IDX33"></A> +This file contains the associations specific to an SLIB user. +<P> + +</P> +<DT><CODE>user-vicinity</CODE> `<TT>usercat</TT>' +<DD><A NAME="IDX34"></A> +This file contains associations affecting only those sessions whose +<EM>working directory</EM> is <CODE>user-vicinity</CODE>. +<P> + +</DL> +<P> + +Here is an example of a `<TT>usercat</TT>' catalog. A program in this +directory can invoke the `<SAMP>run</SAMP>' feature with <CODE>(require 'run)</CODE>. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>;;; "usercat": SLIB catalog additions for SIMSYNCH. -*-scheme-*- +( + (simsynch . "../synch/simsynch.scm") + (run . "../synch/run.scm") + (schlep . "schlep.scm") +) +</pre></td></tr></table><P> + +Copying `<TT>usercat</TT>' to many directories is inconvenient. +Application programs which aren't always run in specially prepared +directories can nonetheless register their features during +initialization. +</P> +<P> + +<A NAME="IDX35"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>catalog:read</B> <I>vicinity catalog</I> +<DD>Reads file named by string <VAR>catalog</VAR> in <VAR>vicinity</VAR>, resolving +all paths relative to <VAR>vicinity</VAR>, and adds those feature +associations to <VAR>*catalog*</VAR>. +<P> + +<CODE>catalog:read</CODE> would typically be used by an application program +having dynamically loadable modules. For instance, to register +factoring and other modules in <VAR>*catalog*</VAR>, JACAL does: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(catalog:read (program-vicinity) "jacalcat") +</pre></td></tr></table><P> + +</P> +</DL> +<P> + +For an application program there are three appropriate venues for +registering its catalog associations: +</P> +<P> + +<UL> +<LI> +in a `<TT>usercat</TT>' file in the directory where the program runs; or +<LI> +in an `<TT>implcat</TT>' file in the <CODE>implementation-vicinity</CODE>; or +<LI> +in an application program directory; loaded by calling +<CODE>catalog:read</CODE>. +</UL> +<P> + +<A NAME="Compiling Scheme"></A> +<HR SIZE="6"> +<A NAME="SEC7"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC6"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC8"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 1.6 Compiling Scheme </H2> +<!--docid::SEC7::--> +<P> + +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. +</P> +<P> + +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. +</P> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC8">1.6.1 Module Conventions</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC9">1.6.2 Module Manifests</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC10">1.6.3 Module Semantics</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC11">1.6.4 Top-level Variable References</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_1.html#SEC12">1.6.5 Module Analysis</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +</TABLE> +<P> + +<A NAME="Module Conventions"></A> +<HR SIZE="6"> +<A NAME="SEC8"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC9"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 1.6.1 Module Conventions </H3> +<!--docid::SEC8::--> +<P> + +<UL> +<LI> +All the top-level <CODE>require</CODE> commands have one quoted argument and +are positioned before other Scheme definitions and expressions in the +file. +<LI> +Any conditionally <CODE>require</CODE>d SLIB modules +<A NAME="DOCF1" HREF="slib_fot.html#FOOT1">(1)</A> +also appear at the beginning of their files conditioned on the feature +<A NAME="IDX36"></A> +<CODE>compiling</CODE> using <CODE>require-if</CODE> +(see section <A HREF="slib_1.html#SEC3">require-if</A>). +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require 'logical) +(require 'multiarg/and-) +(require-if 'compiling 'sort) +(require-if 'compiling 'ciexyz) +</pre></td></tr></table><P> + +</P> +<LI> +Schmooz-style comments preceding a definition, identify that +definition as an exported identifier (see section <A HREF="slib_4.html#SEC87">4.14 Schmooz</A>). For +non-schmooz files, putting `<SAMP>;@</SAMP>' at the beginning of the line +immediately preceding the definition (<CODE>define</CODE>, +<CODE>define-syntax</CODE>, or <CODE>defmacro</CODE>) suffices. +<P> + +<TABLE><tr><td> </td><td class=example><pre>;@ +(define (make-vicinity <pathname>) <pathname>) +</pre></td></tr></table><P> + +</P> +<LI> +Syntax (macro) definitions are grouped at the end of a module file. +<P> + +</P> +<LI> +Modules defining macros do not invoke those macros. SLIB macro +implementations are exempt from this rule. +<P> + +An example of how to expand macro invocations is: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require 'macros-that-work) +(require 'yasos) +(require 'pprint-file) +(pprint-filter-file "collect.scm" macwork:expand) +</pre></td></tr></table><P> + +</UL> +<P> + +<A NAME="Module Manifests"></A> +<HR SIZE="6"> +<A NAME="SEC9"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC8"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC10"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 1.6.2 Module Manifests </H3> +<!--docid::SEC9::--> +<P> + +<CODE>(require 'manifest)</CODE> +<A NAME="IDX37"></A> +</P> +<P> + +In some of these examples, <VAR>slib:catalog</VAR> is the SLIB part of +the catalog; it is free of compiled and implementation-specific +entries. It would be defined by: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(define slib:catalog (cdr (member (assq 'null *catalog*) *catalog*))) +</pre></td></tr></table><P> + +<A NAME="IDX38"></A> +</P> +<DL> +<DT><U>Function:</U> <B>file->requires</B> <I>file provided? catalog</I> +<DD><P> + +Returns a list of the features <CODE>require</CODE>d by <VAR>file</VAR> assuming the +predicate <VAR>provided?</VAR> and association-list <VAR>catalog</VAR>. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(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) +</pre></td></tr></table><P> + +<A NAME="IDX39"></A> +</P> +<DL> +<DT><U>Function:</U> <B>feature->requires</B> <I>feature provided? catalog</I> +<DD><P> + +Returns a list of the features <CODE>require</CODE>d by <VAR>feature</VAR> assuming the +predicate <VAR>provided?</VAR> and association-list <VAR>catalog</VAR>. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(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) +</pre></td></tr></table><P> + +<A NAME="IDX40"></A> +</P> +<DL> +<DT><U>Function:</U> <B>file->loads</B> <I>file</I> +<DD><P> + +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 <VAR>file</VAR> or any of the files it loads. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(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") +</pre></td></tr></table><P> + +<A NAME="IDX41"></A> +</P> +<DL> +<DT><U>Function:</U> <B>load->path</B> <I>exp</I> +<DD><P> + +Given a <CODE>(load '<expr>)</CODE>, where <expr> is a string or vicinity +stuff), <CODE>(load->path <expr>)</CODE> figures a path to the file. +<CODE>load->path</CODE> returns that path if it names an existing file; otherwise #f. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(load->path '(in-vicinity (library-vicinity) "mklibcat")) + => "/usr/local/lib/slib/mklibcat.scm" +</pre></td></tr></table><P> + +<A NAME="IDX42"></A> +</P> +<DL> +<DT><U>Function:</U> <B>file->definitions</B> <I>file</I> +<DD><P> + +Returns a list of the identifier symbols defined by SLIB (or +SLIB-style) file <VAR>file</VAR>. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(file->definitions "random.scm") + => (*random-state* make-random-state + seed->random-state copy-random-state random + random:chunk) +</pre></td></tr></table><P> + +<A NAME="IDX43"></A> +</P> +<DL> +<DT><U>Function:</U> <B>file->exports</B> <I>file</I> +<DD><P> + +Returns a list of the identifier symbols exported (advertised) by +SLIB (or SLIB-style) file <VAR>file</VAR>. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(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) +</pre></td></tr></table><P> + +<A NAME="IDX44"></A> +</P> +<DL> +<DT><U>Function:</U> <B>feature->export-alist</B> <I>feature catalog</I> +<DD><P> + +Returns a list of lists; each sublist holding the name of the file +implementing <VAR>feature</VAR>, and the identifier symbols exported (advertised) by +SLIB (or SLIB-style) feature <VAR>feature</VAR>, in <VAR>catalog</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX45"></A> +</P> +<DL> +<DT><U>Function:</U> <B>feature->exports</B> <I>feature catalog</I> +<DD><P> + +Returns a list of all exports of <VAR>feature</VAR>. +</P> +</DL> +In the case of <CODE>aggregate</CODE> features, more than one file may +have export lists to report: +<P> + +<TABLE><tr><td> </td><td class=example><pre>(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) +</pre></td></tr></table><P> + +<A NAME="Module Semantics"></A> +<HR SIZE="6"> +<A NAME="SEC10"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC9"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC11"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 1.6.3 Module Semantics </H3> +<!--docid::SEC10::--> +<P> + +For the purpose of compiling Scheme code, each top-level +<CODE>require</CODE> makes the identifiers exported by its feature's module +<CODE>defined</CODE> (or defmacroed or defined-syntaxed) within the file +(being compiled) headed with those requires. +</P> +<P> + +Top-level occurrences of <CODE>require-if</CODE> make defined the exports +from the module named by the second argument <EM>if</EM> the +<VAR>feature-expression</VAR> first argument is true in the target +environment. The target feature <CODE>compiling</CODE> should be provided +during this phase of compilation. +</P> +<P> + +Non-top-level SLIB occurences of <CODE>require</CODE> and <CODE>require-if</CODE> +of quoted features can be ignored by compilers. The SLIB modules will +all have top-level constructs for those features. +</P> +<P> + +<A NAME="IDX46"></A> +Note that aggregate catalog entries import more than one module. +Implementations of <CODE>require</CODE> may or may <EM>not</EM> be transitive; +code which uses module exports without requiring the providing module +is in error. +</P> +<P> + +In the SLIB modules <CODE>modular</CODE>, <CODE>batch</CODE>, <CODE>hash</CODE>, +<CODE>common-lisp-time</CODE>, <CODE>commutative-ring</CODE>, <CODE>charplot</CODE>, +<CODE>logical</CODE>, <CODE>common-list-functions</CODE>, <CODE>coerce</CODE> and +<CODE>break</CODE> there is code conditional on features being +<CODE>provided?</CODE>. Most are testing for the presence of features which +are intrinsic to implementations (inexacts, bignums, ...). +</P> +<P> + +In all cases these <CODE>provided?</CODE> tests can be evaluated at +compile-time using <CODE>feature-eval</CODE> +(see section <A HREF="slib_1.html#SEC2">feature-eval</A>). The simplest way to compile these +constructs may be to treat <CODE>provided?</CODE> as a macro. +</P> +<P> + +<A NAME="Top-level Variable References"></A> +<HR SIZE="6"> +<A NAME="SEC11"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC10"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC12"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 1.6.4 Top-level Variable References </H3> +<!--docid::SEC11::--> +<P> + +<CODE>(require 'top-refs)</CODE> +<A NAME="IDX47"></A> +<A NAME="IDX48"></A> +<A NAME="IDX49"></A> +</P> +<P> + +These procedures complement those in <A HREF="slib_1.html#SEC9">1.6.2 Module Manifests</A> 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. +</P> +<P> + +<A NAME="IDX50"></A> +</P> +<DL> +<DT><U>Function:</U> <B>top-refs</B> <I>obj</I> +<DD><P> + +Returns a list of the top-level variables referenced by the Scheme +expression <VAR>obj</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX51"></A> +</P> +<DL> +<DT><U>Function:</U> <B>top-refs<-file</B> <I>filename</I> +<DD><P> + +<VAR>filename</VAR> should be a string naming an existing file containing Scheme +source code. <CODE>top-refs<-file</CODE> returns a list of the top-level variable references +made by expressions in the file named by <VAR>filename</VAR>. +</P> +<P> + +Code in modules which <VAR>filename</VAR> <CODE>require</CODE>s is not traversed. Code in +files loaded from top-level <EM>is</EM> traversed if the expression +argument to <CODE>load</CODE>, <CODE>slib:load</CODE>, <CODE>slib:load-source</CODE>, +<CODE>macro:load</CODE>, <CODE>defmacro:load</CODE>, <CODE>synclo:load</CODE>, +<CODE>syncase:load</CODE>, or <CODE>macwork:load</CODE> 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). +</P> +</DL> +The following function parses an <EM>Info</EM> Index. +<A NAME="IDX52"></A> +<A NAME="DOCF2" HREF="slib_fot.html#FOOT2">(2)</A> +<P> + +<A NAME="IDX53"></A> +</P> +<DL> +<DT><U>Function:</U> <B>exports<-info-index</B> <I>file n <small>...</small></I> +<DD><P> + +<VAR>n</VAR> <small>...</small> must be an increasing series of positive integers. +<CODE>exports<-info-index</CODE> returns a list of all the identifiers appearing in the <VAR>n</VAR>th +<small>...</small> (info) indexes of <VAR>file</VAR>. The identifiers have the case that +the implementation's <CODE>read</CODE> uses for symbols. Identifiers +containing spaces (eg. <CODE>close-base on base-table</CODE>) are +<EM>not</EM> included. +</P> +<P> + +Each info index is headed by a `<SAMP>* Menu:</SAMP>' line. To list the +symbols in the first and third info indexes do: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(exports<-info-index "slib.info" 1 3) +</pre></td></tr></table></DL> +<P> + +<A NAME="Module Analysis"></A> +<HR SIZE="6"> +<A NAME="SEC12"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC11"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC7"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 1.6.5 Module Analysis </H3> +<!--docid::SEC12::--> +<P> + +<CODE>(require 'vet)</CODE> +<A NAME="IDX54"></A> +</P> +<P> + +<A NAME="IDX55"></A> +</P> +<DL> +<DT><U>Function:</U> <B>vet-slib</B> +<DD><P> + +Using the procedures in the <CODE>top-refs</CODE> and <CODE>manifest</CODE> +modules, <CODE>vet-slib</CODE> analyzes each SLIB module, reporting about any +procedure or macro defined whether it is: +</P> +<P> + +</P> +<DL COMPACT> + +<DT>orphaned +<DD>defined, not called, not exported; +<DT>missing +<DD>called, not defined, and not exported by its <CODE>require</CODE>d modules; +<DT>undocumented-export +<DD>Exported by module, but no index entry in `<TT>slib.info</TT>'; +<P> + +</DL> +<P> + +And for the library as a whole: +</P> +<P> + +</P> +<DL COMPACT> + +<DT>documented-unexport +<DD>Index entry in `<TT>slib.info</TT>', but no module exports it. +<P> + +</DL> +<P> + +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. +</P> +</DL> +<P> + +<A NAME="Universal SLIB Procedures"></A> +<HR SIZE="6"> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_1.html#SEC1"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_2.html#SEC13"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<BR> +<FONT SIZE="-1"> +This document was generated +by <I>Steve Langasek</I> on <I>January, 10 2005</I> +using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A> +</FONT> + +</BODY> +</HTML> |