* bug#10327: Please document include and include-from-path
@ 2011-12-19 15:12 Ian Hulin
2011-12-23 23:53 ` Ian Price
0 siblings, 1 reply; 3+ messages in thread
From: Ian Hulin @ 2011-12-19 15:12 UTC (permalink / raw)
To: 10327
I think I know what these do, but could you include them in the docs,
and point out how differ from load and load-from-path.
Documentation something like this?
— Scheme Procedure: include filename
Load filename and add its contents to a file currently being
compiled. Unlike /load/ its contents are not evaluated immediately.
The load paths are not searched.
— Scheme Procedure: include-from-path filename
Locate /filename/ in the load paths, load /filename/ and add its
contents to a file currently being compiled. Unlike
/load-from-path/ its contents are not evaluated immediately.
^ permalink raw reply [flat|nested] 3+ messages in thread
* bug#10327: Please document include and include-from-path
2011-12-19 15:12 bug#10327: Please document include and include-from-path Ian Hulin
@ 2011-12-23 23:53 ` Ian Price
2012-01-27 15:31 ` Andy Wingo
0 siblings, 1 reply; 3+ messages in thread
From: Ian Price @ 2011-12-23 23:53 UTC (permalink / raw)
To: 10327; +Cc: Ian Hulin
Ian Hulin <ian@hulin.org.uk> writes:
> I think I know what these do, but could you include them in the docs,
> and point out how differ from load and load-from-path.
>
> Documentation something like this?
>
> — Scheme Procedure: include filename
>
> Load filename and add its contents to a file currently being
> compiled. Unlike /load/ its contents are not evaluated immediately.
> The load paths are not searched.
>
> — Scheme Procedure: include-from-path filename
>
> Locate /filename/ in the load paths, load /filename/ and add its
> contents to a file currently being compiled. Unlike
> /load-from-path/ its contents are not evaluated immediately.
I agree, these should be documented, but I would stay away from using
the phrase 'load' in a description of these in case it is
confusing. Maybe "Adds the contents of the file, in place, at the point
of the 'include' macro use at macro expansion time"? Or am I being ever
so slightly patronising?
--
Ian Price
"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"
^ permalink raw reply [flat|nested] 3+ messages in thread
* bug#10327: Please document include and include-from-path
2011-12-23 23:53 ` Ian Price
@ 2012-01-27 15:31 ` Andy Wingo
0 siblings, 0 replies; 3+ messages in thread
From: Andy Wingo @ 2012-01-27 15:31 UTC (permalink / raw)
To: Ian Price; +Cc: Ian Hulin, 10327-done
Hello Ian & Ian :)
Thanks for the report. I added some extensive docs.
6.17.11 Local Inclusion
-----------------------
This section has discussed various means of linking Scheme code
together: fundamentally, loading up files at run-time using `load' and
`load-compiled'. Guile provides another option to compose parts of
programs together at expansion-time instead of at run-time.
-- Scheme Syntax: include file-name
Open FILE-NAME, at expansion-time, and read the Scheme forms that
it contains, splicing them into the location of the `include',
within a `begin'.
If you are a C programmer, if `load' in Scheme is like `dlopen' in
C, consider `include' to be like the C preprocessor's `#include'. When
you use `include', it is as if the contents of the included file were
typed in instead of the `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 `include' appears, without the need
for `eval-when'. (*Note Eval When::.)
For the same reason, compiling a form that uses `include' results in
one compilation unit, composed of multiple files. Loading the compiled
file is one `stat' operation for the compilation unit, instead of `2*N'
in the case of `load' (once for each loaded source file, and once each
corresponding compiled file, in the best case).
Unlike `load', `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 `(let () ...)' can
sometimes lead to important speed improvements.
On the other hand, `include' does have all the disadvantages of
early binding: once the code with the `include' is compiled, no change
to the included file is reflected in the future behavior of the
including form.
Also, the particular form of `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, `include-from-path', which looks for the source file to
include within a load path.
-- Scheme Syntax: include-from-path file-name
Like `include', but instead of expecting `file-name' to be an
absolute file name, it is expected to be a relative path to search
in the `%load-path'.
`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
`.go' file being up to date.
On Sat 24 Dec 2011 00:53, Ian Price <ianprice90@googlemail.com> writes:
> Or am I being ever so slightly patronising?
"Recursion and condescension"? :-)
http://james-iry.blogspot.com/2009/05/brief-incomplete-and-mostly-wrong.html
Cheers,
Andy
--
http://wingolog.org/
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2012-01-27 15:31 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-12-19 15:12 bug#10327: Please document include and include-from-path Ian Hulin
2011-12-23 23:53 ` Ian Price
2012-01-27 15:31 ` Andy Wingo
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).