chez-openbsd/csug/libraries.stex

% Copyright 2005-2017 Cisco Systems, Inc.
% 
% Licensed under the Apache License, Version 2.0 (the "License");
% you may not use this file except in compliance with the License.
% You may obtain a copy of the License at
% 
% http://www.apache.org/licenses/LICENSE-2.0
% 
% Unless required by applicable law or agreed to in writing, software
% distributed under the License is distributed on an "AS IS" BASIS,
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
% See the License for the specific language governing permissions and
% limitations under the License.
\chapter{Libraries and Top-level Programs\label{CHPTLIBRARIES}}

\index{libraries}%
\index{top-level-programs}%
The Revised$^6$ Report describes two units of portable code:
libraries and top-level programs.
A library is a named collection of bindings with a declared set of
explicitly exported bindings, a declared set of imported libraries, and a
body that initializes its bindings.
A top-level program is a stand-alone program with a declared set of
imported libraries and a body that is run when the top-level program is
run.
The bindings in a library are created and its initialization code run only
if the library is used, directly or indirectly, by a top-level program.

\index{\scheme{import}}%
The \scheme{import} declarations appearing within libraries and top-level
programs serve two purposes:  first, they cause the imported libraries to
be loaded, and second, they cause the bindings of the imported libraries
to become visible in the importing library or top-level program.
Libraries are typically stored in the file system, with one library per
file, and the library name typically identifies the file-system path to
the library, possibly relative to a default or programmer-specified set of
library locations.
The exact mechanism by which top-level programs are run and libraries are
loaded is implementation-dependent.

This chapter describes the mechanisms by which libraries and programs are
loaded in {\ChezScheme} along with various features for controlling and
tracking this process.
It also describes the set of built-in libraries and syntactic forms for
defining new libraries and top-level programs outside of a library or
top-level program file.

