13.4 Reading

See The Reader for information on the default reader and Reading via an Extension for the protocol of read.

See The Reader for information on the default reader in read-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.

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, the read/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 uses read/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.

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.

Changed in version 6.2 of package base: Adjusted use of readtable in the same way as for read/recursive.

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 the get-info function (if any) exported by the same module. The arguments to get-info are the same as for read as described in Reading via an Extension. 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. If no get-info function is exported, read-language returns #f.

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.

Added in version 6.3.0.5 of package base.

Added in version 6.3.0.5 of package base.

Added in version 8.4.0.8 of package base.

Added in version 7.3.0.5 of package base.

Added in version 6.3.0.5 of package base.

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 #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—instead of keeping unparsed compiled code in memory—when the PLT_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.

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-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.