commit becbff6845ce89337b98493322aa6d7b13bc97fe
parent 6e70c37ccd035a4e0df7b8c33fba8305595f2759
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Fri, 2 Feb 2024 00:21:54 -0500
Program structure: Reflow & delete leading spaces in @itemize.
Diffstat:
1 file changed, 251 insertions(+), 222 deletions(-)
diff --git a/doc/r7rs-small/program-structure.texinfo b/doc/r7rs-small/program-structure.texinfo
@@ -14,33 +14,38 @@
@node Programs
@section Programs
-A Scheme program consists of one or more import declarations followed by a sequence
-of expressions and definitions. Import declarations specify the libraries on which a
-program or library depends; a subset of the identifiers exported by the libraries are made
-available to the program. Expressions are described in @ref{Expressions}. Definitions are either
-variable definitions, syntax definitions, or record-type definitions, all of which are
-explained in this chapter. They are valid in some, but not all, contexts where expressions
-are allowed, specifically at the outermost level of a @svar{program} and at the beginning of a
-@svar{body}.
-
-At the outermost level of a program, @code{(begin }@svar{expression or definition@sub{1}} @dots{}@code{)} is equivalent to
-the sequence of expressions and definitions in the begin. Similarly, in a @svar{body}, (begin
-@svar{definition@sub{1}} @dots{}) is equivalent to the sequence @svar{definition@sub{1}} @dots{}. Macros can expand into
-such begin forms. For the formal definition, see @ref{Sequencing}.
-
-Import declarations and definitions cause bindings to be created in the global
-environment or modify the value of existing global bindings. The initial environment of a
-program is empty, so at least one import declaration is needed to introduce initial
-bindings.
-
-Expressions occurring at the outermost level of a program do not create any bindings.
-They are executed in order when the program is invoked or loaded, and typically perform
-some kind of initialization.
-
-Programs and libraries are typically stored in files, although in some implementations
-they can be entered interactively into a running Scheme system. Other paradigms are
-possible. Implementations which store libraries in files should document the mapping
-from the name of a library to its location in the file system.
+A Scheme program consists of one or more import declarations followed
+by a sequence of expressions and definitions. Import declarations
+specify the libraries on which a program or library depends; a subset
+of the identifiers exported by the libraries are made available to the
+program. Expressions are described in @ref{Expressions}. Definitions
+are either variable definitions, syntax definitions, or record-type
+definitions, all of which are explained in this chapter. They are
+valid in some, but not all, contexts where expressions are allowed,
+specifically at the outermost level of a @svar{program} and at the
+beginning of a @svar{body}.
+
+At the outermost level of a program, @code{(begin }@svar{expression
+or definition@sub{1}} @dots{}@code{)} is equivalent to the sequence of
+expressions and definitions in the begin. Similarly, in a @svar{body},
+(begin @svar{definition@sub{1}} @dots{}) is equivalent to the sequence
+@svar{definition@sub{1}} @dots{}. Macros can expand into such begin
+forms. For the formal definition, see @ref{Sequencing}.
+
+Import declarations and definitions cause bindings to be created in the
+global environment or modify the value of existing global bindings. The
+initial environment of a program is empty, so at least one import
+declaration is needed to introduce initial bindings.
+
+Expressions occurring at the outermost level of a program do not create
+any bindings. They are executed in order when the program is invoked
+or loaded, and typically perform some kind of initialization.
+
+Programs and libraries are typically stored in files, although in
+some implementations they can be entered interactively into a running
+Scheme system. Other paradigms are possible. Implementations which store
+libraries in files should document the mapping from the name of a library
+to its location in the file system.
@node Import declarations
@section Import declarations
@@ -51,9 +56,10 @@ An import declaration takes the following form:
(import @r{@svar{import-set} @dots{}})
@end example
-An import declaration provides a way to import identifiers exported by a library. Each
-@svar{import set} names a set of bindings from a library and possibly specifies local names for
-the imported bindings. It takes one of the following forms:
+An import declaration provides a way to import identifiers exported by a
+library. Each @svar{import set} names a set of bindings from a library and
+possibly specifies local names for the imported bindings. It takes one of
+the following forms:
@itemize
@@ -71,47 +77,52 @@ the imported bindings. It takes one of the following forms:
@item
@code{(rename }@svar{import set}
- @code{(}@svar{identifier@sub{1}} @svar{identifier@sub{2}}@code{)} @dots{}@code{)}
+@code{(}@svar{identifier@sub{1}} @svar{identifier@sub{2}}@code{)}
+@dots{}@code{)}
@end itemize
-In the first form, all of the identifiers in the named library's export clauses are imported
-with the same names (or the exported names if exported with rename). The additional
-@svar{import set} forms modify this set as follows:
+In the first form, all of the identifiers in the named library's export
+clauses are imported with the same names (or the exported names if
+exported with rename). The additional @svar{import set} forms modify this
+set as follows:
@itemize
@item
-@code{only} produces a subset of the given @svar{import set} including only the listed identifiers
- (after any renaming). It is an error if any of the listed identifiers are not found in the
- original set.
+@code{only} produces a subset of the given @svar{import set} including
+only the listed identifiers (after any renaming). It is an error if any of
+the listed identifiers are not found in the original set.
@item
-@code{except} produces a subset of the given @svar{import set}, excluding the listed identifiers
- (after any renaming). It is an error if any of the listed identifiers are not found in the
- original set.
+@code{except} produces a subset of the given @svar{import set}, excluding
+the listed identifiers (after any renaming). It is an error if any of the
+listed identifiers are not found in the original set.
@item
-@code{rename} modifies the given @svar{import set}, replacing each instance of @svar{identifier@sub{1}} with
- @svar{identifier@sub{2}}. It is an error if any of the listed @svar{identifier@sub{1}}s are not found in the original
- set.
+@code{rename} modifies the given @svar{import set}, replacing each
+instance of @svar{identifier@sub{1}} with @svar{identifier@sub{2}}. It is
+an error if any of the listed @svar{identifier@sub{1}}s are not found in
+the original set.
@item
-@code{prefix} automatically renames all identifiers in the given @svar{import set}, prefixing each
- with the specified @svar{identifier}.
+@code{prefix} automatically renames all identifiers in the given
+@svar{import set}, prefixing each with the specified @svar{identifier}.
@end itemize
-In a program or library declaration, it is an error to import the same identifier more than
-once with different bindings, or to redefine or mutate an imported binding with a
-definition or with @code{set!}, or to refer to an identifier before it is imported. However, a REPL
-should permit these actions.
+In a program or library declaration, it is an error to import the same
+identifier more than once with different bindings, or to redefine or
+mutate an imported binding with a definition or with @code{set!}, or to
+refer to an identifier before it is imported. However, a REPL should
+permit these actions.
@node Variable definitions
@section Variable definitions
-A variable definition binds one or more identifiers and specifies an initial value for each of
-them. The simplest kind of variable definition takes one of the following forms:
+A variable definition binds one or more identifiers and specifies an
+initial value for each of them. The simplest kind of variable definition
+takes one of the following forms:
@itemize
@@ -121,9 +132,9 @@ them. The simplest kind of variable definition takes one of the following forms:
@item
@code{(define }(@svar{variable} @svar{formals}@code{)} @svar{body}@code{)}
- @svar{Formals} are either a sequence of zero or more variables, or a sequence of one or
- more variables followed by a space-delimited period and another variable (as in a
- lambda expression). This form is equivalent to
+@svar{Formals} are either a sequence of zero or more variables, or a
+sequence of one or more variables followed by a space-delimited period and
+another variable (as in a lambda expression). This form is equivalent to
@example
(define @r{@svar{variable}}
@@ -133,7 +144,7 @@ them. The simplest kind of variable definition takes one of the following forms:
@item
@code{(define (}@svar{variable} @code{.} @svar{formal}@code{)} @svar{body}@code{)}
- @svar{Formal} is a single variable. This form is equivalent to
+@svar{Formal} is a single variable. This form is equivalent to
@example
(define @r{@svar{variable}}
@@ -164,10 +175,11 @@ expression
(set! @r{@svar{variable} @svar{expression}})
@end example
-if @svar{variable} is bound to a non-syntax value.
-However, if @svar{variable} is not bound, or is a syntactic keyword, then the definition will bind
-@svar{variable} to a new location before performing the assignment, whereas it would be an
-error to perform a @code{set!} on an unbound variable.
+if @svar{variable} is bound to a non-syntax value. However, if
+@svar{variable} is not bound, or is a syntactic keyword, then the
+definition will bind @svar{variable} to a new location before performing
+the assignment, whereas it would be an error to perform a @code{set!} on
+an unbound variable.
@example
(define add3
@@ -180,15 +192,14 @@ error to perform a @code{set!} on an unbound variable.
@node Internal definitions
@subsection Internal definitions
-Definitions can occur at the
-beginning of a @svar{body} (that is, the body of a @code{lambda},
-@code{let}, @code{let*}, @code{letrec}, @code{letrec*},
-@code{let-values}, @code{let*-values}, @code{let-syntax}, @code{letrec-syntax},
-@code{parameterize}, @code{guard}, or @code{case-lambda}). Note that
-such a body might not be apparent until after expansion of other syntax.
-Such definitions are known as @dfn{internal definitions}
-as opposed to the global definitions described above.
-The variables defined by internal definitions are local to the
+Definitions can occur at the beginning of a @svar{body} (that is,
+the body of a @code{lambda}, @code{let}, @code{let*}, @code{letrec},
+@code{letrec*}, @code{let-values}, @code{let*-values}, @code{let-syntax},
+@code{letrec-syntax}, @code{parameterize}, @code{guard}, or
+@code{case-lambda}). Note that such a body might not be apparent
+until after expansion of other syntax. Such definitions are known as
+@dfn{internal definitions} as opposed to the global definitions described
+above. The variables defined by internal definitions are local to the
@svar{body}. That is, @svar{variable} is bound rather than assigned,
and the region of the binding is the entire @svar{body}. For example,
@@ -199,11 +210,9 @@ and the region of the binding is the entire @svar{body}. For example,
(foo (+ x 3))) @result{} 45
@end example
-An expanded @svar{body} containing internal definitions
-can always be
-converted into a completely equivalent @code{letrec*} expression. For
-example, the @code{let} expression in the above example is equivalent
-to
+An expanded @svar{body} containing internal definitions can always be
+converted into a completely equivalent @code{letrec*} expression. For
+example, the @code{let} expression in the above example is equivalent to
@example
(let ((x 5))
@@ -212,30 +221,34 @@ to
(foo (+ x 3))))
@end example
-Just as for the equivalent @code{letrec*} expression, it is an error if it is not
-possible to evaluate each @svar{expression} of every internal definition in a @svar{body} without
-assigning or referring to the value of the corresponding @svar{variable} or the @svar{variable} of
-any of the definitions that follow it in @svar{body}.
+Just as for the equivalent @code{letrec*} expression, it is an error if
+it is not possible to evaluate each @svar{expression} of every internal
+definition in a @svar{body} without assigning or referring to the value
+of the corresponding @svar{variable} or the @svar{variable} of any of
+the definitions that follow it in @svar{body}.
-It is an error to define the same identifier more than once in the same @svar{body}.
+It is an error to define the same identifier more than once in the
+same @svar{body}.
-Wherever an internal definition can occur, @code{(begin }@svar{definition@sub{1}} @dots{}@code{)} is equivalent to the
-sequence of definitions that form the body of the @code{begin}.
+Wherever an internal definition can occur,
+@code{(begin }@svar{definition@sub{1}} @dots{}@code{)} is equivalent
+to the sequence of definitions that form the body of the @code{begin}.
@node Multiple value definitions
@subsection Multiple-value definitions
-Another kind of definition is provided by @code{define-values}, which creates multiple definitions
-from a single expression returning multiple values. It is allowed wherever define is
-allowed.
+Another kind of definition is provided by @code{define-values}, which
+creates multiple definitions from a single expression returning multiple
+values. It is allowed wherever define is allowed.
@deffn syntax define-values @svar{formals} @svar{expression}
-It is an error if a variable appears more than once in the set of @svar{formals}.
+It is an error if a variable appears more than once in the set of
+@svar{formals}.
-Semantics: @svar{Expression} is evaluated, and the @svar{formals} are bound to the return values in
-the same way that the @svar{formals} in a @code{lambda} expression are matched to the arguments in
-a procedure call.
+Semantics: @svar{Expression} is evaluated, and the @svar{formals} are
+bound to the return values in the same way that the @svar{formals} in a
+@code{lambda} expression are matched to the arguments in a procedure call.
@example
(define-values (x y) (exact-integer-sqrt 17))
@@ -257,16 +270,18 @@ Syntax definitions have this form:
(define-syntax @r{@svar{keyword} @svar{transformer spec}})
@end example
-@svar{Keyword} is an identifier, and the @svar{transformer spec} is an instance of @code{syntax-rules}. Like
-variable definitions, syntax definitions can appear at the outermost level or nested within
-a body.
+@svar{Keyword} is an identifier, and the @svar{transformer spec} is
+an instance of @code{syntax-rules}. Like variable definitions, syntax
+definitions can appear at the outermost level or nested within a body.
-If the @code{define-syntax} occurs at the outermost level, then the global syntactic environment
-is extended by binding the @svar{keyword} to the specified transformer, but previous
-expansions of any global binding for @svar{keyword} remain unchanged. Otherwise, it is an
-@dfn{internal syntax definition}, and is local to the @svar{body} in which it is defined. Any use of a
-syntax keyword before its corresponding definition is an error. In particular, a use that
-precedes an inner definition will not apply an outer definition.
+If the @code{define-syntax} occurs at the outermost level, then the global
+syntactic environment is extended by binding the @svar{keyword} to the
+specified transformer, but previous expansions of any global binding
+for @svar{keyword} remain unchanged. Otherwise, it is an @dfn{internal
+syntax definition}, and is local to the @svar{body} in which it is
+defined. Any use of a syntax keyword before its corresponding definition
+is an error. In particular, a use that precedes an inner definition will
+not apply an outer definition.
@example
(let ((x 1) (y 2))
@@ -280,13 +295,15 @@ precedes an inner definition will not apply an outer definition.
(list x y)) @result{} (2 1)
@end example
-Macros can expand into definitions in any context that permits them. However, it is an
-error for a definition to define an identifier whose binding has to be known in order to
-determine the meaning of the definition itself, or of any preceding definition that belongs
-to the same group of internal definitions. Similarly, it is an error for an internal definition
-to define an identifier whose binding has to be known in order to determine the
-boundary between the internal definitions and the expressions of the body it belongs to.
-For example, the following are errors:
+Macros can expand into definitions in any context that permits
+them. However, it is an error for a definition to define an identifier
+whose binding has to be known in order to determine the meaning of the
+definition itself, or of any preceding definition that belongs to the
+same group of internal definitions. Similarly, it is an error for an
+internal definition to define an identifier whose binding has to be known
+in order to determine the boundary between the internal definitions and
+the expressions of the body it belongs to. For example, the following
+are errors:
@example
(define define 3)
@@ -309,13 +326,13 @@ For example, the following are errors:
@section Record-type definitions
@dfn{Record-type definitions} are used to introduce new data types, called
-@dfn{record types}.
-Like other definitions, they can appear either at the outermost level or in a body.
-The values of a record type are called @dfn{records} and are
-aggregations of zero or more @dfn{fields}, each of which holds a single location.
-A predicate, a constructor, and field accessors and
-mutators are defined for each record type.
+@dfn{record types}. Like other definitions, they can appear either at the
+outermost level or in a body. The values of a record type are called
+@dfn{records} and are aggregations of zero or more @dfn{fields}, each of
+which holds a single location. A predicate, a constructor, and field
+accessors and mutators are defined for each record type.
+@c FIXME: Should we "stub" this and put the actual syntax below?
@deffn syntax define-record-type @svar{name} @svar{constructor} @svar{pred} @svar{field}@dots{}
Syntax: @svar{name} and @svar{pred} are identifiers. The @svar{constructor} is of the form
@@ -336,46 +353,52 @@ or of the form
@code{(}@svar{field name} @svar{accessor name} @svar{modifier name}@code{)}
@end display
-It is an
-error for the same identifier to occur more than once as a field name. It is also an error
-for the same identifier to occur more than once as an accessor or mutator name.
+It is an error for the same identifier to occur more than once as a
+field name. It is also an error for the same identifier to occur more
+than once as an accessor or mutator name.
-The @code{define-record-type} construct is generative: each use creates a new record type that is
-distinct from all existing types, including Scheme's predefined types and other record
-types---even record types of the same name or structure.
+The @code{define-record-type} construct is generative: each use creates
+a new record type that is distinct from all existing types, including
+Scheme's predefined types and other record types---even record types of
+the same name or structure.
-An instance of @code{define-record-type} is equivalent to the following definitions:
+An instance of @code{define-record-type} is equivalent to the following
+definitions:
@itemize
@item
-@svar{name} is bound to a representation of the record type itself. This may be a run-time
- object or a purely syntactic representation. The representation is not utilized in this
- report, but it serves as a means to identify the record type for use by further language
- extensions.
+@svar{name} is bound to a representation of the record type itself. This
+may be a run-time object or a purely syntactic representation. The
+representation is not utilized in this report, but it serves as a means to
+identify the record type for use by further language extensions.
@item
-@svar{constructor name} is bound to a procedure that takes as many arguments as there
- are @svar{field name}s in the @code{(}@svar{constructor name} @dots{}@code{)} subexpression and returns a new
- record of type @svar{name}. Fields whose names are listed with @svar{constructor name} have
- the corresponding argument as their initial value. The initial values of all other fields are
- unspecified. It is an error for a field name to appear in @svar{constructor} but not as a <field
- name>.
+@svar{constructor name} is bound to a procedure that takes as many
+arguments as there are @svar{field name}s in the @code{(}@svar{constructor
+name} @dots{}@code{)} subexpression and returns a new record of type
+@svar{name}. Fields whose names are listed with @svar{constructor name}
+have the corresponding argument as their initial value. The initial values
+of all other fields are unspecified. It is an error for a field name to
+appear in @svar{constructor} but not as a <field name>.
@item
-@svar{pred} is bound to a predicate that returns @code{#t} when given a value returned by the
- procedure bound to @svar{constructor name} and @code{#f} for everything else.
+@svar{pred} is bound to a predicate that returns @code{#t} when given a
+value returned by the procedure bound to @svar{constructor name} and
+@code{#f} for everything else.
@item
-Each @svar{accessor name} is bound to a procedure that takes a record of type @svar{name} and
- returns the current value of the corresponding field. It is an error to pass an accessor a
- value which is not a record of the appropriate type.
+Each @svar{accessor name} is bound to a procedure that takes a record of
+type @svar{name} and returns the current value of the corresponding field.
+It is an error to pass an accessor a value which is not a record of the
+appropriate type.
@item
-Each @svar{modifier name} is bound to a procedure that takes a record of type @svar{name} and
- a value which becomes the new value of the corresponding field; an unspecified value
- is returned. It is an error to pass a modifier a first argument which is not a record of
- the appropriate type.
+Each @svar{modifier name} is bound to a procedure that takes a record of
+type @svar{name} and a value which becomes the new value of the
+corresponding field; an unspecified value is returned. It is an error to
+pass a modifier a first argument which is not a record of the appropriate
+type.
@end itemize
@@ -408,9 +431,9 @@ to be a predicate for instances of @code{<pare>}.
@node Libraries
@section Libraries
-Libraries provide a way to organize Scheme programs into reusable parts with explicitly
-defined interfaces to the rest of the program. This section defines the notation and
-semantics for libraries.
+Libraries provide a way to organize Scheme programs into reusable parts
+with explicitly defined interfaces to the rest of the program. This
+section defines the notation and semantics for libraries.
@menu
* Library Syntax::
@@ -427,13 +450,15 @@ A library definition takes the following form:
@svar{library declaration} @dots{}@code{)}
@end display
-@svar{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 @code{scheme} are reserved for use by this report and future
-versions of this report. Libraries whose first identifier is @code{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 @code{| \ ? * < " : > + [ ] /} or
-control characters after escapes are expanded.
+@svar{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 @code{scheme} are reserved for use by this report and future
+versions of this report. Libraries whose first identifier is @code{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 @code{| \ ? * < " : > +
+[ ] /} or control characters after escapes are expanded.
A @svar{library declaration} is any of:
@@ -449,21 +474,26 @@ A @svar{library declaration} is any of:
@code{(begin }@svar{command or definition} @dots{}@code{)}
@item
-@code{(include }@svar{filename@sub{1}} @svar{filename@sub{2}} @dots{}@code{)}
+@code{(include }@svar{filename@sub{1}} @svar{filename@sub{2}}
+@dots{}@code{)}
@item
-@code{(include-ci }@svar{filename@sub{1}} @svar{filename@sub{2}} @dots{}@code{)}
+@code{(include-ci }@svar{filename@sub{1}} @svar{filename@sub{2}}
+@dots{}@code{)}
@item
-@code{(include-library-declarations }@svar{filename@sub{1}} @svar{filename@sub{2}} @dots{}@code{)}
+@code{(include-library-declarations }@svar{filename@sub{1}}
+@svar{filename@sub{2}} @dots{}@code{)}
@item
-@code{(cond-expand }@svar{ce-clause@sub{1}} @svar{ce-clause@sub{2}} @dots{}@code{)}
+@code{(cond-expand }@svar{ce-clause@sub{1}} @svar{ce-clause@sub{2}}
+@dots{}@code{)}
@end itemize
-An @code{export} declaration specifies a list of identifiers which can be made visible to other
-libraries or programs. An @svar{export spec} takes one of the following forms:
+An @code{export} declaration specifies a list of identifiers which can be
+made visible to other libraries or programs. An @svar{export spec} takes
+one of the following forms:
@itemize
@@ -475,71 +505,72 @@ libraries or programs. An @svar{export spec} takes one of the following forms:
@end itemize
-In an @svar{export spec}, an @svar{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 @code{rename} spec exports the binding defined within or imported
-into the library and named by @svar{identifier@sub{1}} in each (@svar{identifier@sub{1}} @svar{identifier@sub{2}}) pairing,
+In an @svar{export spec}, an @svar{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 @code{rename} spec exports the binding defined within
+or imported into the library and named by @svar{identifier@sub{1}}
+in each (@svar{identifier@sub{1}} @svar{identifier@sub{2}}) pairing,
using @svar{identifier@sub{2}} as the external name.
-An @code{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 @ref{Import declarations}).
+An @code{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 @ref{Import
+declarations}).
-The @code{begin}, @code{include}, and @code{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 @code{begin} is analogous to, but not the same as, the
-two types of @code{begin} defined in @ref{Sequencing}.
+The @code{begin}, @code{include}, and @code{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
+@code{begin} is analogous to, but not the same as, the two types of
+@code{begin} defined in @ref{Sequencing}.
The @code{include-library-declarations} declaration is similar to
-@code{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 @code{export} declaration among multiple libraries as a simple
-form of library interface.
-
-The @code{cond-expand} declaration has the same syntax and semantics as
-the @code{cond-expand} expression type, except that it expands to
-spliced-in library declarations rather than expressions enclosed in @code{begin}.
-
-One possible implementation of libraries is as follows:
-After all @code{cond-expand} library declarations are expanded, a new
-environment is constructed for the library consisting of all
-imported bindings. The expressions
-from all @code{begin}, @code{include} and @code{include-ci}
-library declarations are expanded in that environment in the order in which
-they occur in the library.
-Alternatively, @code{cond-expand} and @code{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 @code{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
+@code{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 @code{export} declaration among multiple libraries as a
+simple form of library interface.
+
+The @code{cond-expand} declaration has the same syntax and semantics
+as the @code{cond-expand} expression type, except that it expands to
+spliced-in library declarations rather than expressions enclosed in
+@code{begin}.
+
+One possible implementation of libraries is as follows: After all
+@code{cond-expand} library declarations are expanded, a new environment
+is constructed for the library consisting of all imported bindings. The
+expressions from all @code{begin}, @code{include} and @code{include-ci}
+library declarations are expanded in that environment in the order in
+which they occur in the library. Alternatively, @code{cond-expand}
+and @code{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
+@code{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 @code{(foo)}, if any syntax
keywords imported from another library @code{(bar)} are needed to expand
-the library, then the library @code{(bar)} must be expanded and its syntax
-definitions evaluated before the expansion of @code{(foo)}.
+the library, then the library @code{(bar)} must be expanded and its
+syntax definitions evaluated before the expansion of @code{(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, @code{(import (only (foo) a))} followed by @code{(import (only (foo) b))}
-has the same effect as @code{(import (only (foo) a b))}.
+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, @code{(import (only (foo) a))} followed
+by @code{(import (only (foo) b))} has the same effect as @code{(import
+(only (foo) a b))}.
@node Library example
@subsection Library example
-The following example shows how a program can be divided into libraries plus a relatively
-small main program [16]. If the main program is entered into a REPL, it is not necessary to
-import the base library.
+The following example shows how a program can be divided into libraries
+plus a relatively small main program [16]. If the main program is entered
+into a REPL, it is not necessary to import the base library.
@example
(define-library (example grid)
@@ -634,27 +665,25 @@ import the base library.
@node The REPL
@section The REPL
-Implementations may provide an interactive session called a
-@dfn{REPL} (Read-Eval-Print Loop), where import declarations,
-expressions and definitions can be
-entered and evaluated one at a time. For convenience and ease of use,
-the global Scheme environment in a REPL
-must not be empty, but must start out with at least the bindings provided by the
-base library. This library includes the core syntax of Scheme
-and generally useful procedures that manipulate data. For example, the
-variable @code{abs} is bound to a
-procedure of one argument that computes the absolute value of a
-number, and the variable @code{+} is bound to a procedure that computes
-sums. The full list of @code{(scheme base)} bindings can be found in
-@ref{Appendix A}.
-
-Implementations may provide an initial REPL environment
-which behaves as if all possible variables are bound to locations, most of
-which contain unspecified values. Top level REPL definitions in
-such an implementation are truly equivalent to assignments,
-unless the identifier is defined as a syntax keyword.
+Implementations may provide an interactive session called a @dfn{REPL}
+(Read-Eval-Print Loop), where import declarations, expressions and
+definitions can be entered and evaluated one at a time. For convenience
+and ease of use, the global Scheme environment in a REPL must not be
+empty, but must start out with at least the bindings provided by the base
+library. This library includes the core syntax of Scheme and generally
+useful procedures that manipulate data. For example, the variable
+@code{abs} is bound to a procedure of one argument that computes the
+absolute value of a number, and the variable @code{+} is bound to a
+procedure that computes sums. The full list of @code{(scheme base)}
+bindings can be found in @ref{Appendix A}.
+
+Implementations may provide an initial REPL environment which behaves as
+if all possible variables are bound to locations, most of which contain
+unspecified values. Top level REPL definitions in such an implementation
+are truly equivalent to assignments, unless the identifier is defined
+as a syntax keyword.
An implementation may provide a mode of operation in which the REPL
reads its input from a file. Such a file is not, in general, the same
-as a program, because it can contain import declarations in places other than
-the beginning.
+as a program, because it can contain import declarations in places other
+than the beginning.
