diff options
author | Andy Wingo <wingo@pobox.com> | 2012-01-27 16:26:36 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2012-01-27 16:33:11 +0100 |
commit | eb7da3d81f565ae20b0a35dda0607537e969ff59 (patch) | |
tree | 05f7aaec2c193e3fbb92589a85ff45182b4b39a8 /doc/ref/api-evaluation.texi | |
parent | 0740cb49d1509c56184fc6802b4347ed8fc80a28 (diff) | |
download | guile-eb7da3d81f565ae20b0a35dda0607537e969ff59.tar.gz |
document `include', `include-from-path'
* doc/ref/api-evaluation.texi (Local Inclusion): New section.
Diffstat (limited to 'doc/ref/api-evaluation.texi')
-rw-r--r-- | doc/ref/api-evaluation.texi | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index ebd8771df..90cae45bd 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -21,6 +21,7 @@ loading, evaluating, and compiling Scheme code at run time. * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file. * Delayed Evaluation:: Postponing evaluation until it is needed. * Local Evaluation:: Evaluation in a local lexical environment. +* Local Inclusion:: Compile-time inclusion of one file in another. @end menu @@ -1101,6 +1102,67 @@ captured syntactic keywords via @code{local-eval} or @code{local-compile} produces an error. +@node Local Inclusion +@subsection Local Inclusion + +This section has discussed various means of linking Scheme code +together: fundamentally, loading up files at run-time using @code{load} +and @code{load-compiled}. Guile provides another option to compose +parts of programs together at expansion-time instead of at run-time. + +@deffn {Scheme Syntax} include file-name +Open @var{file-name}, at expansion-time, and read the Scheme forms that +it contains, splicing them into the location of the @code{include}, +within a @code{begin}. +@end deffn + +If you are a C programmer, if @code{load} in Scheme is like +@code{dlopen} in C, consider @code{include} to be like the C +preprocessor's @code{#include}. When you use @code{include}, it is as +if the contents of the included file were typed in instead of the +@code{include} form. + +Because the code is included at compile-time, it is available to the +macroexpander. Syntax definitions in the included file are available to +later code in the form in which the @code{include} appears, without the +need for @code{eval-when}. (@xref{Eval When}.) + +For the same reason, compiling a form that uses @code{include} results +in one compilation unit, composed of multiple files. Loading the +compiled file is one @code{stat} operation for the compilation unit, +instead of @code{2*@var{n}} in the case of @code{load} (once for each +loaded source file, and once each corresponding compiled file, in the +best case). + +Unlike @code{load}, @code{include} also works within nested lexical +contexts. It so happens that the optimizer works best within a lexical +context, because all of the uses of bindings in a lexical context are +visible, so composing files by including them within a @code{(let () +...)} can sometimes lead to important speed improvements. + +On the other hand, @code{include} does have all the disadvantages of +early binding: once the code with the @code{include} is compiled, no +change to the included file is reflected in the future behavior of the +including form. + +Also, the particular form of @code{include}, which requires an absolute +path, or a path relative to the current directory at compile-time, is +not very amenable to compiling the source in one place, but then +installing the source to another place. For this reason, Guile provides +another form, @code{include-from-path}, which looks for the source file +to include within a load path. + +@deffn {Scheme Syntax} include-from-path file-name +Like @code{include}, but instead of expecting @code{file-name} to be an +absolute file name, it is expected to be a relative path to search in +the @code{%load-path}. +@end deffn + +@code{include-from-path} is more useful when you want to install all of +the source files for a package (as you should!). It makes it possible +to evaluate an installed file from source, instead of relying on the +@code{.go} file being up to date. + @c Local Variables: @c TeX-master: "guile.texi" @c End: |