13.4 Reading
procedure
in : input-port? = (current-input-port)
See The Reader for information on the default reader.
procedure
(read-syntax [source-name in]) → (or/c syntax? eof-object?)
source-name : any/c = (object-name in) in : input-port? = (current-input-port)
See The Reader for information on the default reader in read-syntax mode.
procedure
(read/recursive [in start readtable graph?]) → any
in : input-port? = (current-input-port) start : (or/c char? #f) = #f readtable : (or/c readtable? #f) = (current-readtable) graph? : any/c = #t
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.
procedure
(read-syntax/recursive [ source-name in start readtable graph?]) → any source-name : any/c = (object-name in) in : input-port? = (current-input-port) start : (or/c char? #f) = #f readtable : (or/c readtable? #f) = (current-readtable) graph? : any/c = #t
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.
procedure
(read-language [in fail-thunk]) → (any/c any/c . -> . any)
in : input-port? = (current-input-port) fail-thunk : (-> any) = (lambda () (error ...))
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.
Examples: | ||||
|
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.
parameter
(read-case-sensitive on?) → void? on? : any/c
parameter
(read-square-bracket-as-paren on?) → void? on? : any/c
parameter
(read-curly-brace-as-paren on?) → void? on? : any/c
parameter
(read-accept-box on?) → void? on? : any/c
parameter
(read-accept-compiled on?) → void? on? : any/c
parameter
(read-accept-bar-quote on?) → void? on? : any/c
parameter
(read-accept-graph on?) → void? on? : any/c
parameter
(read-decimal-as-inexact on?) → void? on? : any/c
parameter
(read-accept-dot on?) → void? on? : any/c
parameter
(read-accept-infix-dot on?) → void? on? : any/c
parameter
(read-accept-quasiquote on?) → void? on? : any/c
parameter
(read-accept-reader on?) → void? on? : any/c
parameter
(read-accept-lang on?) → void? on? : any/c
parameter
(current-readtable) → (or/c readtable? #f)
(current-readtable readtable) → void? readtable : (or/c readtable? #f)
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.
parameter
(current-reader-guard) → (any/c . -> . any)
(current-reader-guard proc) → void? proc : (any/c . -> . any)
parameter
→ (or/c #f #t (and/c path? complete-path?)) (read-on-demand-source mode) → void? mode : (or/c #f #t (and/c path? complete-path?))
A #f value for read-on-demand-source disables lazy
parsing of compiled code. A #t value enables lazy parsing. A
path value furthers enable lazy retrieval from disk—
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.
procedure
(port-read-handler in) →
(case-> (input-port? . -> . any) (input-port? any/c . -> . any)) in : input-port? (port-read-handler in proc) → void? in : input-port?
proc :
(case-> (input-port? . -> . any) (input-port? any/c . -> . any))
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.