% \section{Locating Libraries\label{SECTLOCATINGLIBRARIES}}
% 
% In {\ChezScheme}, a library to be loaded implicitly by \scheme{import}
% must reside in a file whose name reflects the name of the library.
% For example, if the library's name is \scheme{(tools sorting)}, the
% base name of the file must be \scheme{sorting} with a valid extension, and
% the file must be in a directory named \scheme{tools} which itself resides
% in one of the directories searched by \scheme{import}.
% The set of directories searched by \scheme{import} is determined by
% the
% \index{\scheme{library-directories}}\scheme{library-directories}
% parameter, and the set of
% extensions is determined by the
% \index{\scheme{library-extensions}}\scheme{library-extensions}
% parameter.
% So, if \scheme{(library-directories)} contains the pathnames
% \scheme{"/usr/lib/scheme/libraries"} and \scheme{"."}, and
% \scheme{(library-extensions)} contains the extensions \scheme{.ss}
% and \scheme{.sls}, the path of the \scheme{(tools sorting)}
% library must be one of the following.
% 
% \schemedisplay
% /usr/lib/scheme/libraries/tools/sorting.ss
% /usr/lib/scheme/libraries/tools/sorting.sls
% ./tools/sorting.ss
% ./tools/sorting.sls
% \endschemedisplay
% 
% A file containing a library or set of libraries can be explicitly loaded
% via \scheme{load}, in which case the file may have any name and may reside
% anywhere in the file system.
% 
% \index{\scheme{compile-library}}%
% \index{\scheme{compile-imported-libraries}}%
% A file containing a library may be compiled with \scheme{compile-file}
% or \scheme{compile-library}.
% The only difference between the two is that the latter treats the source
% file as if it were prefixed by an implicit \scheme{#!r6rs}.
% Any libraries upon which the library depends must be compiled first.
% This can be done manually or by setting the parameter
% \scheme{compile-imported-libraries} to \scheme{#t} before compiling
% the importing library.
% If one of the libraries imported by the library is subsequently
% recompiled (say because it was modified), the importing library must also
% be recompiled.


\section{Built-in Libraries\label{SECTBUILTINLIBRARIES}}

In addition to the RNRS libraries mandated by the Revised$^6$ Report:

\schemedisplay
  (rnrs base (6))
  (rnrs arithmetic bitwise (6))
  (rnrs arithmetic fixnums (6))
  (rnrs arithmetic flonums (6))
  (rnrs bytevectors (6))
  (rnrs conditions (6))
  (rnrs control (6))
  (rnrs enums (6))
  (rnrs eval (6))
  (rnrs exceptions (6))
  (rnrs files (6))
  (rnrs hashtables (6))
  (rnrs io ports (6))
  (rnrs io simple (6))
  (rnrs lists (6))
  (rnrs mutable-pairs (6))
  (rnrs mutable-strings (6))
  (rnrs programs (6))
  (rnrs r5rs (6))
  (rnrs records procedural (6))
  (rnrs records syntactic (6))
  (rnrs records inspection (6))
  (rnrs sorting (6))
  (rnrs syntax-case (6))
  (rnrs unicode (6))
\endschemedisplay

\index{\scheme{(chezscheme)} library}%
\index{\scheme{(chezscheme csv7)} library}%
\index{\scheme{(scheme)} library}%
\index{\scheme{(scheme csv7)} library}%
{\ChezScheme} also provides two additional libraries: \scheme{(chezscheme)}
and \scheme{(chezscheme csv7)}.
The former can also be referenced as \scheme{(scheme)} and the latter can
also be referenced as \scheme{(scheme csv7)}.

The \scheme{(chezscheme)} library exports bindings for every identifier whose
binding is described in this document, including those for keywords like
\scheme{lambda}, auxiliary keywords like \scheme{else}, module names
like \scheme{scheme}, and procedure names like \scheme{cons}.
In most cases where an identifier exported from the
\scheme{(chezscheme)} library corresponds to an identifier exported from
one of the RNRS libraries, the bindings are identical.
In some cases, however, the \scheme{(chezscheme)} bindings extend the
\scheme{rnrs} bindings in some way.
For example, the \scheme{(chezscheme)} \scheme{syntax-rules} form allows
its clauses to have fenders (Section~\ref{SECTSYNTAXRULES}), while the
\scheme{(rnrs)} \scheme{syntax-rules} form does not.
Similarly, the \scheme{(chezscheme)} \scheme{current-input-port} procedure
accepts an optional \var{port} argument that, when specified, sets the
current input port to \var{port} (Section~\ref{SECTIOINPUT}), while the
\scheme{(rnrs)} \scheme{current-input-port} procedure does not.
When the \scheme{(chezscheme)} library extends an RNRS binding in some
way, the \scheme{(chezscheme)} library also exports the RNRS version,
with the name prefixed by \scheme{r6rs:}, e.g., \scheme{r6rs:syntax-rules}
or \scheme{r6rs:current-input-port}.

The \scheme{(chezscheme csv7)} Version~7 backward compatibility library
contains bindings for a set of syntactic forms and procedures whose syntax
or semantics directly conflicts with the RNRS bindings for the same
identifiers.
The following identifiers are exported from \scheme{(chezscheme csv7)}.

\schemedisplay
record-field-accessible?
record-field-accessor
record-field-mutable?
record-field-mutator
record-type-descriptor
record-type-field-decls
record-type-field-names
record-type-name
record-type-symbol
\endschemedisplay

The bindings of this library should be used only for old code; new
code should use the RNRS variants.
Each of these is also available in the \scheme{(chezscheme)} library with
the prefix \scheme{csv7:}, e.g., \scheme{csv7:record-type-name}.

The interaction environment in which code outside of a library or
RNRS top-level program is scoped contains all of the bindings of the
\scheme{(chezscheme)} library, as described in
Section~\ref{SECTUSEINTERACTIONENVIRONMENT}.


\section{Running Top-level Programs\label{SECTRUNNINGTOPLEVELPROGRAMS}}

\index{\scheme{scheme-script}}%
\index{\scheme{--program} command-line option}%
\index{\scheme{load-program}}%
A top-level program must reside in its own file, which may have any
name and may reside anywhere in the file system.
A top-level program residing in a file is run by one of three mechanisms: 
the \scheme{scheme-script} command, the \scheme{--program} command-line
argument, or the \scheme{load-program} procedure.

The \scheme{scheme-script} command is used as follows:

\schemedisplay
scheme-script \var{program-filename} \var{arg} \dots
\endschemedisplay

It may also be run implicitly on Unix-based systems by placing the line

\schemedisplay
#! /usr/bin/env scheme-script
\endschemedisplay

at the front of the file containing the top-level program, making the
top-level program file executable, and executing the file.
This line may be replaced with

\schemedisplay
#! /usr/bin/scheme-script
\endschemedisplay

with \scheme{/usr/bin} replaced by the absolute path to the directory
containing \scheme{scheme-script} if it is not in \scheme{/usr/bin}.
The first form is recommended in the nonnormative appendices to the
Revised$^6$ Report~\cite{r6rsapps}, and works wherever
\scheme{scheme-script} appears in the path.

The \scheme{--program} command is used similarly with the \scheme{scheme}
or \scheme{petite} executables, either by running:

\schemedisplay
scheme --program \var{program-filename} \var{arg} \dots
petite --program \var{program-filename} \var{arg} \dots
\endschemedisplay

or by including

\schemedisplay
#! /usr/bin/scheme --script
\endschemedisplay

or

\schemedisplay
#! /usr/bin/petite --script
\endschemedisplay

at the front of the top-level program file, making the file executable,
and executing the file.
Again, \scheme{/usr/bin} should be replaced with the absolute path to
the actual directory in which \scheme{scheme} and/or \scheme{petite}
resides, if not \scheme{/usr/bin}.

The \scheme{load-program} procedure, described in
Section~\ref{SECTMISCCOMPILEEVAL}, is used like \scheme{load}:

\schemedisplay
(load-program \var{string})
\endschemedisplay

where \var{string} names the file in which the top-level program resides.

Regardless of the mechanism used, if the opening line is in one of the
forms described above, or more generally, consists of
\scheme{#!} followed by a space or a forward slash, the opening line
is not considered part of the program and is ignored once the Scheme
system starts up and begins to run the program.
Thus, the line may be present even in a file loaded by \scheme{load-program}.
In fact, \scheme{load-program} is ultimately used by the other two
mechanisms described above, via the value of the \scheme{scheme-program}
parameter described in Section~\ref{SECTMISCWAITERS}, and it is
\scheme{load-program} that scans past the \scheme{#!} line, if present,
before evaluating the program.

A top-level program may be compiled with the
\index{\scheme{compile-program}}\scheme{compile-program}
procedure described in Section~\ref{SECTMISCCOMPILEEVAL}.
\scheme{compile-program} copies the \scheme{#!} line from the source
file to the object file, followed by a compiled version of the source
code.
Any libraries upon which the top-level program depends, other than
built-in libraries, must be compiled first via \scheme{compile-file}
or \scheme{compile-library}.
This can be done manually or by setting the parameter
\scheme{compile-imported-libraries} to \scheme{#t} before compiling
the program.
The program must be recompiled if any of the libraries upon which
it depends are recompiled.
A compiled top-level program can be run just like a source top-level
program via each of the mechanisms described above.

\index{\scheme{load-library}}%
In {\ChezScheme}, a library may also be defined in the REPL or placed in a
file to be loaded via \scheme{load} or \scheme{load-library}.
The syntax for a library is the same whether the library is placed in
its own file and implicitly loaded via \scheme{import}, entered into
the REPL, or placed in a file along with other top-level expressions to
be evaluated by \scheme{load}.
A top-level program may also be defined in the REPL or placed in a file
to be loaded via \scheme{load}, but in this case, the syntax is slightly
different.
In the language of the Revised$^6$ Report, a top-level program is merely
an unwrapped sequence of subforms consisting of an \scheme{import} form
and a body, delimited only by the boundaries of the file in which it
resides.
In order for a top-level program to be entered in the REPL or placed in
a file to be evaluated by \scheme{load}, {\ChezScheme} allows top-level
programs to be enclosed in a
\index{\scheme{top-level-program}}\scheme{top-level-program} form.

\section{Library and Top-level Program Forms\label{SECTLIBRARYFORMS}}

%----------------------------------------------------------------------------
\noskipentryheader
\formdef{library}{\categorysyntax}{(library \var{name} \var{exports} \var{imports} \var{library-body})}
\returns unspecified
\listlibraries
\endnoskipentryheader

The \scheme{library} form defines a new library with the specified
name, exports, imports, and body.
Details on the syntax and semantics of the library form are given in
Section~\ref{TSPL:SECTLIBPROGRAMS} of {\TSPLFOUR} and in the Revised$^6$
Report.

Only one version of a library can be loaded at any given time, and an
exception is raised if a library is implicitly loaded via \scheme{import}
when another version of the library has already been loaded.
{\ChezScheme} permits a different version of the library, or a new
instance of the same version, to be entered explicitly into the REPL
or loaded explicitly from a file, to facilitate interactive testing
and debugging.
The programmer should take care to make sure that any code that uses
the library is also reentered or reloaded, to make sure that code
accesses the bindings of the new instance of the library.

\schemedisplay
(library (test (1)) (export x) (import (rnrs)) (define x 3))
(import (test))
(define f (lambda () x))
(f) ;=> 3

(library (test (1)) (export x) (import (rnrs)) (define x 4))
(import (test))
(f) ;=> 3    ; oops---forgot to redefine f
(define f (lambda () x))
(f) ;=> 4

(library (test (2)) (export x) (import (rnrs)) (define x 5))
(import (test))
(define f (lambda () x))
(f) ;=> 5
\endschemedisplay

As with module imports (Section~\ref{SECTSYNTAXMODULES}), a library
\scheme{import} may appear anywhere a definition may appear, including at
top level in the REPL, in a file to be loaded by \scheme{load}, or within
a \scheme{lambda}, \scheme{let}, \scheme{letrec}, \scheme{letrec*},
etc., body.
The same \scheme{import} form may be used to import from both libraries
and modules.

\schemedisplay
(library (foo) (export a) (import (rnrs)) (define a 'a-from-foo))
(module bar (b) (define b 'b-from-bar))
(let () (import (foo) bar) (list a b)) ;=> (a-from-foo b-from-bar)
\endschemedisplay

The \scheme{import} keyword is not visible within a library body
unless the library imports it from the \scheme{(chezscheme)} library.

%----------------------------------------------------------------------------
\entryheader
\formdef{top-level-program}{\categorysyntax}{(top-level-program \var{imports} \var{body})}
\returns unspecified
\listlibraries
\endentryheader

\index{top-level-programs}%
A \scheme{top-level-program} form may be entered into the REPL or placed
in a file to be loaded via \scheme{load}, where it behaves as if its
subforms were placed in a file and loaded via \scheme{load-program}.
Details on the syntax and semantics of a top-level program are given in
Section~\ref{TSPL:SECTLIBPROGRAMS} of {\TSPLFOUR} and in the Revised$^6$
Report.

The following transcript illustrates a \scheme{top-level-program} being
tested in the REPL.

\schemedisplay
> (top-level-program (import (rnrs))
    (display "hello!\n"))
hello!
\endschemedisplay

\section{Standalone import and export forms\label{SECTLIBRARYIMPORTEXPORTFORMS}}

Although not required by the Revised$^6$ Report,
{\ChezScheme} supports the use of standalone import and
export forms.
The import forms can appear anywhere other definitions
can appear, including within a \scheme{library} body,
\scheme{module} (Section~\ref{SECTSYNTAXMODULES}) body,
\scheme{lambda} or other local body, and at top level.
The export forms can appear within the definitions of a
\scheme{library} or \scheme{module} body to specify additional
exports for the library or module.

Within a library or top-level program, the keywords for
these forms must be imported from the \scheme{(chezscheme)}
library to be available for use, since they are not
defined in any of the Revised$^6$ Report libraries.

%----------------------------------------------------------------------------
\entryheader
\formdef{import}{\categorysyntax}{(import \var{import-spec} \dots)}
\formdef{import-only}{\categorysyntax}{(import-only \var{import-spec} \dots)}
\returns unspecified
\listlibraries
\endentryheader

An \scheme{import} or \scheme{import-only} form is a definition and can
appear anywhere other definitions can appear, including
at the top level of a program, nested within the bodies of
\scheme{lambda} expressions, and nested within modules
and libraries.

Each \var{import-spec} must take one of the following forms.

\schemedisplay
\var{import-set}
(for \var{import-set} \var{import-level} \dots)
\endschemedisplay

\noindent
The \scheme{for} wrapper and \var{import-level} are described in 
Chapter~\ref{TSPL:CHPTLIBRARIES} of {\TSPLFOUR}.
They are ignored by {\ChezScheme}, which determines
automatically the levels at which identifiers must
be imported, as permitted by the Revised$^6$ Report.
This frees the programmer from the obligation
to do so and results in more generality as well as more
precision in the set of libraries actually imported
at compile and run time~\cite{Ghuloum:libraries,Ghuloum:phd}.

An \var{import-set} must take one of the following forms:

\schemedisplay
\var{library-spec}
\var{module-name}
(only \var{import-set} \var{identifier} \dots)
(except \var{import-set} \var{identifier} \dots)
(prefix \var{import-set} \var{prefix})
(add-prefix \var{import-set} \var{prefix})
(drop-prefix \var{import-set} \var{prefix})
(rename \var{import-set} (\var{import-name} \var{internal-name}) \dots)
(alias \var{import-set} (\var{import-name} \var{internal-name}) \dots)
\endschemedisplay

Several of these are specified by the Revised$^6$ Report; the remainder
are {\ChezScheme} extensions, including \var{module-name} and the
\scheme{add-prefix}, \scheme{drop-prefix}, and \scheme{alias} forms.

An \scheme{import} or \scheme{import-only} form makes the specified bindings
visible in the scope in which they appear.
Except at top level, they differ in that \scheme{import} leaves all bindings
except for those shadowed by the imported names visible, whereas \scheme{import-only}
hides all existing bindings, i.e., makes only the imported names visible.
At top level, \scheme{import-only} behaves like \scheme{import}.

Each \var{import-set} identifies a set of names to make visible
as follows.

\begin{description}
\item[\scheme{\var{library-spec}}:]
all exports of the library identified by the Revised$^6$ Report \var{library-spec}
(Chapter~\ref{TSPL:CHPTLIBRARIES}).

\item[\scheme{\var{module-name}}:]
all exports of module named by the identifier \var{module-name}

\item[\scheme{(only \var{import-set} \var{identifier} \dots)}:]
of those specified by \var{import-set}, just \scheme{\var{identifier} \dots}

\item[\scheme{(except \var{import-set} \var{identifier} \dots)}:]
all specified by \var{import-set} except \scheme{\var{identifier} \dots}

\item[\scheme{(prefix \var{import-set} \var{prefix})}:]
all specified by \var{import-set}, each prefixed by \var{prefix}

\item[\scheme{(add-prefix \var{import-set} \var{prefix})}:]
all specified by \var{import-set}, each prefixed by \var{prefix}
(just like \scheme{prefix})

\item[\scheme{(drop-prefix \var{import-set} \var{prefix})}:]
all specified by \var{import-set}, with prefix \var{prefix} removed

\item[\scheme{(rename \var{import-set} (\var{import-name} \var{internal-name}) \dots)}:]
all specified by \var{import-set}, with each identifier \var{import-name}
renamed to the corresponding identifier \var{internal-name}

\item[\scheme{(alias \var{import-set} (\var{import-name} \var{internal-name}) \dots)}:]
all specified by \var{import-set}, with each \var{internal-name} as an alias
for \var{import-name}
\end{description}

The \scheme{alias} form differs from the \scheme{rename} form in that both
\var{import-name} and \var{internal-name} are in the resulting set,
rather than just \var{internal-name}.

It is a syntax violation if the
given selection or transformation cannot be made because of a missing
export or prefix.

An identifier made visible via an import of a module or library is scoped as if its
definition appears where the import occurs.
The following example illustrates these scoping rules, using a local
module \scheme{m}.

\schemedisplay
(library (A) (export x) (import (rnrs)) (define x 0))
(let ([x 1])
  (module m (x setter)
    (define-syntax x (identifier-syntax z))
    (define setter (lambda (x) (set! z x)))
    (define z 2))
  (let ([y x] [z 3])
    (import m (prefix (A) a:))
    (setter 4)
    (list x a:x y z))) ;=> (4 0 1 3)
\endschemedisplay

\noindent
The inner \scheme{let} expression binds \scheme{y} to the value of
the \scheme{x} bound by the outer \scheme{let}.
The import of \scheme{m} makes the definitions of \scheme{x}
and \scheme{setter} visible within the inner \scheme{let}.
The import of \scheme{(A)} makes the variable \scheme{x} exported
from \scheme{(A)} visible as \scheme{a:x} within the body of the
inner \scheme{let}.
Thus, in the expression \scheme{(list x a:x y z)}, \scheme{x} refers to the
identifier macro exported from \scheme{m} while \scheme{a:x} refers to the
variable \scheme{x} exported from \scheme{(A)} and \scheme{y} and \scheme{z}
refer to the bindings established by the inner \scheme{let}.
The identifier macro \scheme{x} expands into a reference to
the variable \scheme{z} defined within the module.

With local import forms, it is rarely necessary to use the extended
import specifiers.
For example, an abstraction that encapsulates the import and reference
can easily be defined and used as follows.

\schemedisplay
(define-syntax from
  (syntax-rules ()
    [(_ m id) (let () (import-only m) id)]))

(library (A) (export x) (import (rnrs)) (define x 1))
(let ([x 10])
  (module M (x) (define x 2))
  (cons (from (A) x) (from M x))) ;=> (1 . 2)
\endschemedisplay

\noindent
The definition of \scheme{from} could use \scheme{import} rather than
\scheme{import-only}, but by using \scheme{import-only} we get feedback
if an attempt is made to import an identifier from a library or
module that does not export the identifier.
With \scheme{import} instead of \scheme{import-only}, the current binding,
if any, would be visible if the library or module does not export the
specified name.

\schemedisplay
(define-syntax lax-from
  (syntax-rules ()
    [(_ m id) (let () (import m) id)]))

(library (A) (export x) (import (rnrs)) (define x 1))

(let ([x 10])
  (module M (x) (define x 2))
  (+ (from (A) x) (from M y))) ;=> \var{exception: unbound identifier y}
 
(let ([x 10] [y 20])
  (module M (x) (define x 2))
  (+ (lax-from (A) x) (lax-from M y))) ;=> 21
\endschemedisplay

Import visibility interacts with hygienic macro expansion in such a
way that, as one might expect,
an identifier \var{x} imported from a module \var{M} is treated in
the importing context as if the corresponding export identifier had
been present in the import form along with \var{M}.

The \scheme{from} abstraction above works because both \var{M} and \var{id}
appear in the input to the abstraction, so the imported \var{id} captures
the reference to \var{id}.

The following variant of \var{from} also works, because both names are
introduced into the output by the transformer.

\schemedisplay
(module M (x) (define x 'x-of-M))
(define-syntax x-from-M
  (syntax-rules ()
    [(_) (let () (import M) x)]))

(let ([x 'local-x]) (x-from-M)) ;=> x-of-M
\endschemedisplay

On the other hand, imports of introduced module names do not capture
free references.

\schemedisplay
(let ([x 'local-x])
  (define-syntax alpha
    (syntax-rules ()
      [(_ var) (let () (import M) (list x var))]))
 
  (alpha x)) ;=> (x-of-M local-x)
\endschemedisplay

Similarly, imports from free module names do not capture references
to introduced variables.

\schemedisplay
(let ([x 'local-x])
  (define-syntax beta
    (syntax-rules ()
      [(_ m var) (let () (import m) (list x var))]))

  (beta M x)) ;=> (local-x x-of-M)
\endschemedisplay

This semantics extends to prefixed, renamed, and aliased bindings
created by the extended \scheme{import} specifiers \scheme{prefix},
\scheme{rename}, and \scheme{alias}.

The \scheme{from} abstraction
works for variables but not for exported keywords, record names,
or module names, since the output is an expression and may thus appear only where
expressions may appear.
A generalization of this technique is used in the following definition
of \scheme{import*}, which supports renaming of imported bindings and
selective import of specific bindings---without the use of the built-in
\scheme{import} subforms for selecting and renaming identifiers

\schemedisplay
(define-syntax import*
  (syntax-rules ()
    [(_ m) (begin)]
    [(_ m (new old))
     (module (new)
       (module (tmp)
         (import m)
         (alias tmp old))
       (alias new tmp))]
    [(_ m id) (module (id) (import m))]
    [(_ m spec0 spec1 ...)
     (begin (import* m spec0) (import* m spec1 ...))]))
\endschemedisplay

\noindent
To selectively import an identifier from module or library \scheme{m}, the
\scheme{import*} form expands into an anonymous module that first
imports all exports of \scheme{m} then re-exports only the selected
identifier.
To rename on import the macro expands into an anonymous module that
instead exports an alias (Section~\ref{SECTSYNTAXALIAS}) bound to the new name.

If the output placed the definition of \scheme{new} in the same
scope as the import of \scheme{m}, a naming conflict would arise
whenever \scheme{new} is also present in the interface
of \scheme{m}.
To prevent this, the output instead places the import within a nested
anonymous module and links \scheme{old} and \scheme{new}
by means of an alias for the introduced identifier \scheme{tmp}.

The macro expands recursively to handle multiple import specifications.
Each of the following examples imports \scheme{cons} as \scheme{+} and \scheme{+} as
\scheme{cons}, which is probably not a very good idea.

\schemedisplay
(let ()
  (import* scheme (+ cons) (cons +))
  (+ (cons 1 2) (cons 3 4))) ;=> (3 . 7)

(let ()
  (import* (rnrs) (+ cons) (cons +))
  (+ (cons 1 2) (cons 3 4))) ;=> (3 . 7)
\endschemedisplay

% for testing
% (module m (x y z)
%    (define x 'x)
%    (define y 'y)
%    (define z 'z))

%----------------------------------------------------------------------------
\entryheader
\formdef{export}{\categorysyntax}{(export \var{export-spec} \dots)}
\returns unspecified
\listlibraries
\endentryheader

An \scheme{export} form is a definition and can appear with other
definitions at the front of a \scheme{library} or \scheme{module}.
It is a syntax error for an \scheme{export} form to appear in other
contexts, including at top level or among the definitions of a
top-level program or \scheme{lambda} body.

Each \var{export-spec} must take one of the following forms.

\schemedisplay
\var{identifier}
(rename (\var{internal-name} \var{export-name}) \dots)
(import \var{import-spec} \dots)
\endschemedisplay

\noindent
where each \var{internal-name} and \var{export-name} is an identifier.
The first two are syntactically identical to \scheme{library}
\var{export-spec}s, while the third is syntactically
identical to a {\ChezScheme} \scheme{import} form, which is an extension of the
R6RS library \scheme{import} subform.
The first form names a single export, \var{identifier}, whose export
name is the same as its internal name.
The second names a set of exports, each of whose export name is
given explicitly and may differ from its internal name.

For the third, the identifiers identified by the \scheme{import} form
become exports, with aliasing, renaming, prefixing, etc., as specified by the
\var{import-spec}s.
The module or library whose bindings are exported by an \scheme{import}
form appearing within an \scheme{export} form can
be defined within or outside the exporting module or library and need
not be imported elsewhere within the exporting module or library.

The following library exports a two-armed-only variant of \scheme{if}
along with all remaining bindings of the \scheme{(rnrs)} library.

\schemedisplay
(library (rnrs-no-one-armed-if) (export) (import (except (chezscheme) if))
  (export if (import (except (rnrs) if)))
  (define-syntax if
    (let ()
      (import (only (rnrs) if))
      (syntax-rules ()
        [(_ tst thn els) (if tst thn els)]))))

(import (rnrs-no-one-armed-if))
(if #t 3 4) ;=> 3
(if #t 3) ;=> \var{exception: invalid syntax}
\endschemedisplay

Another way to define the same library would be to define the
two-armed-only \scheme{if} with a different internal name and use
\scheme{rename} to export it under the name \scheme{if}:

\schemedisplay
(library (rnrs-no-one-armed-if) (export) (import (chezscheme))
  (export (rename (two-armed-if if)) (import (except (rnrs) if)))
  (define-syntax two-armed-if
    (syntax-rules ()
      [(_ tst thn els) (if tst thn els)])))

(import (rnrs-no-one-armed-if))
(if #t 3 4) ;=> 3
(if #t 3) ;=> \var{exception: invalid syntax}
\endschemedisplay

The placement of the \scheme{export} form in the library body is
irrelevant, e.g., the \scheme{export} form can appear after the
definition in the examples above.


%----------------------------------------------------------------------------
\entryheader
\formdef{indirect-export}{\categorysyntax}{(indirect-export \var{id} \var{indirect-id} \dots)}
\returns unspecified
\listlibraries
\endentryheader

This form is a definition and can appear wherever any other definition
can appear.

An \scheme{indirect-export} form declares that the named
\var{indirect-id}s are indirectly exported to top level if \var{id}
is exported to top level.

In general, if an identifier is not directly exported by a library or
module, it can be referenced outside of the library or module only in
the expansion of a macro defined within and exported from the library
or module.
Even this cannot occur for libraries or modules defined at top level
(or nested within other libraries or modules), unless either (1)
the library or module has been set up to implicitly export all
identifiers as indirect exports, or (2) each indirectly exported
identifier is explicitly declared as an indirect export of some
other identifier that is exported, either directly or indirectly, from
the library or module, via an \scheme{indirect-export} or the built-in
indirect export feature of a \scheme{module} export subform.
By default, (1) is true for a library and false for a module, but the
default can be overridden via the \scheme{implicit-exports}
form, which is described below.

This form is meaningful only within a top-level library, top-level module,
or module enclosed within a library or top-level module, although it
has no effect if the library or module already implicitly exports all
bindings.
It is allowed anywhere else definitions can appear, however, so macros
that expand into indirect export forms can be used in any definition
context.

Indirect exports are listed so the compiler can determine the
exact set of bindings (direct and indirect) that must be inserted
into the top-level environment, and conversely, the set of bindings
that may be treated more efficiently as local bindings (and
perhaps discarded, if they are not used).

In the example below, \scheme{indirect-export} is used to indirectly
export \scheme{count} to top level when \scheme{current-count} is
exported to top level.

\schemedisplay
(module M (bump-count current-count)
  (define-syntax current-count (identifier-syntax count))
  (indirect-export current-count count)
  (define count 0)
  (define bump-count
    (lambda ()
      (set! count (+ count 1)))))

(import M)
(bump-count)
current-count ;=> 1
count ;=> \var{exception: unbound identifier count}
\endschemedisplay

An \scheme{indirect-export} form is not required to make \scheme{count}
visible for \scheme{bump-count}, since it is a procedure whose code
is contained within the module rather than a macro that might expand
into a reference to \scheme{count} somewhere outside the module.

It is often useful to use \scheme{indirect-export} in the output
of a macro that expands into another macro named \var{a} if
\var{a} expands into references to identifiers that might not
be directly exported, as illustrated by the alternative definition
of module \scheme{M} above.

\schemedisplay
(define-syntax define-counter
  (syntax-rules ()
    [(_ getter bumper init incr)
     (begin
       (define count init)
       (define-syntax getter (identifier-syntax count))
       (indirect-export getter count)
       (define bumper
         (lambda ()
           (set! count (incr count)))))]))

(module M (bump-count current-count)
  (define-counter current-count bump-count 0 add1))
\endschemedisplay

%----------------------------------------------------------------------------
\entryheader
\formdef{implicit-exports}{\categorysyntax}{(implicit-exports #t)}
\formdef{implicit-exports}{\categorysyntax}{(implicit-exports #f)}
\returns unspecified
\listlibraries
\endentryheader

An \scheme{implicit-exports} form is a definition and can appear with other
definitions at the front of a \scheme{library} or \scheme{module}.
It is a syntax error for an \scheme{implicit-exports} form to appear in other
contexts, including at top level or among the definitions of a
top-level program or \scheme{lambda} body.

The \scheme{implicit-exports} form determines whether identifiers
not directly exported from a module or library are automatically
indirectly exported to the top level if any meta-binding (keyword, meta
definition, or property definition) is directly exported to top level
from the library or module.
The default for libraries is \scheme{#t}, to match the behavior required
by the Revised$^6$ Report, while the default for modules is \scheme{#f}.
The \scheme{implicit-exports} form is meaningful only within a library,
top-level module, or module enclosed within a library or top-level module.
It is allowed in a module enclosed within a \scheme{lambda}, \scheme{let},
or similar body, but ignored there because none of that module's bindings
can be exported to top level.

The advantage of \scheme{(implicit-exports #t)} is that indirect exports
need not be listed explicitly, which is convenient.
A disadvantage is that it often results in more bindings than necessary
being elevated to top level where they cannot be discarded as useless
by the optimizer.
For modules, another disadvantage is such bindings
cannot be proven immutable, which inhibits important optimizations such
as procedure inlining.
This can result in significantly lower run-time performance.

\section{Explicitly invoking libraries\label{SECTLIBRARYINVOCATION}}

%----------------------------------------------------------------------------
\noskipentryheader
\formdef{invoke-library}{\categoryprocedure}{(invoke-library \var{libref})}
\returns unspecified
\listlibraries
\endnoskipentryheader

\var{libref} must be an s-expression in the form of a library reference.
The syntax for library references is given in
Chapter~\ref{TSPL:CHPTLIBRARIES} of {\TSPLFOUR} and in the Revised$^6$
Report.

A library is implicitly invoked when or before some expression
outside the library (e.g., in another library or in a top-level
program) evaluates a reference to one of the library's exported
variables.
When the library is invoked, its body expressions (the right-hand-sides
of the library's variable definitions and its initialization
expressions) are evaluated.
Once invoked, the library is not invoked again within the same process,
unless it is first explicitly redefined or reloaded.

\scheme{invoke-library} explicitly invokes the library specified
by \var{libref} if it has not already been invoked or has since
been redefined or reloaded.
If the library has not yet been loaded, \scheme{invoke-library}
first loads the library via the process described in
Section~\ref{SECTUSELIBRARIES}.

\scheme{invoke-library} is typically only useful for libraries whose
body expressions have side effects.
It is useful to control when the side effects occur and to force
invocation of a library that has no exported variables.
Invoking a library does not force the compile-time code (macro
transformer expressions and meta definitions) to be loaded or
evaluated, nor does it cause the library's bindings to become
visible.

It is good practice to avoid externally visible side effects in
library bodies so the library can be used equally well at compile
time and run time.
When feasible, consider moving the side effects of a library body
to an initialization routine and adding a top-level program that
imports the library and calls the initialization routine.
With this structure, calls to \scheme{invoke-library} on the
library can be replaced by calls to 
\index{\scheme{load-program}}\scheme{load-program} on the
top-level program.

\section{Library Parameters\label{SECTLIBRARYPARAMETERS}}

\index{\scheme{import}}%
The parameters described below control where \scheme{import} looks
when attempting to load a library, whether it compiles the libraries
it loads, and whether it displays tracking messages as it performs its
search.

%----------------------------------------------------------------------------
\entryheader
\formdef{library-directories}{\categorythreadparameter}{library-directories}
\formdef{library-extensions}{\categorythreadparameter}{library-extensions}
\listlibraries
\endentryheader

The parameter \scheme{library-directories} determines where the files
containing library source and object code are located in the file system,
and the parameter \scheme{library-extensions} determines the filename
extensions for the files holding the code, as described in
section~\ref{SECTUSELIBRARIES}.
The values of both parameters are lists of pairs of strings.
The first string in each \scheme{library-directories} pair identifies a
source-file root directory, and the second identifies the corresponding
object-file root directory.
Similarly, the first string in each \scheme{library-extensions} pair
identifies a source-file extension, and the second identifies the
corresponding object-file extension.
The full path of a library source or object file consists of the source or
object root followed by the components of the library name prefixed by
slashes, with the library extension added on the end.
For example, for root \scheme{/usr/lib/scheme}, library name
\scheme{(app lib1)}, and extension \scheme{.sls}, the full path is
\scheme{/usr/lib/scheme/app/lib1.sls}.
If the library name portion forms an absolute pathname, e.g.,
\scheme{~/.myappinit}, the \scheme{library-directories} parameter is
ignored and no prefix is added.

The initial values of these parameters are shown below.

\schemedisplay
(library-directories) ;=> (("." . "."))

(library-extensions) ;=> ((".chezscheme.sls" . ".chezscheme.so")
                     ;==  (".ss" . ".so")
                     ;==  (".sls" . ".so")
                     ;==  (".scm" . ".so")
                     ;==  (".sch" . ".so"))
\endschemedisplay

As a convenience, when either of these parameters is set, any element of
the list can be specified as a single source string, in which case the
object string is determined automatically.
For \scheme{library-directories}, the object string is the same as
the source string, effectively naming the
same directory as a source- and object-code root.
For \scheme{library-extensions}, the object string is the result of
removing the last (or only) extension from the string and appending
\scheme{".so"}.
The \scheme{library-directories} and \scheme{library-extensions}
parameters also accept as input strings in the format described
in Section~\ref{SECTUSESCRIPTING}
for the
\index{\scheme{--libdirs} command-line option}\scheme{--libdirs} and
\index{\scheme{--libexts} command-line option}\scheme{--libexts} command-line
options.

%----------------------------------------------------------------------------
\entryheader
\formdef{compile-imported-libraries}{\categorythreadparameter}{compile-imported-libraries}
\listlibraries
\endentryheader

When the value of this parameter is \scheme{#t}, \scheme{import}
automatically calls the value of the \scheme{compile-library-handler} parameter (which defaults
to a procedure that simply calls \scheme{compile-library}) on any imported library if
the object file is missing, older than the corresponding source file,
older than any source files included (via \index{\scheme{include}}\scheme{include}) when the
object file was created, or itself requires a library that has or must
be recompiled, as described in Section~\ref{SECTUSELIBRARIES}.
The default initial value of this parameter is \scheme{#f}.
It can be set to \scheme{#t} via the command-line option
\index{\scheme{--compile-imported-libraries} command-line option}\scheme{--compile-imported-libraries}.

When \scheme{import} compiles a library via this mechanism, it does not
also load the compiled library, because this would cause portions of
library to be reevaluated.
Because of this, run-time expressions in the file outside of a
\scheme{library} form will not be evaluated.
If such expressions are present and should be evaluated, the library
should be loaded explicitly.

%----------------------------------------------------------------------------
\entryheader
\formdef{import-notify}{\categorythreadparameter}{import-notify}
\listlibraries
\endentryheader

When the new parameter \scheme{import-notify} is set to a true value,
\scheme{import} displays messages to the console-output port as it
searches for the file containing each library it needs to load.
The default value of this parameter is \scheme{#f}.

%----------------------------------------------------------------------------
\entryheader
\formdef{library-search-handler}{\categorythreadparameter}{library-search-handler}
\listlibraries
\endentryheader

The value of parameter must be a procedure that follows the protocol described
below for \scheme{default-library-search-handler}, which is the default value
of this parameter.

The value of this parameter is invoked to locate the source or object code for
a library during \scheme{import}, \scheme{compile-whole-program}, or
\scheme{compile-whole-library}.

%----------------------------------------------------------------------------
\entryheader
\formdef{default-library-search-handler}{\categoryprocedure}{(default-library-search-handler \var{who} \var{library} \var{directories} \var{extensions})}
\returns see below
\listlibraries
\endentryheader

This procedure is the default value of the \scheme{library-search-handler},
which is
called to locate the source or object code for a library
during \scheme{import},
\scheme{compile-whole-program}, or \scheme{compile-whole-library}.
\var{who} is a symbol that provides context in \scheme{import-notify} messages.
\var{library} is the name of the desired library.
\var{directories} is a list of source and object directory pairs in
the form returned by \scheme{library-directories}.
\var{extensions} is a list of source and object extension pairs in the form
returned by \scheme{library-extensions}.

This procedure searches the specified directories until it finds a library source or
object file with one of the specified extensions.
If it finds the source file first, it constructs the corresponding
object file path and checks whether the file exists.
If it finds the object file first, the procedure looks for a corresponding
source file with one of the given source extensions in a source directory paired
with that object directory.
The procedure returns three values:
the file-system path of the library source file or \scheme{#f} if not found,
the file-system path of the corresponding object file, which may be \scheme{#f},
and a boolean that is true if the object file exists.

\section{Library Inspection\label{SECTLIBRARYINSPECTION}}

%----------------------------------------------------------------------------
\noskipentryheader
\formdef{library-list}{\categoryprocedure}{(library-list)}
\returns a list of the libraries currently defined
\listlibraries
\endnoskipentryheader

The set of libraries initially defined includes those listed in
Section~\ref{SECTBUILTINLIBRARIES} above.

%----------------------------------------------------------------------------
\entryheader
\formdef{library-version}{\categoryprocedure}{(library-version \var{libref})}
\returns the version of the specified library
\formdef{library-exports}{\categoryprocedure}{(library-exports \var{libref})}
\returns a list of the exports of the specified library
\formdef{library-requirements}{\categoryprocedure}{(library-requirements \var{libref})}
\returns a list of libraries required by the specified library
\formdef{library-requirements}{\categoryprocedure}{(library-requirements \var{libref} \var{options})}
\returns a list of libraries required by the specified library, filtered by \var{options}
\formdef{library-object-filename}{\categoryprocedure}{(library-object-filename \var{libref})}
\returns the name of the object file holding the specified library, if any
\listlibraries
\endentryheader

Information can be obtained only for built-in libraries or libraries
previously loaded into the system.
\var{libref} must be an s-expression in the form of a library reference.
The syntax for library references is given in
Chapter~\ref{TSPL:CHPTLIBRARIES} of {\TSPLFOUR} and in the Revised$^6$
Report.

The \scheme{library-version} return value is a list of numbers
(possibly empty) representing the library's version.

The list of exports returned by \scheme{library-exports} is a list of
symbols, each identifying one of the library's exports.
The order in which the elements appear is unspecified.

When the optional \var{options} argument is supplied, it must be
an enumeration set over the symbols constituting
valid library-requirements options, as described in the
\scheme{library-requirements-options} entry below.
It defaults to a set containing all of the options.
Each element of the list of libraries returned by
\scheme{library-requirements} is an s-expression form of a library
reference.
The library reference includes the actual version of the library that is
present in the system (if nonempty), even if a version was not specified
when it was imported.
The order in which the libraries appear in the list returned by
\scheme{library-requirements} is unspecified.

\scheme{library-object-filename} returns a string naming the object
file if the specified library was loaded from or compiled to an object
file.
Otherwise, it returns \scheme{#f}.


\schemedisplay
(with-output-to-file "A.ss"
  (lambda ()
    (pretty-print
      '(library (A (1 2)) (export x z)
         (import (rnrs))
         (define x 'ex)
         (define y 23)
         (define-syntax z
           (syntax-rules ()
             [(_ e) (+ y e)])))))
  'replace)
(with-output-to-file "B.ss"
  (lambda ()
    (pretty-print
      '(library (B) (export x w)
         (import (rnrs) (A))
         (define w (cons (z 12) x)))))
  'replace)
(compile-imported-libraries #t)
(import (B))
(library-exports '(A)) ;=> (x z) ; or (z x)
(library-exports '(A (1 2))) ;=> (x z) ; or (z x)
(library-exports '(B)) ;=> (x w) ; or (w x)
(library-version '(A)) ;=> (1 2)
(library-version '(B)) ;=> ()
(library-requirements '(A)) ;=> ((rnrs (6)))
(library-requirements '(B)) ;=> ((rnrs (6)) (A (1 2)))
(library-object-filename '(A)) ;=> "A.so"
(library-object-filename '(B)) ;=> "B.so"
\endschemedisplay

%----------------------------------------------------------------------------
\entryheader
\formdef{library-requirements-options}{\categorysyntax}{(library-requirements-options \var{symbol} \dots)}
\returns a library-requirements-options enumeration set
\listlibraries
\endentryheader

\noindent
Library-requirements-options enumeration sets are passed to
\scheme{library-requirements} to determine the library requirements
to be listed.  The available options are described below.

\begin{description}
\item[\scheme{import}:]
Include the libraries that must be imported when the specified library
is imported.

\item[\scheme{visit@visit}:]
Includes the libraries that must be visited when the specified library
is visited.

\item[\scheme{invoke@visit}:]
Include the libraries that must be invoked when the specified library
is visited.

\item[\scheme{invoke}:]
Includes the libraries that must be invoked when the specified library
is invoked.
\end{description}