13.4 Reading (original) (raw)
13.4 Reading🔗ℹ
Reads and returns a single datum from in. Ifin has a handler associated to it viaport-read-handler, then the handler is called. Otherwise, the default reader is used, as parameterized by thecurrent-readtable parameter, as well as many other parameters.
See The Reader for information on the default reader andReading via an Extension for the protocol of read.
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 inread-syntax mode and Reading via an Extension for the protocol of read-syntax.
Typically, line counting should be enabled for in so that source locations in syntax objects are in characters, instead of bytes. See also Counting Positions, Lines, and Columns.
See also Syntax Objects in The Racket Guide.
Similar to calling read, but normally used during the dynamic extent of read within a reader-extension procedure (seeReader-Extension Procedures). The main effect of usingread/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 thegraph? 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, including various delimiters of a built-in top-level form (such as parentheses and . for reading a hash table); 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, theread/recursive procedure can produce a special-comment value (see Special Comments) when the input stream’s first non-whitespace content parses as a comment.
See Readtables for an extended example that usesread/recursive.
Changed in version 6.2 of package base: Adjusted use of readtable to more consistently apply to the delimiters of a built-in form.
Analogous to calling read/recursive, but the resulting value encapsulates S-expression structure with source-location information. As with read/recursive, whenread-syntax/recursive is used within the dynamic extent ofread-syntax, the result fromread-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-syntaxreturns.
Using read/recursive within the dynamic extent ofread-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 ofread. In those cases, read/recursive andread-syntax/recursive produce results like read andread-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 usesread-syntax/recursive.
Changed in version 6.2 of package base: Adjusted use of readtablein the same way as forread/recursive.
Reads from in in the same way as read, but stopping as soon as a reader language (or its absence) is determined, and using the current namespace to load a reader module instead of its root namespace (if those are different).
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 defaultreadtable is used by read-language (instead of the value of current-readtable), and #reader forms (which might produce comments) are not allowed before #langor #!.
When it finds a #lang or #! specification, instead of dispatching to a read or read-syntaxfunction as read and read-syntax do,read-language dispatches to the get-infofunction (if any) exported by the same module. The arguments toget-info are the same as for readas described in Reading via an Extension. The result of theget-info function is the result ofread-language if it is a function of two arguments; ifget-info produces any other kind of result, theexn:fail:contract exception is raised. If no get-info function is exported, read-language returns #f.
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 (seethe DrRacket documentation). If no information is available for a given key, the result should be the second argument.
Examples:
> (scribble-manual-info 'color-lexer #f) #procedure:scribble-inside-lexer > (scribble-manual-info 'something-else #f) #f
The get-info function itself is applied to five arguments: the input port being read, the module path from which theget-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 andread-syntax), then the result of read-languageis #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 raisesexn: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; seeReading Symbols for more information. While a module is loaded, the parameter is set to #t (seecurrent-load).
A parameter that controls whether [ and ]are treated as parentheses, but the resulting list tagged with#%brackets. See Reading Pairs and Lists for more information.
Added in version 6.3.0.5 of package base.
A parameter that controls whether { and} are treated as parentheses, but the resulting list tagged with #%braces. See Reading Pairs and Lists for more information.
Added in version 6.3.0.5 of package base.
A parameter value that controls parsing input with sharing inread mode. See Reading Graph Structure for more information.
A parameter value that controls parsing input with sharing inread-syntax mode. See Reading Graph Structure for more information.
Added in version 8.4.0.8 of package base.
A parameter that controls parsing input numbers with a decimal point or exponent (but no explicit exactness tag). SeeReading Numbers for more information.
A parameter that controls parsing input numbers that have af, F, s, or S precision character. See Reading Numbers for more information.
Added in version 7.3.0.5 of package base.
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.
Added in version 6.3.0.5 of package base.
A parameter that controls whether #reader, #lang, or #! are allowed for selecting a parser. SeeReading via an Extension for more information.
A parameter that (along with read-accept-reader) controls whether #lang and #! are allowed for selecting a parser. 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.
Using the default parameter values ensures consistency, and it also provides safety when reading from untrusted sources, since the default values disable evaluation of arbitrary code via #lang or#reader.
A parameter whose value converts or rejects (by raising an exception) a module-path datum following #reader. SeeReading via an Extension 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-enabledis #t.
A #f value for read-on-demand-source disables lazy parsing of compiled code. A #t value enables lazy parsing. Apath value furthers enable lazy retrieval from disk—instead of keeping unparsed compiled code in memory—when thePLT_DELAY_FROM_ZO environment variable is set (to any value) on start-up.
If the file at mode as a path changes before the delayed code is parsed when lazy retrieval from disk is enabled, then the on-demand parse most likely will encounter garbage, leading to an exception.
Gets or sets the port read handler for in. The handler called to read from the port when the built-in reador read-syntax procedure is applied to the port. (The port read handler is not used for read/recursive orread-syntax/recursive.)
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 withread-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 (seemake-input-port) by treating it as a single expression, except that special-comment values (seeSpecial Comments) are treated as whitespace.
The default port read handler itself can be customized through a readtable; see Readtables for more information.