272 lines
11 KiB
Racket
272 lines
11 KiB
Racket
#lang scribble/doc
|
|
@require["mz.ss"]
|
|
|
|
@title{Reading}
|
|
|
|
@defproc[(read [in input-port? (current-input-port)]) any]{
|
|
|
|
Reads and returns a single @tech{datum} from @scheme[in]. If
|
|
@scheme[in] has a handler associated to it via
|
|
@scheme[port-read-handler], then the handler is called. Otherwise, the
|
|
default reader is used, as parameterized by the
|
|
@scheme[current-readtable] parameter, as well as many other
|
|
parameters.
|
|
|
|
See @secref["reader"] for information on the default reader.}
|
|
|
|
@defproc[(read-syntax [source-name any/c (object-name in)]
|
|
[in input-port? (current-input-port)])
|
|
(or/c syntax? eof-object?)]{
|
|
|
|
Like @scheme[read], but produces a @tech{syntax object} with
|
|
source-location information. The @scheme[source-name] is used as the
|
|
source field of the syntax object; it can be an arbitrary value, but
|
|
it should generally be a path for the source file.
|
|
|
|
See @secref["reader"] for information on the default reader in
|
|
@scheme[read-syntax] mode.}
|
|
|
|
@defproc[(read/recursive [in input-port? (current-input-port)]
|
|
[start (or/c character? false/c) #f]
|
|
[readtable readtable? (current-readtable)]
|
|
[graph? any/c #f])
|
|
any]{
|
|
|
|
Similar to calling @scheme[read], but normally used during the dynamic
|
|
extent of @scheme[read] within a reader-extension procedure (see
|
|
@secref["reader-procs"]). The main effect of using
|
|
@scheme[read/recursive] instead of @scheme[read] is that
|
|
graph-structure annotations (see @secref["parse-graph"]) in the
|
|
nested read are considered part of the overall read, at least when the
|
|
@scheme[graph?] argument is true; since the result is wrapped in a
|
|
placeholder, however, it is not directly inspectable.
|
|
|
|
If @scheme[start] is provided and not @scheme[#f], it is effectively
|
|
prefixed to the beginning of @scheme[in]'s stream for the read. (To
|
|
prefix multiple characters, use @scheme[input-port-append].)
|
|
|
|
The @scheme[readtable] argument is used for top-level parsing to
|
|
satisfy the read request; recursive parsing within the read (e.g., to
|
|
read the elements of a list) instead uses the current readtable as
|
|
determined by the @scheme[current-readtable] parameter. A reader
|
|
macro might call @scheme[read/recursive] with a character and
|
|
readtable to effectively invoke the readtable's behavior for the
|
|
character. If @scheme[readtable] is @scheme[#f], the default
|
|
readtable is used for top-level parsing.
|
|
|
|
When @scheme[graph?] is @scheme[#f], graph structure annotations in
|
|
the read datum are local to the datum.
|
|
|
|
When called within the dynamic extent of @scheme[read], the
|
|
@scheme[read/recursive] procedure produces either an opaque
|
|
placeholder value, a special-comment value, or an end-of-file. The
|
|
result is a special-comment value (see @secref["special-comments"])
|
|
when the input stream's first non-whitespace content parses as a
|
|
comment. The result is end-of-file when @scheme[read/recursive]
|
|
encounters an end-of-file. Otherwise, the result is a placeholder that
|
|
protects graph references that are not yet resolved. When this
|
|
placeholder is returned within an S-expression that is produced by any
|
|
reader-extension procedure (see @secref["reader-procs"]) for the
|
|
same outermost @scheme[read], it will be replaced with the actual read
|
|
value before the outermost @scheme[read] returns.
|
|
|
|
See @secref["readtables"] for an extended example that uses
|
|
@scheme[read/recursive].}
|
|
|
|
@defproc[(read-syntax/recursive [source-name any/c (object-name in)]
|
|
[in input-port? (current-input-port)]
|
|
[start (or/c character? false/c) #f]
|
|
[readtable readtable? (current-readtable)]
|
|
[graph? any/c #f])
|
|
any]{
|
|
|
|
Analogous to calling @scheme[read/recursive], but the resulting value
|
|
encapsulates S-expression structure with source-location
|
|
information. As with @scheme[read/recursive], when
|
|
@scheme[read-syntax/recursive] is used within the dynamic extent of
|
|
@scheme[read-syntax], the result of from
|
|
@scheme[read-syntax/recursive] is either a special-comment value,
|
|
end-of-file, or opaque graph-structure placeholder (not a syntax
|
|
object). The placeholder can be embedded in an S-expression or syntax
|
|
object returned by a reader macro, etc., and it will be replaced with
|
|
the actual syntax object before the outermost @scheme[read-syntax]
|
|
returns.
|
|
|
|
Using @scheme[read/recursive] within the dynamic extent of
|
|
@scheme[read-syntax] does not allow graph structure for reading to be
|
|
included in the outer @scheme[read-syntax] parsing, and neither does
|
|
using @scheme[read-syntax/recursive] within the dynamic extent of
|
|
@scheme[read]. In those cases, @scheme[read/recursive] and
|
|
@scheme[read-syntax/recursive] produce results like @scheme[read] and
|
|
@scheme[read-syntax], except that a special-comment value is returned
|
|
when the input stream starts with a comment (after whitespace).
|
|
|
|
See @secref["readtables"] for an extended example that uses
|
|
@scheme[read-syntax/recursive].}
|
|
|
|
|
|
@defboolparam[read-case-sensitive on?]{
|
|
|
|
A parameter that controls parsing and printing of symbols. When this
|
|
parameter's value is @scheme[#f], the reader case-folds symbols (e.g.,
|
|
producing @scheme['hi] when the input is any one of \litchar{hi},
|
|
@litchar{Hi}, @litchar{HI}, or @litchar{hI}). The parameter also
|
|
affects the way that @scheme[write] prints symbols containing
|
|
uppercase characters; if the parameter's value is @scheme[#f], then
|
|
symbols are printed with uppercase characters quoted by a
|
|
@litchar["\\"] or @litchar["|"]. The parameter's value is overridden by
|
|
quoting @litchar["\\"] or @litchar["|"] vertical-bar quotes and the
|
|
@litchar{#cs} and @litchar{#ci} prefixes; see
|
|
@secref["parse-symbol"] for more information. While a module is
|
|
loaded, the parameter is set to @scheme[#t] (see
|
|
@scheme[current-load]).}
|
|
|
|
@defboolparam[read-square-bracket-as-paren on?]{
|
|
|
|
A parameter that controls whether @litchar["["] and @litchar["]"]
|
|
are treated as parentheses. See @secref["parse-pair"] for more
|
|
information.}
|
|
|
|
@defboolparam[read-curly-brace-as-paren on?]{
|
|
|
|
A parameter that controls whether @litchar["{"] and @litchar["}"]
|
|
are treated as parentheses. See @secref["parse-pair"] for more
|
|
information.}
|
|
|
|
@defboolparam[read-accept-box on?]{
|
|
|
|
A parameter that controls parsing @litchar{#&} input. See
|
|
@secref["parse-box"] for more information.}
|
|
|
|
@defboolparam[read-accept-compiled on?]{
|
|
|
|
A parameter that controls parsing @litchar{#~} compiled input. See
|
|
@secref["reader"] and @scheme[current-compile] for more
|
|
information.}
|
|
|
|
@defboolparam[read-accept-bar-quote on?]{
|
|
|
|
A parameter that controls parsing and printing of @litchar["|"] in
|
|
symbols. See @secref["parse-symbol"] and @secref["printing"] for
|
|
more information.}
|
|
|
|
@defboolparam[read-accept-graph on?]{
|
|
|
|
A parameter value that controls parsing input with sharing. See
|
|
@secref["parse-graph"] for more information.}
|
|
|
|
@defboolparam[read-decimal-as-inexact on?]{
|
|
|
|
A parameter that controls parsing input numbers with a decimal point
|
|
or exponent (but no explicit exactness tag). See
|
|
@secref["parse-number"] for more information.}
|
|
|
|
@defboolparam[read-accept-dot on?]{
|
|
|
|
A parameter that controls parsing input with a dot, which is normally
|
|
used for literal cons cells. See @secref["parse-pair"] for more
|
|
information.}
|
|
|
|
@defboolparam[read-accept-infix-dot on?]{
|
|
|
|
A parameter that controls parsing input with two dots to trigger infix
|
|
conversion. See @secref["parse-pair"] for more information.}
|
|
|
|
@defboolparam[read-accept-quasiquote on?]{
|
|
|
|
A parameter that controls parsing input with @litchar{`} or
|
|
@litchar{,} which is normally used for @scheme[quasiquote],
|
|
@scheme[unquote], and @scheme[unquote-splicing] abbreviations. See
|
|
@secref["parse-quote"] for more information.}
|
|
|
|
@defboolparam[read-accept-reader on?]{
|
|
|
|
A parameter that controls whether @litchar{#reader} is allowed for
|
|
selecting a parser. See @secref["parse-reader"] for more
|
|
information.}
|
|
|
|
@defparam[current-reader-guard proc (any/c . -> . any)]{
|
|
|
|
A parameter whose value converts or rejects (by raising an exception)
|
|
a module-path datum following @litchar{#reader}. See
|
|
@secref["parse-reader"] for more information.}
|
|
|
|
|
|
@defparam[current-readtable readtable (or/c readtable? false/c)]{
|
|
|
|
A parameter whose value determines a readtable that
|
|
adjusts the parsing of S-expression input, where @scheme[#f] implies the
|
|
default behavior. See @secref["readtables"] for more information.}
|
|
|
|
@defproc*[([(port-read-handler [in input-port?]) (case->
|
|
(input-port? . -> . any)
|
|
(input-port? any/c . -> . any))]
|
|
[(port-read-handler [in input-port?]
|
|
[proc (case->
|
|
(input-port? . -> . any)
|
|
(input-port? any/c . -> . any))])
|
|
void?])]{
|
|
|
|
Gets or sets the @deftech{port read handler} for @scheme[in]. The
|
|
handler called to read from the port when the built-in @scheme[read]
|
|
or @scheme[read-syntax] procedure is applied to the port. (The
|
|
port read handler is not used for @scheme[read/recursive] or
|
|
@scheme[read-syntax/recursive].)
|
|
|
|
A port read handler is applied to either one argument or two
|
|
arguments:
|
|
|
|
@itemize{
|
|
|
|
@item{A single argument is supplied when the port is used
|
|
with @scheme[read]; the argument is the port being read. The return
|
|
value is the value that was read from the port (or end-of-file).}
|
|
|
|
@item{Two arguments are supplied when the port is used with
|
|
@scheme[read-syntax]; the first argument is the port being read, and
|
|
the second argument is a value indicating the source. The return
|
|
value is a syntax object that was read from the port (or end-of-file).}
|
|
|
|
}
|
|
|
|
The default port read handler reads standard Scheme expressions with
|
|
Scheme's built-in parser (see @secref["reader"]). It handles a
|
|
special result from a custom input port (see
|
|
@scheme[make-custom-input-port]) by treating it as a single expression,
|
|
except that special-comment values (see
|
|
@secref["special-comments"]) are treated as whitespace.
|
|
|
|
The default port read handler itself can be customized through a
|
|
readtable; see @secref["readtables"] for more information.}
|
|
|
|
|
|
@defproc[(read-honu [in input-port? (current-input-port)]) any]{
|
|
|
|
Like @scheme[read], but for Honu mode (see @secref["parse-honu"]).}
|
|
|
|
@defproc[(read-honu-syntax [source-name any/c (object-name in)]
|
|
[in input-port? (current-input-port)])
|
|
(or/c syntax? eof-object?)]{
|
|
|
|
Like @scheme[read-syntax], but for Honu mode (see
|
|
@secref["parse-honu"]).}
|
|
|
|
@defproc[(read-honu/recursive [in input-port? (current-input-port)]
|
|
[start (or/c character? false/c) #f]
|
|
[readtable readtable? (current-readtable)]
|
|
[graph? any/c #f])
|
|
any]{
|
|
|
|
Like @scheme[read/recursive], but for Honu mode (see
|
|
@secref["parse-honu"]).}
|
|
|
|
@defproc[(read-honu-syntax/recursive [source-name any/c (object-name in)]
|
|
[in input-port? (current-input-port)]
|
|
[start (or/c character? false/c) #f]
|
|
[readtable readtable? (current-readtable)]
|
|
[graph? any/c #f])
|
|
any]{
|
|
|
|
Like @scheme[read-syntax/recursive], but for Honu mode (see
|
|
@secref["parse-honu"]).}
|