/usr/share/doc/slib/slib

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- This manual is for SLIB (version 3b1, February 2008),
the portable Scheme library.

Copyright C 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled "GNU Free
Documentation License."

 -->
<!-- Created on a rainy day by texi2html 1.82
texi2html was 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.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>slib: 1. The Library System</title>

<meta name="description" content="slib: 1. The Library System">
<meta name="keywords" content="slib: 1. The Library System">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="The-Library-System"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="slib.html#Top" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Feature" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-Library-System-1"></a>
<h1 class="chapter">1. The Library System</h1>

<p><em>SLIB</em> is a portable library for the programming language
<em>Scheme</em>.  It provides a platform independent framework for using
<em>packages</em> 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.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Feature">1.1 Feature</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                     SLIB names.
</td></tr>
<tr><td align="left" valign="top"><a href="#Require">1.2 Require</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                     
</td></tr>
<tr><td align="left" valign="top"><a href="#Library-Catalogs">1.3 Library Catalogs</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">            
</td></tr>
<tr><td align="left" valign="top"><a href="#Catalog-Creation">1.4 Catalog Creation</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">            
</td></tr>
<tr><td align="left" valign="top"><a href="#Catalog-Vicinities">1.5 Catalog Vicinities</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">          
</td></tr>
<tr><td align="left" valign="top"><a href="#Compiling-Scheme">1.6 Compiling Scheme</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">            
</td></tr>
</table>


<hr size="6">
<a name="Feature"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#The-Library-System" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Require" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Feature-1"></a>
<h2 class="section">1.1 Feature</h2>

<a name="index-feature"></a>
<p>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="index-session"></a>
provided by a session may change during that session.  Some features
are properties of the Scheme implementation being used.  The following
<a name="index-intrinsic-feature"></a>
<em>intrinsic feature</em>s detail what sort of numbers are available
from an implementation:
</p>
<a name="index-inexact"></a>
<a name="index-rational"></a>
<a name="index-real"></a>
<a name="index-complex"></a>
<a name="index-bignum"></a>

<ul>
<li>
&rsquo;inexact
</li><li>
&rsquo;rational
</li><li>
&rsquo;real
</li><li>
&rsquo;complex
</li><li>
&rsquo;bignum
</li></ul>

<p>SLIB initialization (in &lsquo;<tt>require.scm</tt>&rsquo;) 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>
<dl>
<dt><a name="index-provided_003f"></a><u>Function:</u> <b>provided?</b><i> feature</i></dt>
<dd><p>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>, the <code>scheme-implementation-type</code>
<a name="DOCF1" href="slib_fot.html#FOOT1">(1)</a>, or if <var>feature</var> has been provided by a module already
loaded; and <code>#f</code> otherwise.
</p>
<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></dd></dl>

<p>The generalization of <code>provided?</code> for arbitrary features and catalog
is <code>feature-eval</code>:
</p>
<dl>
<dt><a name="index-feature_002deval"></a><u>Function:</u> <b>feature-eval</b><i> expression provided?</i></dt>
<dd><p>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.
</p></dd></dl>

