#
Chapter 18
`include.ss`: Textually Including Source

`(`include` `path-spec`)` S Y N T A X

Inlines the syntax in the designated file in place of the `include` expression.

The `path-spec` can be any of the following:

- a literal string that specifies a path to include (parsed according to the platform's conventions).

- a path construction of the form `(`build-path` `elem` `···`1)`, where `build-path` is `module-identifier=?` either to the `build-path` export from `mzscheme` or to the top-level `build-path`, and where each `elem` is a path string, `up` (unquoted), or `same` (unquoted). The `elem`s are combined in the same way as for the `build-path` function (see section 11.3.1 in PLT MzScheme: Language Manual) to obtain the path to include.

- a path construction of the form `(`lib` `file-string` `collection-string` `···`)`, where `lib` is free or refers to a top-level `lib` variable. The `collection-string`s are passed to `collection-path` to obtain a directory; if no `collection-string`s are supplied, `"mzlib"` is used. The `file-string` is then appended to the directory using `build-path` to obtain the path to include.

If `path-spec` specifies a relative path to include, 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 the current load relative directory if one is available, or to the current directory otherwise.

The included syntax is given the lexical context of the `include` expression.

`(`include-at/relative-to` `context source path-spec`)` S Y N T A X

Like `include`, except that the lexical context of `context` is used for the included syntax, and a relative `path-spec` is resolved with respect to the source of `source`. The `context` and `source` elements are otherwise discarded by expansion.

`(`include-at/relative-to/reader` `context source path-spec reader-expr`)` S Y N T A X

Combines `include-at/relative-to` and `include/reader`.

`(`include/reader` `path-spec reader-expr`)` S Y N T A X

Like `include`, except that the procedure produced by the expression `reader-expr` is used to read the included file, instead of ``read-syntax``.

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.