12.11 File Inclusion

A path-spec resembles a subset of the mod-path forms for require, but it specifies a file whose content need not be a module. That is, string refers to a file using a platform-independent relative path, (file string) refers to a file using platform-specific notation, and (lib string ...) refers to a file within a collection.

If path-spec specifies a relative path, the path is resolved relative to the source for the include expression, if that source is a complete path string. If the source is not a complete path string, then path-spec is resolved relative to (current-load-relative-directory) if it is not #f, or relative to (current-directory) otherwise.

The included syntax is given the lexical context of the include expression, while the included syntax’s source location refers to its actual source.

The reader-expr is evaluated at expansion time in the transformer environment. Since it serves as a replacement for read-syntax, the expression’s value should be a procedure that consumes two inputs—a string representing the source and an input port—and produces a syntax object or eof. The procedure will be called repeatedly until it produces eof.

The syntax objects returned by the procedure should have source location information, but usually no lexical context; any lexical context in the syntax objects will be ignored.