commit 0ced04d836af9067517e0bb55b4973a423107c6c
parent ed4f7ee1f7ccc73365f072008c0c834b642ed223
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Thu, 1 Feb 2024 20:07:17 -0500
Macros: Reflow paragraphs.
Diffstat:
1 file changed, 135 insertions(+), 113 deletions(-)
diff --git a/doc/r7rs-small/macros.texinfo b/doc/r7rs-small/macros.texinfo
@@ -9,48 +9,52 @@ Scheme programs can define and use new derived expression types, called
@end display
where @svar{keyword} is an identifier that uniquely determines the
-expression type. This identifier is called the @dfn{syntactic keyword}, or simply @dfn{keyword}, of the
-macro. The number of the @svar{datum}s, and their syntax, depends on the expression type.
+expression type. This identifier is called the @dfn{syntactic keyword}, or
+simply @dfn{keyword}, of the macro. The number of the @svar{datum}s, and
+their syntax, depends on the expression type.
-Each instance of a macro is called a @dfn{use} of the macro. The set of rules that specifies how a
-use of a macro is transcribed into a more primitive expression is called the @dfn{transformer} of
-the macro.
+Each instance of a macro is called a @dfn{use} of the macro. The set of
+rules that specifies how a use of a macro is transcribed into a more
+primitive expression is called the @dfn{transformer} of the macro.
The macro definition facility consists of two parts:
@itemize
@item
-A set of expressions used to establish that certain identifiers are macro keywords,
- associate them with macro transformers, and control the scope within which a macro
- is defined, and
+A set of expressions used to establish that certain identifiers are macro
+keywords, associate them with macro transformers, and control the scope
+within which a macro is defined, and
@item
a pattern language for specifying macro transformers.
@end itemize
-The syntactic keyword of a macro can shadow variable bindings, and local variable
-bindings can shadow syntactic bindings. Two mechanisms are provided to prevent
-unintended conflicts:
+The syntactic keyword of a macro can shadow variable bindings, and local
+variable bindings can shadow syntactic bindings. Two mechanisms are
+provided to prevent unintended conflicts:
@itemize
@item
-If a macro transformer inserts a binding for an identifier (variable or keyword), the
- identifier will in effect be renamed throughout its scope to avoid conflicts with other
- identifiers. Note that a global variable definition may or may not introduce a binding;
-@xref{Variable definitions}.
+If a macro transformer inserts a binding for an identifier (variable or
+keyword), the identifier will in effect be renamed throughout its scope to
+avoid conflicts with other identifiers. Note that a global variable
+definition may or may not introduce a binding; @xref{Variable
+definitions}.
@item
-If a macro transformer inserts a free reference to an identifier, the reference refers to
- the binding that was visible where the transformer was specified, regardless of any
- local bindings that surround the use of the macro.
+If a macro transformer inserts a free reference to an identifier, the
+reference refers to the binding that was visible where the transformer was
+specified, regardless of any local bindings that surround the use of the
+macro.
@end itemize
-In consequence, all macros defined using the pattern language are ``hygienic'' and
-``referentially transparent'' and thus preserve Scheme's lexical scoping. [21, 22, 2, 9, 12]
+In consequence, all macros defined using the pattern language are
+``hygienic'' and ``referentially transparent'' and thus preserve Scheme's
+lexical scoping. [21, 22, 2, 9, 12]
Implementations may provide macro facilities of other types.
@@ -64,10 +68,10 @@ Implementations may provide macro facilities of other types.
@subsection Binding constructs for syntactic keywords
The @code{let-syntax} and @code{letrec-syntax} binding constructs are
-analogous to @code{let} and @code{letrec}, but they bind
-syntactic keywords to macro transformers instead of binding variables
-to locations that contain values. Syntactic keywords can also be
-bound globally or locally with @code{define-syntax}; @xref{Syntax definitions}.
+analogous to @code{let} and @code{letrec}, but they bind syntactic
+keywords to macro transformers instead of binding variables to locations
+that contain values. Syntactic keywords can also be bound globally or
+locally with @code{define-syntax}; @xref{Syntax definitions}.
@deffn syntax let-syntax @svar{bindings} @svar{body}
@@ -78,13 +82,15 @@ Syntax: @svar{Bindings} has the form
@end display
Each @svar{keyword} is an identifier, each @svar{transformer spec}
-is an instance of @code{syntax-rules}, and @svar{body} is a sequence of zero or more
-definitions followed by one or more expressions. It is an error for a @svar{keyword} to
-appear more than once in the list of keywords being bound.
-
-Semantics: The @svar{body} is expanded in the syntactic environment obtained by extending
-the syntactic environment of the @code{let-syntax} expression with macros whose keywords are
-the @svar{keyword}s, bound to the specified transformers. Each binding of a @svar{keyword} has
+is an instance of @code{syntax-rules}, and @svar{body} is a sequence
+of zero or more definitions followed by one or more expressions. It is
+an error for a @svar{keyword} to appear more than once in the list of
+keywords being bound.
+
+Semantics: The @svar{body} is expanded in the syntactic environment
+obtained by extending the syntactic environment of the @code{let-syntax}
+expression with macros whose keywords are the @svar{keyword}s, bound
+to the specified transformers. Each binding of a @svar{keyword} has
@svar{body} as its region.
@example
@@ -109,12 +115,13 @@ the @svar{keyword}s, bound to the specified transformers. Each binding of a @sva
Syntax: Same as for @code{let-syntax}.
-Semantics: The @svar{body} is expanded in the syntactic environment obtained by extending
-the syntactic environment of the @code{letrec-syntax} expression with macros whose keywords
-are the @svar{keyword}s, bound to the specified transformers. Each binding of a @svar{keyword}
-has the @svar{transformer spec}s as well as the @svar{body} within its region, so the transformers
-can transcribe expressions into uses of the macros introduced by the @code{letrec-syntax}
-expression.
+Semantics: The @svar{body} is expanded in the syntactic
+environment obtained by extending the syntactic environment of the
+@code{letrec-syntax} expression with macros whose keywords are the
+@svar{keyword}s, bound to the specified transformers. Each binding of a
+@svar{keyword} has the @svar{transformer spec}s as well as the @svar{body}
+within its region, so the transformers can transcribe expressions into
+uses of the macros introduced by the @code{letrec-syntax} expression.
@example
(letrec-syntax
@@ -155,15 +162,16 @@ A @svar{transformer spec} has one of the following forms:
@svar{syntax rule} @dots{}@code{)}
@end display
-Syntax: It is an error if any of the @svar{pattern literal}s, or the @svar{ellipsis} in the second form, is
-not an identifier. It is also an error if @svar{syntax rule} is not of the form
+Syntax: It is an error if any of the @svar{pattern literal}s, or the
+@svar{ellipsis} in the second form, is not an identifier. It is also an
+error if @svar{syntax rule} is not of the form
@display
(@svar{pattern} @svar{template})
@end display
-The @svar{pattern} in a @svar{syntax rule} is a list @svar{pattern} whose first
-element is an identifier.
+The @svar{pattern} in a @svar{syntax rule} is a list @svar{pattern} whose
+first element is an identifier.
A @svar{pattern} is either an identifier, a constant, or one of the following
@@ -177,8 +185,8 @@ A @svar{pattern} is either an identifier, a constant, or one of the following
@code{#(}@svar{pattern} @dots{} @svar{pattern} @svar{ellipsis} @svar{pattern} @dots{}@code{)}
@end display
-and a @svar{template} is either an identifier, a
-constant, or one of the following
+and a @svar{template} is either an identifier, a constant, or one of the
+following
@display
@code{(}@svar{element} @dots{}@code{)}
@@ -187,40 +195,49 @@ constant, or one of the following
@code{#(}@svar{element} @dots{}@code{)}
@end display
-where an @svar{element} is a @svar{template} optionally followed by an @svar{ellipsis}.
-An @svar{ellipsis} is the identifier specified in the second form of @code{syntax-rules}, or the default
-identifier @code{@dots{}} (three consecutive periods) otherwise.
-
-Semantics: An instance of @code{syntax-rules} produces a new macro transformer by specifying a
-sequence of hygienic rewrite rules. A use of a macro whose keyword is associated with a
-transformer specified by @code{syntax-rules} is matched against the patterns contained in the
-@svar{syntax rule}s, beginning with the leftmost @svar{syntax rule}. When a match is found, the
-macro use is transcribed hygienically according to the template.
-
-An identifier appearing within a @svar{pattern} can be an underscore (@code{_}), a literal identifier
-listed in the list of @svar{pattern literal}s, or the @svar{ellipsis}. All other identifiers appearing
-within a @svar{pattern} are @dfn{pattern variables}.
-
-The keyword at the beginning of the pattern in a @svar{syntax rule} is not involved in the
-matching and is considered neither a pattern variable nor a literal identifier.
-
-Pattern variables match arbitrary input elements and are used to refer to elements of
-the input in the template. It is an error for the same pattern variable to appear more
-than once in a @svar{pattern}.
-
-Underscores also match arbitrary input elements but are not pattern variables and so
-cannot be used to refer to those elements. If an underscore appears in the
-@svar{pattern literal}s list, then that takes precedence and underscores in the @svar{pattern} match as
+where an @svar{element} is a @svar{template} optionally followed by
+an @svar{ellipsis}. An @svar{ellipsis} is the identifier specified
+in the second form of @code{syntax-rules}, or the default identifier
+@code{@dots{}} (three consecutive periods) otherwise.
+
+Semantics: An instance of @code{syntax-rules} produces a new macro
+transformer by specifying a sequence of hygienic rewrite rules. A use
+of a macro whose keyword is associated with a transformer specified by
+@code{syntax-rules} is matched against the patterns contained in the
+@svar{syntax rule}s, beginning with the leftmost @svar{syntax rule}. When
+a match is found, the macro use is transcribed hygienically according
+to the template.
+
+An identifier appearing within a @svar{pattern} can be an underscore
+(@code{_}), a literal identifier listed in the list of @svar{pattern
+literal}s, or the @svar{ellipsis}. All other identifiers appearing within
+a @svar{pattern} are @dfn{pattern variables}.
+
+The keyword at the beginning of the pattern in a @svar{syntax rule}
+is not involved in the matching and is considered neither a pattern
+variable nor a literal identifier.
+
+Pattern variables match arbitrary input elements and are used to refer
+to elements of the input in the template. It is an error for the same
+pattern variable to appear more than once in a @svar{pattern}.
+
+Underscores also match arbitrary input elements but are not pattern
+variables and so cannot be used to refer to those elements. If an
+underscore appears in the @svar{pattern literal}s list, then that
+takes precedence and underscores in the @svar{pattern} match as
literals. Multiple underscores can appear in a @svar{pattern}.
-Identifiers that appear in @code{(}@svar{pattern literal} @dots{}@code{)} are interpreted as literal identifiers to be
-matched against corresponding elements of the input. An element in the input matches
-a literal identifier if and only if it is an identifier and either both its occurrence in the
-macro expression and its occurrence in the macro definition have the same lexical
-binding, or the two identifiers are the same and both have no lexical binding.
+Identifiers that appear in @code{(}@svar{pattern literal} @dots{}@code{)}
+are interpreted as literal identifiers to be matched against corresponding
+elements of the input. An element in the input matches a literal
+identifier if and only if it is an identifier and either both its
+occurrence in the macro expression and its occurrence in the macro
+definition have the same lexical binding, or the two identifiers are
+the same and both have no lexical binding.
-A subpattern followed by @svar{ellipsis} can match zero or more elements of the input,
-unless @svar{ellipsis} appears in the @svar{pattern literal}s, in which case it is matched as a literal.
+A subpattern followed by @svar{ellipsis} can match zero or more elements
+of the input, unless @svar{ellipsis} appears in the @svar{pattern
+literal}s, in which case it is matched as a literal.
More formally, an input expression @var{E} matches a pattern @var{P}
if and only if:
@@ -278,14 +295,13 @@ matches @var{P@sub{x}}; or
match @var{P@sub{1}} through @var{P@sub{n}}; or
@item
-@var{P} is of the form
-@code{#(}@var{P@sub{1}} @dots{} @var{P@sub{k}} @var{P@sub{e}}
-@svar{ellipsis} @var{P@sub{m+1}} @dots{} @var{P@sub{n}}@code{)} where @var{E}
-is a vector of @var{n} elements the first @var{k} of which match
-@var{P@sub{1}} through @var{P@sub{k}}, whose next @var{m} @minus{}
-@var{k} elements each match @var{P@sub{e}}, and whose remaining
-@var{n} @minus{} @var{m} elements match @var{P@sub{m+1}} through
-@var{P@sub{n}}; or
+@var{P} is of the form @code{#(}@var{P@sub{1}} @dots{} @var{P@sub{k}}
+@var{P@sub{e}} @svar{ellipsis} @var{P@sub{m+1}} @dots{}
+@var{P@sub{n}}@code{)} where @var{E} is a vector of @var{n} elements the
+first @var{k} of which match @var{P@sub{1}} through @var{P@sub{k}}, whose
+next @var{m} @minus{} @var{k} elements each match @var{P@sub{e}}, and
+whose remaining @var{n} @minus{} @var{m} elements match @var{P@sub{m+1}}
+through @var{P@sub{n}}; or
@item
@var{P} is a constant and @var{E} is equal to @var{P} in the sense of
@@ -293,28 +309,33 @@ the @code{equal?} procedure.
@end itemize
-It is an error to use a macro keyword, within the scope of its binding, in an expression
-that does not match any of the patterns.
+It is an error to use a macro keyword, within the scope of its binding,
+in an expression that does not match any of the patterns.
When a macro use is transcribed according to the template of the matching
-@svar{syntax rule}, pattern variables that occur in the template are replaced by the elements they
-match in the input. Pattern variables that occur in subpatterns followed by one or more
-instances of the identifier @svar{ellipsis} are allowed only in subtemplates that are followed
-by as many instances of @svar{ellipsis}. They are replaced in the output by all of the elements
-they match in the input, distributed as indicated. It is an error if the output cannot be
-built up as specified.
-
-Identifiers that appear in the template but are not pattern variables or the identifier
-@svar{ellipsis} are inserted into the output as literal identifiers. If a literal identifier is inserted
-as a free identifier then it refers to the binding of that identifier within whose scope the
-instance of @code{syntax-rules} appears. If a literal identifier is inserted as a bound identifier
-then it is in effect renamed to prevent inadvertent captures of free identifiers.
-
-A template of the form @code{(}@svar{ellipsis} @svar{template}@code{)} is identical to @svar{template}, except that
-ellipses within the template have no special meaning. That is, any ellipses contained
-within @svar{template} are treated as ordinary identifiers. In particular, the template
-@code{(}@svar{ellipsis} @svar{ellipsis}@svar{)} produces a single @svar{ellipsis}. This allows syntactic abstractions to
-expand into code containing ellipses.
+@svar{syntax rule}, pattern variables that occur in the template are
+replaced by the elements they match in the input. Pattern variables that
+occur in subpatterns followed by one or more instances of the identifier
+@svar{ellipsis} are allowed only in subtemplates that are followed by
+as many instances of @svar{ellipsis}. They are replaced in the output by
+all of the elements they match in the input, distributed as indicated. It
+is an error if the output cannot be built up as specified.
+
+Identifiers that appear in the template but are not pattern variables or
+the identifier @svar{ellipsis} are inserted into the output as literal
+identifiers. If a literal identifier is inserted as a free identifier
+then it refers to the binding of that identifier within whose scope
+the instance of @code{syntax-rules} appears. If a literal identifier is
+inserted as a bound identifier then it is in effect renamed to prevent
+inadvertent captures of free identifiers.
+
+A template of the form @code{(}@svar{ellipsis} @svar{template}@code{)}
+is identical to @svar{template}, except that ellipses within the
+template have no special meaning. That is, any ellipses contained within
+@svar{template} are treated as ordinary identifiers. In particular,
+the template @code{(}@svar{ellipsis} @svar{ellipsis}@svar{)} produces
+a single @svar{ellipsis}. This allows syntactic abstractions to expand
+into code containing ellipses.
@example
(define-syntax be-like-begin
@@ -330,8 +351,8 @@ expand into code containing ellipses.
@end example
As an example, if @code{let} and @code{cond} are defined as in
-@ref{Derived expression types formal} then
-they are hygienic (as required) and the following is not an error.
+@ref{Derived expression types formal} then they are hygienic (as
+required) and the following is not an error.
@example
(let ((=> #f))
@@ -340,8 +361,8 @@ they are hygienic (as required) and the following is not an error.
The macro transformer for @code{cond} recognizes @code{=>} as a local
variable, and hence an expression, and not as the base identifier
-@code{=>}, which the macro transformer treats as a syntactic
-keyword. Thus the example expands into
+@code{=>}, which the macro transformer treats as a syntactic keyword. Thus
+the example expands into
@example
(let ((=> #f))
@@ -365,13 +386,14 @@ which would result in an invalid procedure call.
@deffn syntax syntax-error @svar{message} @svar{args}@dots{}
-syntax-error behaves similarly to error (@ref{Exceptions}) except that implementations with an
-expansion pass separate from evaluation should signal an error as soon as @code{syntax-error}
-is expanded. This can be used as a @code{syntax-rules} @svar{template} for a @svar{pattern} that is an
-invalid use of the macro, which can provide more descriptive error messages.
-@svar{message} is a string literal, and @svar{args} arbitrary expressions providing additional
-information. Applications cannot count on being able to catch syntax errors with
-exception handlers or guards.
+syntax-error behaves similarly to error (@ref{Exceptions}) except that
+implementations with an expansion pass separate from evaluation should
+signal an error as soon as @code{syntax-error} is expanded. This can be
+used as a @code{syntax-rules} @svar{template} for a @svar{pattern} that is
+an invalid use of the macro, which can provide more descriptive error
+messages. @svar{message} is a string literal, and @svar{args} arbitrary
+expressions providing additional information. Applications cannot count on
+being able to catch syntax errors with exception handlers or guards.
@example
(define-syntax simple-let
