[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.19.6 R6RS Libraries
In addition to the API described in the previous sections, you also
have the option to create modules using the portable library
form
described in R6RS (see R6RS Library Form in The Revised^6 Report on the Algorithmic Language Scheme), and to import
libraries created in this format by other programmers. Guile’s R6RS
library implementation takes advantage of the flexibility built into the
module system by expanding the R6RS library form into a corresponding
Guile define-module
form that specifies equivalent import and
export requirements and includes the same body expressions. The library
expression:
(library (mylib (1 2)) (import (otherlib (3))) (export mybinding))
is equivalent to the module definition:
(define-module (mylib) #:version (1 2) #:use-module ((otherlib) #:version (3)) #:export (mybinding))
Central to the mechanics of R6RS libraries is the concept of import
and export levels, which control the visibility of bindings at
various phases of a library’s lifecycle — macros necessary to
expand forms in the library’s body need to be available at expand
time; variables used in the body of a procedure exported by the
library must be available at runtime. R6RS specifies the optional
for
sub-form of an import set specification (see below)
as a mechanism by which a library author can indicate that a
particular library import should take place at a particular phase
with respect to the lifecycle of the importing library.
Guile’s library implementation uses a technique called
implicit phasing (first described by Abdulaziz Ghuloum and R.
Kent Dybvig), which allows the expander and compiler to automatically
determine the necessary visibility of a binding imported from another
library. As such, the for
sub-form described below is ignored by
Guile (but may be required by Schemes in which phasing is explicit).
- Scheme Syntax: library name (export export-spec ...) (import import-spec ...) body ...
Defines a new library with the specified name, exports, and imports, and evaluates the specified body expressions in this library’s environment.
The library name is a non-empty list of identifiers, optionally ending with a version specification of the form described above (see section Creating Guile Modules).
Each export-spec is the name of a variable defined or imported by the library, or must take the form
(rename (internal-name external-name) ...)
, where the identifier internal-name names a variable defined or imported by the library and external-name is the name by which the variable is seen by importing libraries.Each import-spec must be either an import set (see below) or must be of the form
(for import-set import-level ...)
, where each import-level is one of:run expand (meta level)
where level is an integer. Note that since Guile does not require explicit phase specification, any import-sets found inside of
for
sub-forms will be “unwrapped” during expansion and processed as if they had been specified directly.Import sets in turn take one of the following forms:
library-reference (library library-reference) (only import-set identifier ...) (except import-set identifier ...) (prefix import-set identifier) (rename import-set (internal-identifier external-identifier) ...)
where library-reference is a non-empty list of identifiers ending with an optional version reference (see section R6RS Version References), and the other sub-forms have the following semantics, defined recursively on nested import-sets:
-
The
library
sub-form is used to specify libraries for import whose names begin with the identifier “library.” -
The
only
sub-form imports only the specified identifiers from the given import-set. -
The
except
sub-form imports all of the bindings exported by import-set except for those that appear in the specified list of identifiers. -
The
prefix
sub-form imports all of the bindings exported by import-set, first prefixing them with the specified identifier. -
The
rename
sub-form imports all of the identifiers exported by import-set. The binding for each internal-identifier among these identifiers is made visible to the importing library as the corresponding external-identifier; all other bindings are imported using the names provided by import-set.
Note that because Guile translates R6RS libraries into module definitions, an import specification may be used to declare a dependency on a native Guile module — although doing so may make your libraries less portable to other Schemes.
-
The
- Scheme Syntax: import import-spec ...
Import into the current environment the libraries specified by the given import specifications, where each import-spec takes the same form as in the
library
form described above.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on April 20, 2013 using texi2html 5.0.