4 Reader Helpers

4.1 Raising exn:fail:read

(require syntax/readerr)

Source-location information is added to the error message using the last five arguments (if the error-print-source-location parameter is set to #t). The source argument is an arbitrary value naming the source location – usually a file path string. Each of the line, pos arguments is #f or a positive exact integer representing the location within source-name (as much as known), col is a non-negative exact integer for the source column (if known), and span is #f or a non-negative exact integer for an item range starting from the indicated position.

The usual location values should point at the beginning of whatever it is you were reading, and the span usually goes to the point the error was discovered.

4.2 Module Reader

(require syntax/module-reader)

The syntax/module-reader language provides support for defining #lang readers. In its simplest form, the only thing that is needed in the body of a syntax/module-reader is the name of the module that will be used in the language position of read modules; using keywords, the resulting readers can be customized in a number of ways.

That is, a module something/lang/reader implemented as

(module reader syntax/module-reader

module-path)

creates a reader that converts #lang something into

(module name-id module-path

....)

where name-id is derived from the name of the port used by the reader.

For example, scheme/base/lang/reader is implemented as

(module reader syntax/module-reader

scheme/base)

The reader functions can be customized in a number of ways, using keyword markers in the syntax of the reader module. A #:read and #:read-syntax keywords can be used to specify functions other than read and read-syntax to perform the reading. For example, you can implement a Honu reader using:

(module reader syntax/module-reader

honu

#:read read-honu

#:read-syntax read-honu-syntax)

Similarly, the #:info keyword supplies a procedure to be used by a get-info export (see read-language). The procedure produced by info-expr should consume two arguments: a key symbol and a default info-getting procedure (to be called with the key for default handling). If #:info is not supplied, the default info-getting procedure is used.

You can also use the (optional) module body forms to provide more definitions that might be needed to implement your reader functions. For example, here is a case-insensitive reader for the scheme/base language:

(module reader syntax/module-reader

scheme/base

#:read (wrap read) #:read-syntax (wrap read-syntax)

(define ((wrap reader) . args)

(parameterize ([read-case-sensitive #f]) (apply reader args))))

In many cases, however, the standard read and read-syntax are fine, as long as you can customize the dynamic context they’re invoked at. For this, #:wrapper1 can specify a function that can control the dynamic context in which the reader functions are called. It should evaluate to a function that consumes a thunk and invokes it in the right context. Here is an alternative definition of the case-insensitive language using #:wrapper1:

(module reader syntax/module-reader

scheme/base

#:wrapper1 (lambda (t)

(parameterize ([read-case-sensitive #f])

(t))))

Note that using a readtable, you can implement languages that are extensions of plain S-expressions.

In addition to this wrapper, there is also #:wrapper2 that has more control over the resulting reader functions. If specified, this wrapper is handed the input port and a (one-argumet) reader function that expects the input port as an argument. This allows this wrapper to hand a different port value to the reader function, for example, it can divert the read to use different file (if given a port that corresponds to a file). Here is the case-insensitive implemented using this option:

(module reader syntax/module-reader

scheme/base

#:wrapper2 (lambda (in r)

(parameterize ([read-case-sensitive #f])

(r in))))

In some cases, the reader functions read the whole file, so there is no need to iterate them (e.g., Scribble’s read-inside and read-syntax-inside). In these cases you can specify #:whole-body-readers? as #t – the readers are expected to return a list of expressions in this case.

The at-exp, reader, and planet languages are implemented using this function.

The generated functions expect a target language description in the input stream that is provided to read-spec. The default read-spec extracts a non-empty sequence of bytes after one or more space and tab bytes, stopping at the first whitespace byte or end-of-file (whichever is first), and it produces either such a byte string or #f. If read-spec produces #f, a reader exception is raised, and path-desc-str is used as a description of the expected language form in the error message.

The reader language supplies read for read-spec. The at-exp and planet languages use the default read-spec.

The result of read-spec is converted to a module path using module-path-parser. If module-path-parser produces #f, a reader exception is raised in the same way as when read-spec produces a #f. The planet languages supply a module-path-parser that converts a byte string to a module path.

If loading the module produced by module-path-parser succeeds, then the loaded module’s read, read-syntax, or get-info export is passed to convert-read, convert-read-syntax, or convert-get-info, respectively.

The at-exp language supplies convert-read and convert-read-syntax to add @-expression support to the current readtable before chaining to the given procedures.

The procedures generated by make-meta-reader are not meant for use with the syntax/module-reader language; they are meant to be exported directly.

Repeatedly calls read on in until an end of file, collecting the results in order into lst, and derives a name-id from (object-name in). The last five arguments are used to construct the syntax object for the language position of the module. The result is roughly

  `(module ,name-id ,mod-path ,@lst)