@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
* Fly Evaluation:: Procedures for on the fly evaluation.
* Compilation:: How to compile Scheme files and procedures.
* Loading:: Loading Scheme code from file.
+* 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.
@end menu
'#t' quotes them; 'reader' quotes them
when the reader option 'keywords' is
not '#f'.
+escape-newlines yes Render newlines as \n when printing
+ using `write'.
@end smalllisp
These options may be modified with the print-set! syntax.
taste to use @code{eval}. By default, Guile automatically compiles any
files it encounters that have not been compiled yet (@pxref{Invoking
Guile, @code{--auto-compile}}). The compiler can also be invoked
-explicitly from the shell as @code{guile-tools compile foo.scm}.
+explicitly from the shell as @code{guild compile foo.scm}.
(Why are calls to @code{eval} and @code{compile} usually in bad taste?
Because they are limited, in that they can only really make sense for
Virtual Machine}. For information on the virtual machine, see @ref{A
Virtual Machine for Guile}.
-The command-line interface to Guile's compiler is the @command{guile-tools
+The command-line interface to Guile's compiler is the @command{guild
compile} command:
-@deffn {Command} {guile-tools compile} [@option{option}...] @var{file}...
+@deffn {Command} {guild compile} [@option{option}...] @var{file}...
Compile @var{file}, a source file, and store bytecode in the compilation cache
or in the file specified by the @option{-o} option. The following options are
available:
Use @var{lang} as the target language of @var{file}. If this option is omitted,
@code{objcode} is assumed.
+@item -T @var{target}
+@itemx --target=@var{target}
+Produce bytecode for @var{target} instead of @var{%host-type}
+(@pxref{Build Config, %host-type}). Target must be a valid GNU triplet,
+such as @code{armv5tel-unknown-linux-gnueabi} (@pxref{Specifying Target
+Triplets,,, autoconf, GNU Autoconf Manual}).
+
@end table
Each @var{file} is assumed to be UTF-8-encoded, unless it contains a
@xref{Compiling to the Virtual Machine}, for more information on these
options, and on @var{env} and @var{opts}.
-As with @command{guile-tools compile}, @var{file} is assumed to be
+As with @command{guild compile}, @var{file} is assumed to be
UTF-8-encoded unless it contains a coding declaration.
@end deffn
@rnindex load
@deffn {Scheme Procedure} load filename [reader]
Load @var{filename} and evaluate its contents in the top-level
-environment. The load paths are not searched.
+environment.
@var{reader} if provided should be either @code{#f}, or a procedure with
the signature @code{(lambda (port) @dots{})} which reads the next
@end deffn
@deffn {Scheme Procedure} load-compiled filename
-Load the compiled file named @var{filename}. The load paths are not
-searched.
+Load the compiled file named @var{filename}.
Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
calling @code{load-compiled} on the resulting file is equivalent to
calling @code{load} on the source file.
@end deffn
-@deffn {Scheme Procedure} load-from-path filename
-Similar to @code{load}, but searches for @var{filename} in the load
-paths. Preferentially loads a compiled version of the file, if it is
-available and up-to-date.
-@end deffn
-
@deffn {Scheme Procedure} primitive-load filename
@deffnx {C Function} scm_primitive_load (filename)
-Load the file named @var{filename} and evaluate its contents in
-the top-level environment. The load paths are not searched;
-@var{filename} must either be a full pathname or be a pathname
-relative to the current directory. If the variable
-@code{%load-hook} is defined, it should be bound to a procedure
-that will be called before any code is loaded. See the
-documentation for @code{%load-hook} later in this section.
+Load the file named @var{filename} and evaluate its contents in the
+top-level environment. @var{filename} must either be a full pathname or
+be a pathname relative to the current directory. If the variable
+@code{%load-hook} is defined, it should be bound to a procedure that
+will be called before any code is loaded. See the documentation for
+@code{%load-hook} later in this section.
@end deffn
@deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
@code{SCM}.
@end deftypefn
-@deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
-@deffnx {C Function} scm_primitive_load_path (filename)
-Search @code{%load-path} for the file named @var{filename} and
-load it into the top-level environment. If @var{filename} is a
-relative pathname and is not found in the list of search paths,
-an error is signalled. Preferentially loads a compiled version of the
-file, if it is available and up-to-date.
-
-By default or if @var{exception-on-not-found} is true, an exception is
-raised if @var{filename} is not found. If @var{exception-on-not-found}
-is @code{#f} and @var{filename} is not found, no exception is raised and
-@code{#f} is returned. For compatibility with Guile 1.8 and earlier,
-the C function takes only one argument, which can be either a string
-(the file name) or an argument list.
-@end deffn
-
-@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}
-will try each extension automatically.
-@end deffn
-
@defvar current-reader
@code{current-reader} holds the read procedure that is currently being
used by the above loading procedures to read expressions (from the file
@defvar %load-hook
A procedure to be called @code{(%load-hook @var{filename})} whenever a
file is loaded, or @code{#f} for no such call. @code{%load-hook} is
-used by all of the above loading functions (@code{load},
-@code{load-path}, @code{primitive-load} and
-@code{primitive-load-path}).
+used by all of the loading functions (@code{load} and
+@code{primitive-load}, and @code{load-from-path} and
+@code{primitive-load-path} documented in the next section).
For example an application can set this to show what's loaded,
The load port is used internally by @code{primitive-load}.
@end deffn
+@node Load Paths
+@subsection Load Paths
+
+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}.
+
+@deffn {Scheme Procedure} load-from-path filename
+Similar to @code{load}, but searches for @var{filename} in the load
+paths. Preferentially loads a compiled version of the file, if it is
+available and up-to-date.
+@end deffn
+
+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.
+
+For example, a script might include this form to add the directory that
+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
+of modifying the path both at compile-time and at run-time.
+
+@deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
+@deffnx {C Function} scm_primitive_load_path (filename)
+Search @code{%load-path} for the file named @var{filename} and
+load it into the top-level environment. If @var{filename} is a
+relative pathname and is not found in the list of search paths,
+an error is signalled. Preferentially loads a compiled version of the
+file, if it is available and up-to-date.
+
+By default or if @var{exception-on-not-found} is true, an exception is
+raised if @var{filename} is not found. If @var{exception-on-not-found}
+is @code{#f} and @var{filename} is not found, no exception is raised and
+@code{#f} is returned. For compatibility with Guile 1.8 and earlier,
+the C function takes only one argument, which can be either a string
+(the file name) or an argument list.
+@end deffn
+
+@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}
+will try each extension automatically.
+@end deffn
+
@defvar %load-extensions
A list of default file extensions for files containing Scheme code.
@code{%search-load-path} tries each of these extensions when looking for
list @code{("" ".scm")}.
@end defvar
+
@node Character Encoding of Source Files
@subsection Character Encoding of Source Files
@end deffn
+@node Local Evaluation
+@subsection Local Evaluation
+
+@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)
+Evaluate the expression @var{exp} in the lexical environment @var{env}.
+This mostly behaves as if @var{exp} had been wrapped in a lambda
+expression @code{`(lambda () ,@var{exp})} and put in place of
+@code{(the-environment)}, with the resulting procedure called by
+@code{local-eval}. In other words, @var{exp} is evaluated within the
+lexical environment of @code{(the-environment)}, but within the dynamic
+environment of the call to @code{local-eval}.
+@end deffn
+
+@deffn {Scheme Procedure} local-compile exp env [opts=()]
+Compile the expression @var{exp} in the lexical environment @var{env}.
+If @var{exp} is a procedure, the result will be a compiled procedure;
+otherwise @code{local-compile} is mostly equivalent to
+@code{local-eval}. @var{opts} specifies the compilation options.
+@end deffn
+
+Note that the current implementation of @code{(the-environment)} does
+not 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.
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
HCoop / bpt / guile.git / blobdiff