summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/api-evaluation.texi214
-rw-r--r--doc/ref/api-foreign.texi10
-rw-r--r--doc/ref/api-macros.texi17
-rw-r--r--doc/ref/api-modules.texi6
-rw-r--r--doc/ref/api-options.texi50
-rw-r--r--doc/ref/guile.texi2
-rw-r--r--doc/ref/scheme-using.texi5
7 files changed, 243 insertions, 61 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index ef3e602bb..8c41d1efd 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -20,6 +20,8 @@ loading, evaluating, and compiling Scheme code at run time.
* Load Paths:: Where Guile looks for code.
* 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
@@ -531,9 +533,24 @@ then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
@deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
@deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
@deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
+@deffnx {C Function} scm_call_7 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
+@deffnx {C Function} scm_call_8 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
+@deffnx {C Function} scm_call_9 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
Call @var{proc} with the given arguments.
@end deffn
+@deffn {C Function} scm_call (proc, ...)
+Call @var{proc} with any number of arguments. The argument list must be
+terminated by @code{SCM_UNDEFINED}. For example:
+
+@example
+scm_call (scm_c_public_ref ("guile", "+"),
+ scm_from_int (1),
+ scm_from_int (2),
+ SCM_UNDEFINED);
+@end example
+@end deffn
+
@deffn {C Function} scm_call_n (proc, argv, nargs)
Call @var{proc} with the array of arguments @var{argv}, as a
@code{SCM*}. The length of the arguments should be passed in
@@ -807,7 +824,15 @@ The procedure in the previous section look for Scheme code in the file
system at specific location. Guile also has some procedures to search
the load path for code.
-For more on the @code{%load-path} variable, @xref{Build Config}.
+@cindex @env{GUILE_LOAD_PATH}
+@defvar %load-path
+List of directories which should be searched for Scheme modules and
+libraries. @code{%load-path} is initialized when Guile starts up to
+@code{(list (%site-dir) (%library-dir) (%package-data-dir))}, prepended
+with the contents of the @env{GUILE_LOAD_PATH} environment variable, if
+it is set. @xref{Build Config}, for more on @code{%site-dir} and
+related procedures.
+@end defvar
@deffn {Scheme Procedure} load-from-path filename
Similar to @code{load}, but searches for @var{filename} in the load
@@ -819,6 +844,7 @@ A user can extend the load path by calling @code{add-to-load-path}.
@deffn {Scheme Syntax} add-to-load-path dir
Add @var{dir} to the load path.
+@end deffn
For example, a script might include this form to add the directory that
it is in to the load path:
@@ -826,7 +852,6 @@ it is in to the load path:
@example
(add-to-load-path (dirname (current-filename)))
@end example
-@end deffn
It's better to use @code{add-to-load-path} than to modify
@code{%load-path} directly, because @code{add-to-load-path} takes care
@@ -850,12 +875,11 @@ the C function takes only one argument, which can be either a string
@deffn {Scheme Procedure} %search-load-path filename
@deffnx {C Function} scm_sys_search_load_path (filename)
-Search @code{%load-path} for the file named @var{filename},
-which must be readable by the current user. If @var{filename}
-is found in the list of paths to search or is an absolute
-pathname, return its full pathname. Otherwise, return
-@code{#f}. Filenames may have any of the optional extensions
-in the @code{%load-extensions} list; @code{%search-load-path}
+Search @code{%load-path} for the file named @var{filename}, which must
+be readable by the current user. If @var{filename} is found in the list
+of paths to search or is an absolute pathname, return its full pathname.
+Otherwise, return @code{#f}. Filenames may have any of the optional
+extensions in the @code{%load-extensions} list; @code{%search-load-path}
will try each extension automatically.
@end deffn
@@ -866,6 +890,61 @@ a file to load. By default, @code{%load-extensions} is bound to the
list @code{("" ".scm")}.
@end defvar
+As mentioned above, when Guile searches the @code{%load-path} for a
+source file, it will also search the @code{%load-compiled-path} for a
+corresponding compiled file. If the compiled file is as new or newer
+than the source file, it will be loaded instead of the source file,
+using @code{load-compiled}.
+
+@defvar %load-compiled-path
+Like @code{%load-path}, but for compiled files. By default, this path
+has two entries: one for compiled files from Guile itself, and one for
+site packages.
+@end defvar
+
+When @code{primitive-load-path} searches the @code{%load-compiled-path}
+for a corresponding compiled file for a relative path it does so by
+appending @code{.go} to the relative path. For example, searching for
+@code{ice-9/popen} could find
+@code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
+@code{/usr/share/guile/2.0/ice-9/popen.scm}.
+
+If @code{primitive-load-path} does not find a corresponding @code{.go}
+file in the @code{%load-compiled-path}, or the @code{.go} file is out of
+date, it will search for a corresponding auto-compiled file in the
+fallback path, possibly creating one if one does not exist.
+
+@xref{Installing Site Packages}, for more on how to correctly install
+site packages. @xref{Modules and the File System}, for more on the
+relationship between load paths and modules. @xref{Compilation}, for
+more on the fallback path and auto-compilation.
+
+Finally, there are a couple of helper procedures for general path
+manipulation.
+
+@deffn {Scheme Procedure} parse-path path [tail]
+@deffnx {C Function} scm_parse_path (path, tail)
+Parse @var{path}, which is expected to be a colon-separated string, into
+a list and return the resulting list with @var{tail} appended. If
+@var{path} is @code{#f}, @var{tail} is returned.
+@end deffn
+
+@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
+@deffnx {C Function} scm_search_path (path, filename, rest)
+Search @var{path} for a directory containing a file named
+@var{filename}. The file must be readable, and not a directory. If we
+find one, return its full filename; otherwise, return @code{#f}. If
+@var{filename} is absolute, return it unchanged. If given,
+@var{extensions} is a list of strings; for each directory in @var{path},
+we search for @var{filename} concatenated with each @var{extension}. If
+@var{require-exts?} is true, require that the returned file name have
+one of the given extensions; if @var{require-exts?} is not given, it
+defaults to @code{#f}.
+
+For compatibility with Guile 1.8 and earlier, the C function takes only
+three arguments.
+@end deffn
+
@node Character Encoding of Source Files
@subsection Character Encoding of Source Files
@@ -980,6 +1059,125 @@ value.
@end deffn
+@node Local Evaluation
+@subsection Local Evaluation
+
+Guile includes a facility to capture a lexical environment, and later
+evaluate a new expression within that environment. This code is
+implemented in a module.
+
+@example
+(use-modules (ice-9 local-eval))
+@end example
+
+@deffn syntax the-environment
+Captures and returns a lexical environment for use with
+@code{local-eval} or @code{local-compile}.
+@end deffn
+
+@deffn {Scheme Procedure} local-eval exp env
+@deffnx {C Function} scm_local_eval (exp, env)
+@deffnx {Scheme Procedure} local-compile exp env [opts=()]
+Evaluate or compile the expression @var{exp} in the lexical environment
+@var{env}.
+@end deffn
+
+Here is a simple example, illustrating that it is the variable
+that gets captured, not just its value at one point in time.
+
+@example
+(define e (let ((x 100)) (the-environment)))
+(define fetch-x (local-eval '(lambda () x) e))
+(fetch-x)
+@result{} 100
+(local-eval '(set! x 42) e)
+(fetch-x)
+@result{} 42
+@end example
+
+While @var{exp} is evaluated within the lexical environment of
+@code{(the-environment)}, it has the dynamic environment of the call to
+@code{local-eval}.
+
+@code{local-eval} and @code{local-compile} can only evaluate
+expressions, not definitions.
+
+@example
+(local-eval '(define foo 42)
+ (let ((x 100)) (the-environment)))
+@result{} syntax error: definition in expression context
+@end example
+
+Note that the current implementation of @code{(the-environment)} only
+captures ``normal'' lexical bindings, and pattern variables bound by
+@code{syntax-case}. It does not currently capture local syntax
+transformers bound by @code{let-syntax}, @code{letrec-syntax} or
+non-top-level @code{define-syntax} forms. Any attempt to reference such
+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:
diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
index 82925e68d..6ece7f8ed 100644
--- a/doc/ref/api-foreign.texi
+++ b/doc/ref/api-foreign.texi
@@ -425,11 +425,11 @@ its own @code{gettext} message catalogue
(@pxref{Internationalization}).
It will be noted all of the above requires that the Scheme code to be
-found in @code{%load-path} (@pxref{Build Config}). Presently it's
-left up to the system administrator or each user to augment that path
-when installing Guile modules in non-default locations. But having
-reached the Scheme code, that code should take care of hitting any of
-its own private files etc.
+found in @code{%load-path} (@pxref{Load Paths}). Presently it's left up
+to the system administrator or each user to augment that path when
+installing Guile modules in non-default locations. But having reached
+the Scheme code, that code should take care of hitting any of its own
+private files etc.
@node Foreign Pointers
diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 02b5d5c8a..f6a03bc32 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -706,6 +706,23 @@ Return the source properties that correspond to the syntax object
@var{x}. @xref{Source Properties}, for more information.
@end deffn
+Guile also offers some more experimental interfaces in a separate
+module. As was the case with the Large Hadron Collider, it is unclear
+to our senior macrologists whether adding these interfaces will result
+in awesomeness or in the destruction of Guile via the creation of a
+singularity. We will preserve their functionality through the 2.0
+series, but we reserve the right to modify them in a future stable
+series, to a more than usual degree.
+
+@example
+(use-modules (system syntax))
+@end example
+
+@deffn {Scheme Procedure} syntax-module id
+Return the name of the module whose source contains the identifier
+@var{id}.
+@end deffn
+
@deffn {Scheme Procedure} syntax-local-binding id
Resolve the identifer @var{id}, a syntax object, within the current
lexical environment, and return two values, the binding type and a
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index 3c96c2a55..b9f975864 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -98,8 +98,8 @@ types of access are handled by the syntactic form @code{use-modules},
which accepts one or more interface specifications and, upon evaluation,
arranges for those interfaces to be available to the current module.
This process may include locating and loading code for a given module if
-that code has not yet been loaded, following @code{%load-path} (@pxref{Build
-Config}).
+that code has not yet been loaded, following @code{%load-path}
+(@pxref{Modules and the File System}).
An @dfn{interface specification} has one of two forms. The first
variation is simply to name the module, in which case its public
@@ -464,7 +464,7 @@ from in the @dfn{load path}.
In this case, loading @code{(ice-9 popen)} will eventually cause Guile
to run @code{(primitive-load-path "ice-9/popen")}.
@code{primitive-load-path} will search for a file @file{ice-9/popen} in
-the @code{%load-path} (@pxref{Build Config}). For each directory in
+the @code{%load-path} (@pxref{Load Paths}). For each directory in
@code{%load-path}, Guile will try to find the file name, concatenated
with the extensions from @code{%load-extensions}. By default, this will
cause Guile to @code{stat} @file{ice-9/popen.scm}, and then
diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
index 6f7568bee..f63597824 100644
--- a/doc/ref/api-options.texi
+++ b/doc/ref/api-options.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2011
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2011, 2012
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -59,14 +59,14 @@ The @code{effective-version} function returns the version name that
should remain unchanged during a stable series. Currently that means
that it omits the micro version. The effective version should be used
for items like the versioned share directory name
-i.e.@: @file{/usr/share/guile/1.6/}
+i.e.@: @file{/usr/share/guile/2.0/}
@lisp
-(version) @result{} "1.6.0"
-(effective-version) @result{} "1.6"
-(major-version) @result{} "1"
-(minor-version) @result{} "6"
-(micro-version) @result{} "0"
+(version) @result{} "2.0.4"
+(effective-version) @result{} "2.0"
+(major-version) @result{} "2"
+(minor-version) @result{} "0"
+(micro-version) @result{} "4"
@end lisp
@end deffn
@@ -86,7 +86,7 @@ party package) are installed. On Unix-like systems this is usually
@file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
@noindent
-for example @file{/usr/local/share/guile/1.6}.
+for example @file{/usr/local/share/guile/2.0}.
@end deffn
@deffn {Scheme Procedure} %site-dir
@@ -96,40 +96,6 @@ your site should be installed. On Unix-like systems, this is usually
@file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
@end deffn
-@cindex @env{GUILE_LOAD_PATH}
-@defvar %load-path
-List of directories which should be searched for Scheme modules and
-libraries. @code{%load-path} is initialized when Guile starts up to
-@code{(list (%site-dir) (%library-dir) (%package-data-dir))},
-prepended with the contents of the @env{GUILE_LOAD_PATH} environment variable,
-if it is set.
-@end defvar
-
-@deffn {Scheme Procedure} parse-path path [tail]
-@deffnx {C Function} scm_parse_path (path, tail)
-Parse @var{path}, which is expected to be a colon-separated
-string, into a list and return the resulting list with
-@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
-is returned.
-@end deffn
-
-@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
-@deffnx {C Function} scm_search_path (path, filename, rest)
-Search @var{path} for a directory containing a file named
-@var{filename}. The file must be readable, and not a directory.
-If we find one, return its full filename; otherwise, return
-@code{#f}. If @var{filename} is absolute, return it unchanged.
-If given, @var{extensions} is a list of strings; for each
-directory in @var{path}, we search for @var{filename}
-concatenated with each @var{extension}. If @var{require-exts?}
-is true, require that the returned file name have one of the
-given extensions; if @var{require-exts?} is not given, it
-defaults to @code{#f}.
-
-For compatibility with Guile 1.8 and earlier, the C function takes only
-three arguments
-@end deffn
-
@defvar %guile-build-info
Alist of information collected during the building of a particular
Guile. Entries can be grouped into one of several categories:
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 9c6deb667..c3da0c36d 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -14,7 +14,7 @@
This manual documents Guile version @value{VERSION}.
Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2009,
-2010, 2011 Free Software Foundation.
+2010, 2011, 2012 Free Software Foundation.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 07096bb41..ae608d70a 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2006, 2010, 2011
+@c Copyright (C) 2006, 2010, 2011, 2012
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -780,7 +780,8 @@ site packages will be
Note that a @code{.go} file will only be loaded in preference to a
@code{.scm} file if it is newer. For that reason, you should install
-your Scheme files first, and your compiled files second.
+your Scheme files first, and your compiled files second. @code{Load
+Paths}, for more on the loading process.
Finally, although this section is only about Scheme, sometimes you need
to install C extensions too. Shared libraries should be installed in