<dl>
<dt><a name="index-provide"></a><u>Procedure:</u> <b>provide</b><i> feature</i></dt>
<dd><p>Informs SLIB that <var>feature</var> is supported in this session.
</p></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(provided? 'foo)    &rArr; #f
(provide 'foo)
(provided? 'foo)    &rArr; #t
</pre></td></tr></table>



<hr size="6">
<a name="Require"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Feature" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Library-Catalogs" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Require-1"></a>
<h2 class="section">1.2 Require</h2>

<a name="index-catalog"></a>
<p>SLIB creates and maintains a <em>catalog</em> mapping features to locations
of files introducing procedures and syntax denoted by those features.
</p>
<dl>
<dt><a name="index-_002acatalog_002a"></a><u>Variable:</u> <b>*catalog*</b></dt>
<dd><p>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="#Library-Catalogs">Library Catalogs</a>.  The cdr of the pathname should
be either a string or a list.
</p></dd></dl>

<p>At the beginning of each section of this manual, there is a line like
<code>(require '<var>feature</var>)</code>.
<a name="index-feature-1"></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>
<dl>
<dt><a name="index-require"></a><u>Procedure:</u> <b>require</b><i> feature</i></dt>
<dd><ul>
<li>
If <code>(provided? <var>feature</var>)</code> is true,
then <code>require</code> just returns.
</li><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><li>
Otherwise (<var>feature</var> not found in the catalog), an error is
signaled.
</li></ul>
</dd></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>
<dl>
<dt><a name="index-require_002dif"></a><u>Procedure:</u> <b>require-if</b><i> condition feature</i></dt>
<dd>
<p>Requires <var>feature</var> if <var>condition</var> is true.
</p></dd></dl>

<p>The <code>random</code> module uses <code>require-if</code> to flag
<code>object-&gt;string</code> as a (dynamic) required module.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(require 'byte)
(require 'logical)
(require-if 'compiling 'object-&gt;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>
<table><tr><td>&nbsp;</td><td><pre class="example">(require-if '(and bignum compiling) 'posix-time)
</pre></td></tr></table>

<p>The catalog can also be queried using <code>slib:in-catalog?</code>.
</p>
<dl>
<dt><a name="index-slib_003ain_002dcatalog_003f"></a><u>Function:</u> <b>slib:in-catalog?</b><i> feature</i></dt>
<dd><p>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="#Library-Catalogs">Library Catalogs</a>.
</p></dd></dl>


<hr size="6">
<a name="Library-Catalogs"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Require" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Catalog-Creation" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Library-Catalogs-1"></a>
<h2 class="section">1.3 Library Catalogs</h2>

<p>Catalog files consist of one or more <em>association list</em>s.
<a name="index-Catalog-File"></a>
In the circumstance where a feature symbol appears in more than one
list, the latter list&rsquo;s association is retrieved.  Here are the
supported formats for elements of catalog lists:
</p>
<dl compact="compact">
<dt> <code>(<var>feature</var> . <i>&lt;symbol&gt;</i>)</code></dt>
<dd><p>Redirects to the feature named <i>&lt;symbol&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> . &quot;<i>&lt;path&gt;</i>&quot;)</code></dt>
<dd><p>Loads file <i>&lt;path&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> source &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-source"></a>
<p><code>slib:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> compiled &quot;<i>&lt;path&gt;&quot;</i> &hellip;)</code></dt>
<dd><a name="index-compiled"></a>
<p><code>slib:load-compiled</code>s the files <i>&lt;path&gt;</i> &hellip;.
</p></dd>
<dt> <code>(<var>feature</var> aggregate <i>&lt;symbol&gt;</i> &hellip;)</code></dt>
<dd><a name="index-aggregate"></a>
<p><code>require</code>s the features <i>&lt;symbol&gt;</i> &hellip;.
</p></dd>
</dl>

<p>The various macro styles first <code>require</code> the named macro package,
then just load <i>&lt;path&gt;</i> or load-and-macro-expand <i>&lt;path&gt;</i> as
appropriate for the implementation.
</p>
<dl compact="compact">
<dt> <code>(<var>feature</var> defmacro &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-defmacro"></a>
<p><code>defmacro:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> macro-by-example &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-macro_002dby_002dexample"></a>
<p><code>defmacro:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
</dl>

<dl compact="compact">
<dt> <code>(<var>feature</var> macro &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-macro"></a>
<p><code>macro:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> macros-that-work &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-macros_002dthat_002dwork"></a>
<p><code>macro:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> syntax-case &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-syntax_002dcase"></a>
<p><code>macro:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
<dt> <code>(<var>feature</var> syntactic-closures &quot;<i>&lt;path&gt;&quot;</i>)</code></dt>
<dd><a name="index-syntactic_002dclosures"></a>
<p><code>macro:load</code>s the Scheme source file <i>&lt;path&gt;</i>.
</p></dd>
</dl>

<p>Note that file names indicated as <i>&lt;path&gt;</i> may have &ldquo;.scm&rdquo; or
another suffix appended to them, depending on the specific Scheme
system you are using.
</p>

<hr size="6">
<a name="Catalog-Creation"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Library-Catalogs" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Catalog-Vicinities" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Catalog-Creation-1"></a>
<h2 class="section">1.4 Catalog Creation</h2>

<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>
<ul>
<li>
standard SLIB packages.
</li><li>
additional packages of interest to this site.
</li><li>
packages specifically for the variety of Scheme which this
session is running.
</li><li>
packages this user wants to always have available.  This catalog is the
file &lsquo;<tt>homecat</tt>&rsquo; in the user&rsquo;s <em>HOME</em> directory.
<a name="index-HOME"></a>
</li><li>
packages germane to working in this (current working) directory.  This
catalog is the file &lsquo;<tt>usercat</tt>&rsquo; in the directory to which it applies.
One would typically <code>cd</code> to this directory before starting the
Scheme session.
</li><li>
packages which are part of an application program.
</li></ul>

<p>SLIB combines the catalog information which doesn&rsquo;t vary per user into
the file &lsquo;<tt>slibcat</tt>&rsquo; in the implementation-vicinity.  Therefore
&lsquo;<tt>slibcat</tt>&rsquo; 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
&lsquo;<tt>require.scm</tt>&rsquo; 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
&lsquo;<tt>slibcat</tt>&rsquo; will update only that implementation&rsquo;s catalog.
</p>
<p>The compilation scripts of Scheme implementations which work with SLIB
can automatically trigger catalog compilation by deleting
&lsquo;<tt>slibcat</tt>&rsquo; or by invoking <code>require</code> of a special feature:
</p>
<dl>
<dt><a name="index-require-1"></a><u>Procedure:</u> <b>require</b><i> <span class="roman">'new-catalog</span></i></dt>
<dd><a name="index-new_002dcatalog"></a>
<p>This will load &lsquo;<tt>mklibcat</tt>&rsquo;, which compiles and writes a new
&lsquo;<tt>slibcat</tt>&rsquo;.
</p></dd></dl>

<p>Another special feature of <code>require</code> erases SLIB&rsquo;s catalog,
forcing it to be reloaded the next time the catalog is queried.
</p>
<dl>
<dt><a name="index-require-2"></a><u>Procedure:</u> <b>require</b><i> <span class="roman">#f</span></i></dt>
<dd><p>Removes SLIB&rsquo;s catalog information.  This should be done before saving
an executable image so that, when restored, its catalog will be loaded
afresh.
</p></dd></dl>


<hr size="6">
<a name="Catalog-Vicinities"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Catalog-Creation" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Catalog-Vicinities-1"></a>
<h2 class="section">1.5 Catalog Vicinities</h2>

<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#Vicinity">Vicinity</a>).  The entries
of a catalog in the table override those of catalogs above it in the
table.
</p>
<dl compact="compact">
<dt> <code>implementation-vicinity</code> &lsquo;<tt>slibcat</tt>&rsquo;</dt>
<dd><a name="index-slibcat"></a>
<p>This file contains the associations for the packages comprising SLIB,
the &lsquo;<tt>implcat</tt>&rsquo; and the &lsquo;<tt>sitecat</tt>&rsquo;s.  The associations in the
other catalogs override those of the standard catalog.
</p>
</dd>
<dt> <code>library-vicinity</code> &lsquo;<tt>mklibcat.scm</tt>&rsquo;</dt>
<dd><a name="index-mklibcat_002escm"></a>
<p>creates &lsquo;<tt>slibcat</tt>&rsquo;.
</p>
</dd>
<dt> <code>library-vicinity</code> &lsquo;<tt>sitecat</tt>&rsquo;</dt>
<dd><a name="index-sitecat"></a>
<p>This file contains the associations specific to an SLIB installation.
</p>
</dd>
<dt> <code>implementation-vicinity</code> &lsquo;<tt>implcat</tt>&rsquo;</dt>
<dd><a name="index-implcat"></a>
<p>This file contains the associations specific to an implementation of
Scheme.  Different implementations of Scheme should have different
<code>implementation-vicinity</code>.
</p>
</dd>
<dt> <code>implementation-vicinity</code> &lsquo;<tt>mkimpcat.scm</tt>&rsquo;</dt>
<dd><a name="index-mkimpcat_002escm"></a>
<p>if present, creates &lsquo;<tt>implcat</tt>&rsquo;.
</p>
</dd>
<dt> <code>implementation-vicinity</code> &lsquo;<tt>sitecat</tt>&rsquo;</dt>
<dd><a name="index-sitecat-1"></a>
<p>This file contains the associations specific to a Scheme implementation
installation.
</p>
</dd>
<dt> <code>home-vicinity</code> &lsquo;<tt>homecat</tt>&rsquo;</dt>
<dd><a name="index-homecat"></a>
<p>This file contains the associations specific to an SLIB user.
</p>
</dd>
<dt> <code>user-vicinity</code> &lsquo;<tt>usercat</tt>&rsquo;</dt>
<dd><a name="index-usercat"></a>
<p>This file contains associations affecting only those sessions whose
<em>working directory</em> is <code>user-vicinity</code>.
</p>
</dd>
</dl>

<p>Here is an example of a &lsquo;<tt>usercat</tt>&rsquo; catalog.  A program in this
directory can invoke the &lsquo;<samp>run</samp>&rsquo; feature with <code>(require 'run)</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">;;; &quot;usercat&quot;: SLIB catalog additions for SIMSYNCH.     -*-scheme-*-
(
 (simsynch      . &quot;../synch/simsynch.scm&quot;)
 (run           . &quot;../synch/run.scm&quot;)
 (schlep        . &quot;schlep.scm&quot;)
)
</pre></td></tr></table>

<p>Copying &lsquo;<tt>usercat</tt>&rsquo; to many directories is inconvenient.
Application programs which aren&rsquo;t always run in specially prepared
directories can nonetheless register their features during
initialization.
</p>
<dl>
<dt><a name="index-catalog_003aread"></a><u>Procedure:</u> <b>catalog:read</b><i> vicinity catalog</i></dt>
<dd><p>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>
<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>
<table><tr><td>&nbsp;</td><td><pre class="example">(catalog:read (program-vicinity) &quot;jacalcat&quot;)
</pre></td></tr></table>

</dd></dl>

<p>For an application program there are three appropriate venues for
registering its catalog associations:
</p>
<ul>
<li>
in a &lsquo;<tt>usercat</tt>&rsquo; file in the directory where the program runs; or
</li><li>
in an &lsquo;<tt>implcat</tt>&rsquo; file in the <code>implementation-vicinity</code>; or
</li><li>
in an application program directory; loaded by calling
<code>catalog:read</code>.
</li></ul>


<hr size="6">
<a name="Compiling-Scheme"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Catalog-Vicinities" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Module-Conventions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Compiling-Scheme-1"></a>
<h2 class="section">1.6 Compiling Scheme</h2>

<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>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Module-Conventions">1.6.1 Module Conventions</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">          
</td></tr>
<tr><td align="left" valign="top"><a href="#Module-Manifests">1.6.2 Module Manifests</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">            
</td></tr>
<tr><td align="left" valign="top"><a href="#Module-Semantics">1.6.3 Module Semantics</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">            
</td></tr>
<tr><td align="left" valign="top"><a href="#Top_002dlevel-Variable-References">1.6.4 Top-level Variable References</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
<tr><td align="left" valign="top"><a href="#Module-Analysis">1.6.5 Module Analysis</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">             
</td></tr>
</table>

<hr size="6">
<a name="Module-Conventions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Module-Manifests" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Module-Conventions-1"></a>
<h3 class="subsection">1.6.1 Module Conventions</h3>

<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><li>
Any conditionally <code>require</code>d SLIB modules
<a name="DOCF2" href="slib_fot.html#FOOT2">(2)</a>
also appear at the beginning of their files conditioned on the feature
<a name="index-compiling"></a>
<code>compiling</code> using <code>require-if</code>
(see section <a href="#Require">require-if</a>).

<table><tr><td>&nbsp;</td><td><pre class="example">(require 'logical)
(require 'multiarg/and-)
(require-if 'compiling 'sort)
(require-if 'compiling 'ciexyz)
</pre></td></tr></table>

</li><li>
Schmooz-style comments preceding a definition, identify that
definition as an exported identifier (see section <a href="slib_4.html#Schmooz">Schmooz</a>).  For
non-schmooz files, putting &lsquo;<samp>;@</samp>&rsquo; at the beginning of the line
immediately preceding the definition (<code>define</code>,
<code>define-syntax</code>, or <code>defmacro</code>) suffices.

<table><tr><td>&nbsp;</td><td><pre class="example">;@
(define (identity &lt;obj&gt;) &lt;obj&gt;)
</pre></td></tr></table>

</li><li>
Syntax (macro) definitions are grouped at the end of a module file.

</li><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>
<table><tr><td>&nbsp;</td><td><pre class="example">(require 'macros-that-work)
(require 'yasos)
(require 'pprint-file)
(pprint-filter-file &quot;collect.scm&quot; macwork:expand)
</pre></td></tr></table>

</li></ul>


<hr size="6">
<a name="Module-Manifests"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Module-Conventions" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Module-Semantics" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Module-Manifests-1"></a>
<h3 class="subsection">1.6.2 Module Manifests</h3>

<p><code>(require 'manifest)</code>
<a name="index-manifest"></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>
<table><tr><td>&nbsp;</td><td><pre class="example">(define slib:catalog (cdr (member (assq 'null *catalog*) *catalog*)))
</pre></td></tr></table>


<dl>
<dt><a name="index-file_002d_003erequires"></a><u>Function:</u> <b>file-&gt;requires</b><i> file provided? catalog</i></dt>
<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></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(define (provided+? . features)
  (lambda (feature)
    (or (memq feature features) (provided? feature))))

(file-&gt;requires &quot;obj2str.scm&quot; (provided+? 'compiling) '())
        &rArr; (string-port generic-write)

(file-&gt;requires &quot;obj2str.scm&quot; provided? '())
        &rArr; (string-port)
</pre></td></tr></table>


<dl>
<dt><a name="index-feature_002d_003erequires"></a><u>Function:</u> <b>feature-&gt;requires</b><i> feature provided? catalog</i></dt>
<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></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(feature-&gt;requires 'batch (provided+? 'compiling) *catalog*)
        &rArr; (tree line-i/o databases parameters string-port
                   pretty-print common-list-functions posix-time)

(feature-&gt;requires 'batch provided? *catalog*)
        &rArr; (tree line-i/o databases parameters string-port
                   pretty-print common-list-functions)

(feature-&gt;requires 'batch provided? '((batch . &quot;batch&quot;)))
        &rArr; (tree line-i/o databases parameters string-port
                   pretty-print common-list-functions)
</pre></td></tr></table>


<dl>
<dt><a name="index-feature_002d_003erequires_002a"></a><u>Function:</u> <b>feature-&gt;requires*</b><i> feature provided? catalog</i></dt>
<dd>
<p>Returns a list of the features transitively <code>require</code>d by <var>feature</var>
assuming the predicate <var>provided?</var> and association-list <var>catalog</var>.
</p></dd></dl>


<dl>
<dt><a name="index-file_002d_003erequires_002a"></a><u>Function:</u> <b>file-&gt;requires*</b><i> file provided? catalog</i></dt>
<dd>
<p>Returns a list of the features transitively <code>require</code>d by <var>file</var>
assuming the predicate <var>provided?</var> and association-list <var>catalog</var>.
</p></dd></dl>


<dl>
<dt><a name="index-file_002d_003eloads"></a><u>Function:</u> <b>file-&gt;loads</b><i> file</i></dt>
<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></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(file-&gt;loads (in-vicinity (library-vicinity) &quot;scainit.scm&quot;))
        &rArr; (&quot;/usr/local/lib/slib/scaexpp.scm&quot;
            &quot;/usr/local/lib/slib/scaglob.scm&quot;
            &quot;/usr/local/lib/slib/scaoutp.scm&quot;)
</pre></td></tr></table>


<dl>
<dt><a name="index-load_002d_003epath"></a><u>Function:</u> <b>load-&gt;path</b><i> exp</i></dt>
<dd>
<p>Given a <code>(load '&lt;expr&gt;)</code>, where &lt;expr&gt; is a string or vicinity
stuff), <code>(load-&gt;path &lt;expr&gt;)</code> figures a path to the file.
<code>load-&gt;path</code> returns that path if it names an existing file; otherwise #f.
</p></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(load-&gt;path '(in-vicinity (library-vicinity) &quot;mklibcat&quot;))
        &rArr; &quot;/usr/local/lib/slib/mklibcat.scm&quot;
</pre></td></tr></table>


<dl>
<dt><a name="index-file_002d_003edefinitions"></a><u>Function:</u> <b>file-&gt;definitions</b><i> file definer &hellip;</i></dt>
<dd>
<p>Returns a list of the identifier symbols defined by SLIB (or
SLIB-style) file <var>file</var>.  The optional arguments <var>definers</var> should be symbols
signifying a defining form.  If none are supplied, then the symbols
<code>define-operation</code>, <code>define</code>, <code>define-syntax</code>, and
<code>defmacro</code> are captured.
</p></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(file-&gt;definitions &quot;random.scm&quot;)
        &rArr; (*random-state* make-random-state
           seed-&gt;random-state copy-random-state random
           random:chunk)
</pre></td></tr></table>


<dl>
<dt><a name="index-file_002d_003eexports"></a><u>Function:</u> <b>file-&gt;exports</b><i> file definer &hellip;</i></dt>
<dd>
<p>Returns a list of the identifier symbols exported (advertised) by
SLIB (or SLIB-style) file <var>file</var>.  The optional arguments <var>definers</var> should be
symbols signifying a defining form.  If none are supplied, then the
symbols <code>define-operation</code>, <code>define</code>,
<code>define-syntax</code>, and <code>defmacro</code> are captured.
</p></dd></dl>

<table><tr><td>&nbsp;</td><td><pre class="example">(file-&gt;exports &quot;random.scm&quot;)
        &rArr; (make-random-state seed-&gt;random-state
            copy-random-state random)

(file-&gt;exports &quot;randinex.scm&quot;)
        &rArr; (random:solid-sphere! random:hollow-sphere!
            random:normal-vector! random:normal
            random:exp random:uniform)
</pre></td></tr></table>


<dl>
<dt><a name="index-feature_002d_003eexport_002dalist"></a><u>Function:</u> <b>feature-&gt;export-alist</b><i> feature catalog</i></dt>
<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></dd></dl>


<dl>
<dt><a name="index-feature_002d_003eexports"></a><u>Function:</u> <b>feature-&gt;exports</b><i> feature catalog</i></dt>
<dd>
<p>Returns a list of all exports of <var>feature</var>.
</p></dd></dl>

<p>In the case of <code>aggregate</code> features, more than one file may
have export lists to report:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(feature-&gt;export-alist 'r5rs slib:catalog))
        &rArr; ((&quot;/usr/local/lib/slib/values.scm&quot;
             call-with-values values)
            (&quot;/usr/local/lib/slib/mbe.scm&quot;
             define-syntax macro:expand
             macro:load macro:eval)
            (&quot;/usr/local/lib/slib/eval.scm&quot;
             eval scheme-report-environment
             null-environment interaction-environment))

(feature-&gt;export-alist 'stdio *catalog*)
        &rArr; ((&quot;/usr/local/lib/slib/scanf.scm&quot;
             fscanf sscanf scanf scanf-read-list)
            (&quot;/usr/local/lib/slib/printf.scm&quot;
             sprintf printf fprintf)
            (&quot;/usr/local/lib/slib/stdio.scm&quot;
             stderr stdout stdin))

(feature-&gt;exports 'stdio slib:catalog)
        &rArr; (fscanf sscanf scanf scanf-read-list
             sprintf printf fprintf stderr stdout stdin)
</pre></td></tr></table>


<hr size="6">
<a name="Module-Semantics"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Module-Manifests" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Top_002dlevel-Variable-References" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Module-Semantics-1"></a>
<h3 class="subsection">1.6.3 Module Semantics</h3>

<p>For the purpose of compiling Scheme code, each top-level
<code>require</code> makes the identifiers exported by its feature&rsquo;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>
<a name="index-aggregate-1"></a>
<p>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="#Feature">feature-eval</a>).  The simplest way to compile these
constructs may be to treat <code>provided?</code> as a macro.
</p>

<hr size="6">
<a name="Top_002dlevel-Variable-References"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Module-Semantics" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Module-Analysis" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Top_002dlevel-Variable-References-1"></a>
<h3 class="subsection">1.6.4 Top-level Variable References</h3>

<p><code>(require 'top-refs)</code>
<a name="index-top_002drefs"></a>
<a name="index-top_002dlevel-variable-references"></a>
<a name="index-variable-references"></a>
</p>
<p>These procedures complement those in <a href="#Module-Manifests">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>

<dl>
<dt><a name="index-top_002drefs-1"></a><u>Function:</u> <b>top-refs</b><i> obj</i></dt>
<dd>
<p>Returns a list of the top-level variables referenced by the Scheme
expression <var>obj</var>.
</p></dd></dl>


<dl>
<dt><a name="index-top_002drefs_003c_002dfile"></a><u>Function:</u> <b>top-refs&lt;-file</b><i> filename</i></dt>
<dd>
<p><var>filename</var> should be a string naming an existing file containing Scheme
source code.  <code>top-refs&lt;-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 &quot;.scm&quot; appended).
</p></dd></dl>

<p>The following function parses an <em>Info</em> Index.
<a name="index-Info"></a>
<a name="DOCF3" href="slib_fot.html#FOOT3">(3)</a>
</p>

<dl>
<dt><a name="index-exports_003c_002dinfo_002dindex"></a><u>Function:</u> <b>exports&lt;-info-index</b><i> file n &hellip;</i></dt>
<dd>
<p><var>n</var> &hellip; must be an increasing series of positive integers.
<code>exports&lt;-info-index</code> returns a list of all the identifiers appearing in the <var>n</var>th
&hellip; (info) indexes of <var>file</var>.  The identifiers have the case that
the implementation&rsquo;s <code>read</code> uses for symbols.  Identifiers
containing spaces (eg. <code>close-base on base-table</code>) are
<em>not</em> included.  #f is returned if the index is not found.
</p>
<p>Each info index is headed by a &lsquo;<samp>* Menu:</samp>&rsquo; line.  To list the
symbols in the first and third info indexes do:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(exports&lt;-info-index &quot;slib.info&quot; 1 3)
</pre></td></tr></table>
</dd></dl>



<hr size="6">
<a name="Module-Analysis"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Top_002dlevel-Variable-References" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Compiling-Scheme" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Module-Analysis-1"></a>
<h3 class="subsection">1.6.5 Module Analysis</h3>

<p><code>(require 'vet)</code>
<a name="index-vet"></a>
</p>

<dl>
<dt><a name="index-vet_002dslib"></a><u>Function:</u> <b>vet-slib</b><i> file1 &hellip;</i></dt>
<dd>
<p>Using the procedures in the <code>top-refs</code> and <code>manifest</code>
modules, <code>vet-slib</code> analyzes each SLIB module and <var>file1</var>, &hellip;, reporting
about any procedure or macro defined whether it is:
</p>
<dl compact="compact">
<dt> orphaned</dt>
<dd><p>defined, not called, not exported;
</p></dd>
<dt> missing</dt>
<dd><p>called, not defined, and not exported by its <code>require</code>d modules;
</p></dd>
<dt> undocumented-export</dt>
<dd><p>Exported by module, but no index entry in &lsquo;<tt>slib.info</tt>&rsquo;;
</p>
</dd>
</dl>

<p>And for the library as a whole:
</p>
<dl compact="compact">
<dt> documented-unexport</dt>
<dd><p>Index entry in &lsquo;<tt>slib.info</tt>&rsquo;, but no module exports it.
</p>
</dd>
</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>
<p>The optional arguments <var>file1</var>, &hellip; provide a simple way to vet
prospective SLIB modules.
</p></dd></dl>



<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#The-Library-System" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="slib_2.html#Universal-SLIB-Procedures" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="slib.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="slib_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="slib_10.html#Procedure-and-Macro-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="slib_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated on <i>a rainy day</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
 </font>
 <br>

</p>
</body>
</html>
slib 3b1-5 / usr / share / doc / slib / slib_1.html
