12.4 Reading
Reads and returns a single
datum from
in. If
in has a handler associated to it via
port-read-handler, then the handler is called. Otherwise, the
default reader is used, as parameterized by the
current-readtable parameter, as well as many other
parameters.
See The Reader for information on the default reader.
Like
read, but produces a
syntax object with
source-location information. The
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 The Reader for information on the default reader in
read-syntax mode.
Similar to calling
read, but normally used during the dynamic
extent of
read within a reader-extension procedure (see
Reader-Extension Procedures). The main effect of using
read/recursive instead of
read is that
graph-structure annotations (see
Reading Graph Structure) in the
nested read are considered part of the overall read, at least when the
graph? argument is true; since the result is wrapped in a
placeholder, however, it is not directly inspectable.
If start is provided and not #f, it is effectively
prefixed to the beginning of in’s stream for the read. (To
prefix multiple characters, use input-port-append.)
The 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 current-readtable parameter. A reader
macro might call read/recursive with a character and
readtable to effectively invoke the readtable’s behavior for the
character. If readtable is #f, the default
readtable is used for top-level parsing.
When graph? is #f, graph structure annotations in
the read datum are local to the datum.
When called within the dynamic extent of read, the
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 Special Comments)
when the input stream’s first non-whitespace content parses as a
comment. The result is end-of-file when 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 Reader-Extension Procedures) for the
same outermost read, it will be replaced with the actual read
value before the outermost read returns.
See Readtables for an extended example that uses
read/recursive.
Analogous to calling
read/recursive, but the resulting value
encapsulates S-expression structure with source-location
information. As with
read/recursive, when
read-syntax/recursive is used within the dynamic extent of
read-syntax, the result from
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
read-syntax
returns.
Using read/recursive within the dynamic extent of
read-syntax does not allow graph structure for reading to be
included in the outer read-syntax parsing, and neither does
using read-syntax/recursive within the dynamic extent of
read. In those cases, read/recursive and
read-syntax/recursive produce results like read and
read-syntax, except that a special-comment value is returned
when the input stream starts with a comment (after whitespace).
See Readtables for an extended example that uses
read-syntax/recursive.
Reads from
in in the same way as
read, but stopping as
soon as a
reader language (or its absence) is determined.
A reader language is specified by #lang or
#! (see Reading via an Extension) at the beginning of the
input, though possibly after comment forms. The default
readtable is used by read-language (instead of the
value of current-readtable), and #reader forms
(which might produce comments) are not allowed before #lang
or #!.
See also Source-Handling Configuration in The Racket Guide.
When it finds a #lang or #! specification, instead
of dispatching to a read or read-syntax
function as read and read-syntax do,
read-language dispatches to a get-info
function (if any) exported by the same module. The result of the
get-info function is the result of
read-language if it is a function of two arguments; if
get-info produces any other kind of result, the
exn:fail:contract exception is raised.
The function produced by get-info reflects information
about the expected syntax of the input stream. The first argument to the
function serves as a key on such information; acceptable keys and the
interpretation of results is up to external tools, such as DrRacket.
If no information is available for a given key, the result should be
the second argument.
The get-info function itself is applied to five
arguments: the input port being read, the module path from which the
get-info function was extracted, and the source line
(positive exact integer or #f), column (non-negative exact
integer or #f), and position (positive exact integer or
#f) of the start of the #lang or #!
form. The get-info function may further read from the
given input port to determine its result, but it should read no
further than necessary. The get-info function should
not read from the port after returning a function.
If in starts with a reader language specification but
the relevant module does not export get-info (but
perhaps does export read and
read-syntax), then the result of read-language
is #f.
If in has a #lang or #! specification,
but parsing and resolving the specification raises an exception, the
exception is propagated by read-language. Having at least
#l or #! (after comments and whitespace) counts as
starting a #lang or #! specification.
If in does not specify a reader language with
#lang or #!, then fail-thunk is
called. The default fail-thunk raises
exn:fail:read or exn:fail:read:eof.
A parameter that controls parsing and printing of symbols. When this
parameter’s value is
#f, the reader case-folds symbols (e.g.,
producing
'hi when the input is any one of
hi,
Hi,
HI, or
hI). The parameter also
affects the way that
write prints symbols containing
uppercase characters; if the parameter’s value is
#f, then
symbols are printed with uppercase characters quoted by a
\ or
|. The parameter’s value is overridden by
quoting
\ or
| vertical-bar quotes and the
#cs and
#ci prefixes; see
Reading Symbols for more information. While a module is
loaded, the parameter is set to
#t (see
current-load).
A parameter that controls whether
[ and
]
are treated as parentheses. See
Reading Pairs and Lists for more
information.
A parameter that controls whether
{ and
}
are treated as parentheses. See
Reading Pairs and Lists for more
information.
A parameter that controls parsing
#& input. See
Reading Boxes for more information.
A parameter that controls parsing input numbers with a decimal point
or exponent (but no explicit exactness tag). See
Reading Numbers for more information.
A parameter that controls parsing input with a dot, which is normally
used for literal cons cells. See
Reading Pairs and Lists for more
information.
A parameter that controls parsing input with two dots to trigger infix
conversion. See
Reading Pairs and Lists for more information.
A parameter that controls whether
#reader,
#lang,
or
#! are allowed for selecting a parser. See
Reading via an Extension for more information.
A parameter whose value converts or rejects (by raising an exception)
a module-path datum following
#reader. See
Reading via an Extension for more information.
A parameter whose value determines a readtable that
adjusts the parsing of S-expression input, where
#f implies the
default behavior. See
Readtables for more information.
A parameter that enables lazy parsing of compiled code, so that
closure bodies and syntax objects are extracted (and validated) from
marshaled compiled code on demand. Normally, this parameter is set by
the default
load handler when
load-on-demand-enabled
is
#t.
Even when parsing is delayed, compiled code is loaded into memory. If
the PLT_DELAY_FROM_ZO environment variable is set
(to any value) on start-up, however, even loading from disk is
delayed. If the file at path changes before the delayed code or
syntax object is demanded, the read-on-demand most likely will
encounter garbage, leading to an exception.
A port read handler is applied to either one argument or two
arguments:
A single argument is supplied when the port is used
with read; the argument is the port being read. The return
value is the value that was read from the port (or end-of-file).
Two arguments are supplied when the port is used with
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 Racket expressions with
Racket’s built-in parser (see The Reader). It handles a
special result from a custom input port (see
make-custom-input-port) by treating it as a single expression,
except that special-comment values (see
Special Comments) are treated as whitespace.
The default port read handler itself can be customized through a
readtable; see Readtables for more information.