► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

► | 13 | Input and Output

13.1 | Ports
13.2 | Byte and String Input
13.3 | Byte and String Output
13.4 | Reading
13.5 | Writing
13.6 | Pretty Printing
13.7 | Reader Extension
13.8 | Printer Extension
13.9 | Serialization
13.10 | Fast-Load Serialization
13.11 | Cryptographic Hashing

▼ | 13.7 | Reader Extension

13.7.1 | Readtables
13.7.2 | Reader-Extension Procedures
13.7.3 | Special Comments

top ← prev up next →

##### 13.7.2`` Reader-Extension Procedures

Calls to reader extension procedures can be triggered through read, read/recursive, or read-syntax. In addition, a special-read procedure can be triggered by calls to read-char-or-special, or by the context of read-bytes-avail!, peek-bytes-avail!*, read-bytes-avail!, and peek-bytes-avail!*.

Optional arities for reader-macro and special-result procedures allow them to distinguish reads via read, etc., from reads via read-syntax, etc. (where the source value is #f and no other location information is available).

When a reader-extension procedure is called in syntax-reading mode (via read-syntax, etc.), it should generally return a syntax object that has no lexical context (e.g., a syntax object created using datum->syntax with #f as the first argument and with the given location information as the third argument). Another possible result is a special-comment value (see Special Comments). If the procedure’s result is not a syntax object and not a special-comment value, it is converted to one using datum->syntax.

When a reader-extension procedure is called in non-syntax-reading modes, it should generally not return a syntax object. If a syntax object is returned, it is converted to a plain value using syntax->datum.

In either context, when the result from a reader-extension procedure is a special-comment value (see Special Comments), then read, read-syntax, etc. treat the value as a delimiting comment and otherwise ignore it.

Also, in either context, the result may be copied to prevent mutation to vectors or boxes before the read result is completed, and to support the construction of graphs with cycles. Mutable boxes, vectors, and prefab structures are copied, along with any pairs, boxes, vectors, prefab structures that lead to such mutable values, to placeholders produced by a recursive read (see read/recursive), or to references of a shared value. Graph structure (including cycles) is preserved in the copy.

top ← prev up next →