suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

General reformat, and move the new comment about #%module-begin to the end of the section

Browse Source 
svn: r17194
This commit is contained in:
Eli Barzilay 2009-12-05 02:41:35 +00:00
parent 49df9502a4
commit ac0a1dc7d8
1 changed files with 96 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
collects/syntax/scribblings/module-reader.scrbl
View File

@ -2,7 +2,8 @@
@(require "common.ss")
@(require (for-label syntax/module-reader
(only-in scribble/reader read-syntax-inside read-inside)))
(only-in scribble/reader
read-syntax-inside read-inside)))
@title[#:tag "module-reader"]{Module Reader}
@ -15,7 +16,8 @@ is the name of the module that will be used in the language position
of read modules; using keywords, the resulting readers can be
customized in a number of ways.
@defform*/subs[[(#%module-begin module-path)
@defform*/subs[
[(#%module-begin module-path)
(#%module-begin module-path reader-option ... body ....)
(#%module-begin reader-option ... body ....)]
([reader-option (code:line #:language lang-expr)
@ -41,8 +43,7 @@ as
module-path)
]
creates a reader that converts @scheme[#,(hash-lang)_something]
into
creates a reader that converts @scheme[#,(hash-lang)_something] into
@schemeblock[
(module _name-id module-path
@ -82,9 +83,9 @@ procedure (to be called with the key and default result for default
handling). If @scheme[#:info] is not supplied, the default
info-getting procedure is used.
You can also use the (optional) module @scheme[body] forms to provide more
definitions that might be needed to implement your reader functions.
For example, here is a case-insensitive reader for the
You can also use the (optional) module @scheme[body] forms to provide
more definitions that might be needed to implement your reader
functions. For example, here is a case-insensitive reader for the
@scheme[scheme/base] language:
@schemeblock[
@ -138,13 +139,6 @@ no need to iterate them (e.g., Scribble's @scheme[read-inside] and
@scheme[#:whole-body-readers?] as @scheme[#t] --- the readers are
expected to return a list of expressions in this case.
[If such whole-body reader functions return a list with a single
expression that begins with @scheme[#%module-begin], then the
@scheme[syntax/module-reader] language will not inappropriately add
another. This for backwards-compatibility with older code: having a
whole-body reader functions or wrapper functions that return a
@scheme[#%module-begin]-wrapped body is deprectaed.]
In addition, the two wrappers can return a different value than the
wrapped function. This introduces two more customization points for
the resulting readers:
@ -157,8 +151,7 @@ the resulting readers:
@schemeblock[
(module ignored syntax/module-reader
scheme/base
#:wrapper1 (lambda (t) (t) '()))
]
#:wrapper1 (lambda (t) (t) '()))]
Note that it is still performing the read, otherwise the module
loader will complain about extra expressions.}
@item{The reader function that is passed to a @scheme[#:wrapper2]
@ -198,13 +191,15 @@ expression can be useful in cases such as the above, where the base
language module is chosen based on the input. To make this more
convenient, you can omit the @scheme[module-path] and instead specify
it via a @scheme[#:language] expression. This expression can evaluate
to a datum or syntax object that is used as a language, or it can evaluate to a thunk.
In the latter case, the thunk is invoked to obtain such a datum
before reading the module body begins, in a dynamic extent where
@scheme[current-input-port] is the source input. A syntax object is converted
using @scheme[syntax->datum] when a datum is needed (for @scheme[read] instead of @scheme[read-syntax]).
Using @scheme[#:language], the last
example above can be written more concisely:
to a datum or syntax object that is used as a language, or it can
evaluate to a thunk. In the latter case, the thunk is invoked to
obtain such a datum before reading the module body begins, in a
dynamic extent where @scheme[current-input-port] is the source
input. A syntax object is converted using @scheme[syntax->datum] when
a datum is needed (for @scheme[read] instead of @scheme[read-syntax]).
Using @scheme[#:language], the last example above can be written more
concisely:
@schemeblock[
(module reader syntax/module-reader
#:language read
@ -214,6 +209,15 @@ example above can be written more concisely:
(rd in)))
(require scribble/reader))
]
Note: if such whole-body reader functions return a list with a single
expression that begins with @scheme[#%module-begin], then the
@scheme[syntax/module-reader] language will not inappropriately add
another. This for backwards-compatibility with older code: having a
whole-body reader functions or wrapper functions that return a
@scheme[#%module-begin]-wrapped body is deprectaed.
}
@ -234,7 +238,8 @@ procedures chains to another language that is specified in an input
stream.
@margin-note{The @schememodname[at-exp], @schememodname[reader], and
@schememodname[planet] languages are implemented using this function.}
@schememodname[planet] languages are implemented using this
function.}
The generated functions expect a target language description in the
input stream that is provided to @scheme[read-spec]. The default
@ -247,7 +252,8 @@ description of the expected language form in the error message.
@margin-note{The @schememodname[reader] language supplies
@scheme[read] for @scheme[read-spec]. The @schememodname[at-exp] and
@schememodname[planet] languages use the default @scheme[read-spec].}
@schememodname[planet] languages use the default
@scheme[read-spec].}
The result of @scheme[read-spec] is converted to a module path using
@scheme[module-path-parser]. If @scheme[module-path-parser] produces