5.6.1 Library syntax

A library definition takes the following form:

(define-library ⟨library name⟩
  ⟨library declaration⟩ …)

⟨library name⟩ is a list whose members are identifiers and exact non-negative integers. It is used to identify the library uniquely when importing from other programs or libraries. Libraries whose first identifier is scheme are reserved for use by this report and future versions of this report. Libraries whose first identifier is srfi are reserved for libraries implementing Scheme Requests for Implementation. It is inadvisable, but not an error, for identifiers in library names to contain any of the characters | \ ? * < " : > + [ ] / or control characters after escapes are expanded.

A ⟨library declaration⟩ is any of:

• (export ⟨export spec⟩ …)
• (import ⟨import set⟩ …)
• (begin ⟨command or definition⟩ …)
• (include ⟨filename₁⟩ ⟨filename₂⟩ …)
• (include-ci ⟨filename₁⟩ ⟨filename₂⟩ …)
• (include-library-declarations ⟨filename₁⟩ ⟨filename₂⟩ …)
• (cond-expand ⟨ce-clause₁⟩ ⟨ce-clause₂⟩ …)

An export declaration specifies a list of identifiers which can be made visible to other libraries or programs. An ⟨export spec⟩ takes one of the following forms:

• ⟨identifier⟩
• (rename ⟨identifier₁⟩ ⟨identifier₂⟩)

In an ⟨export spec⟩, an ⟨identifier⟩ names a single binding defined within or imported into the library, where the external name for the export is the same as the name of the binding within the library. A rename spec exports the binding defined within or imported into the library and named by ⟨identifier₁⟩ in each (⟨identifier₁⟩ ⟨identifier₂⟩) pairing, using ⟨identifier₂⟩ as the external name.

An import declaration provides a way to import the identifiers exported by another library. It has the same syntax and semantics as an import declaration used in a program or at the REPL (see Import declarations).

The begin, include, and include-ci declarations are used to specify the body of the library. They have the same syntax and semantics as the corresponding expression types. This form of begin is analogous to, but not the same as, the two types of begin defined in Sequencing.

The include-library-declarations declaration is similar to include except that the contents of the file are spliced directly into the current library definition. This can be used, for example, to share the same export declaration among multiple libraries as a simple form of library interface.

The cond-expand declaration has the same syntax and semantics as the cond-expand expression type, except that it expands to spliced-in library declarations rather than expressions enclosed in begin.

One possible implementation of libraries is as follows: After all cond-expand library declarations are expanded, a new environment is constructed for the library consisting of all imported bindings. The expressions from all begin, include and include-ci library declarations are expanded in that environment in the order in which they occur in the library. Alternatively, cond-expand and import declarations may be processed in left to right order interspersed with the processing of other declarations, with the environment growing as imported bindings are added to it by each import declaration.

When a library is loaded, its expressions are executed in textual order. If a library’s definitions are referenced in the expanded form of a program or library body, then that library must be loaded before the expanded program or library body is evaluated. This rule applies transitively. If a library is imported by more than one program or library, it may possibly be loaded additional times.

Similarly, during the expansion of a library (foo), if any syntax keywords imported from another library (bar) are needed to expand the library, then the library (bar) must be expanded and its syntax definitions evaluated before the expansion of (foo).

Regardless of the number of times that a library is loaded, each program or library that imports bindings from a library must do so from a single loading of that library, regardless of the number of import declarations in which it appears. That is, (import (only (foo) a)) followed by (import (only (foo) b)) has the same effect as (import (only (foo) a b)).