.SCM File Format – Libraries and modules

R7RS libraries

A library is one define-library form:

(define-library (example grid)
  (export make rows cols ref each
          (rename put! set!))
  (import (scheme base))
  (begin
    (define (make n m) ...)
    (define (put! grid n m v) ...)))

The library name is a list of identifiers and exact non-negative integers, which identifies the library when other code imports it. Names whose first element is scheme are reserved for the report and its successors, and those starting with srfi for SRFI libraries ((srfi 1), (srfi 69)). Using the characters | \ ? * < " : > + [ ] / in a name is inadvisable but not an error, because they are unsafe in file names.

Library declarations

When a library is loaded its expressions run in textual order. A library whose definitions are referenced by another must be loaded before it, and so on transitively; a syntax keyword needed to expand a library requires the library that defines it to be expanded and its syntax definitions evaluated first. A library imported by several others may possibly be loaded more than once, but each program or library that imports from it must do so from a single loading, so two import declarations of one library have the same effect as one. R7RS has no versions and no phases.

Programs and import

An R7RS program starts with one or more import declarations, then expressions and definitions. An import set is one of:

It is an error to import one identifier twice with different bindings, to redefine or set! an imported binding, or to use an identifier before it is imported (a REPL may allow all three). The initial environment of an R7RS program is empty, so at least (import (scheme base)) is usual. A REPL starts with the bindings of at least (scheme base).

(import (scheme base)
        (only (example life) life)
        (rename (prefix (example grid) grid-)
                (grid-make make-grid)))

R6RS libraries

(library (example grid (1 0))
  (export make rows cols ref (rename put! set!))
  (import (rnrs base) (rnrs lists))
  (define (make n m) ...)
  (define (put! grid n m v) ...))

• Name and version. A library name is a list of identifiers, optionally ending in a version, a list of exact non-negative integers: (example grid (1 0)). The version of an empty list () is the default.
• Body. After the export and import clauses come definitions and then expressions, without a begin. Definitions are evaluated left to right as in an implicit letrec*, then the expressions.
• Exports. An identifier or (rename (internal external) ...). Exported variables are immutable, in the exporting and the importing library: a set! on one is a syntax violation. An exported macro may implicitly export an unexported identifier it inserts.
• Imports. An import spec is an import set or (for set level ...) where a level is run (= (meta 0)), expand (= (meta 1)) or (meta n). An import set is a library reference (a name, optionally with a version reference), or (library reference), (only ...), (except ...), (prefix ...) or (rename ...), the same as R7RS.
• Version references. (example grid (1 0)) matches versions that start 1 0; (example grid (>= 1 0)) uses >= and <= on a sub-version; and (and ...), (or ...) and (not ...) combine version references and sub-version references. When several libraries match, which is chosen is implementation-dependent.
• Phases. Run-time expressions are phase 0 and the right-hand sides of define-syntax are phase 1, so a macro transformer that calls a procedure of library A needs (for (A) expand) in its library. A visit evaluates the syntax definitions and an instantiation the variable definitions of a library in one phase.
• No reserved words. library, export, import, for, run, expand, meta, only, except, prefix, rename, and, or, not, >= and <= are part of the syntax of the form and are not reserved.

R6RS top-level programs

A top-level program is an import form and then the body, with no library wrapper; the report’s chapter 8 describes it as a sequence of forms where the first is the import. It may start with #!r6rs. The program’s exit is (exit) from (rnrs programs).

R6RS and R7RS libraries compared

A library for both is written twice, or an implementation that accepts both can read either; CHICKEN, Chez, Guile, Racket and others have different amounts of support. SRFI 97 names the SRFI libraries for R6RS as (srfi :1 lists) and similar; the :1 numeric form is one reason the viewer does not treat a leading colon as a keyword inside an import.

cond-expand and features

(cond-expand (feature body ...) ... (else body ...)) chooses at expansion time, in expressions, in bodies and in library declarations. A feature requirement is a feature identifier, (library name), or an and, or or not of requirements. The R7RS feature identifiers are r7rs, exact-closed, exact-complex, ieee-float, full-unicode, ratios, and, as implementations choose, posix, windows, the operating systems (unix, darwin, gnu-linux, bsd, freebsd, solaris), the processors (i386, x86-64, ppc, sparc, jvm, clr, llvm), the memory models (ilp32, lp64, ilp64), the byte order (big-endian, little-endian), and the implementation’s own name and name-version. SRFI 0 is the older cond-expand, SRFI 7 a configuration language, and SRFI 112 environment inquiry (implementation-name and the like). (features) returns the list.

Module systems of the implementations

Every entry in this table is from memory of the implementation’s documentation and was not checked against the manuals; see the note below. SRFI 83 and 103 proposed R6RS-style library syntaxes and were withdrawn; SRFI 138 describes compiling Scheme programs to executables.

The viewer colours the module-defining forms of these systems (define-module, use-modules, module, use, require-extension) as syntax and the module names after them as library names.

Not described

Known, not yet covered

• Reference: the expansion and instantiation order of R6RS libraries (the visit and instantiate rules of chapter 7 and the expansion process of chapter 10) is summarised, not described step by step.
• Reference: the table of module systems was written from memory of the manuals of Guile, CHICKEN, Chez, Gambit, MIT/GNU, Chibi, Gauche, Bigloo and Racket, none of which was read; details such as which versions of Gambit and MIT/GNU Scheme added R7RS libraries are not stated, and the table should be taken as indicative.
• Reference: how each implementation finds a library file from its name is not described.

See also

• Standard libraries – the libraries the reports define
• Macros – phases and macro export
• Implementations and dialects – what each implementation supports