diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/api-evaluation.texi | 214 | ||||
-rw-r--r-- | doc/ref/api-foreign.texi | 10 | ||||
-rw-r--r-- | doc/ref/api-macros.texi | 17 | ||||
-rw-r--r-- | doc/ref/api-modules.texi | 6 | ||||
-rw-r--r-- | doc/ref/api-options.texi | 50 | ||||
-rw-r--r-- | doc/ref/guile.texi | 2 | ||||
-rw-r--r-- | doc/ref/scheme-using.texi | 5 |
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 |