@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
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012, 2013
@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.
-* VM Behaviour:: Modifying Guile's virtual machine.
+* Local Evaluation:: Evaluation in a local lexical environment.
+* Local Inclusion:: Compile-time inclusion of one file in another.
+* REPL Servers:: Serving a REPL over a socket.
@end menu
@node Case Sensitivity
@subsubsection Case Sensitivity
+@cindex fold-case
+@cindex no-fold-case
@c FIXME::martin: Review me!
(read-enable 'case-insensitive)
@end lisp
-Note that this is seldom a problem, because Scheme programmers tend not
-to use uppercase letters in their identifiers anyway.
-
+It is also possible to disable (or enable) case sensitivity within a
+single file by placing the reader directives @code{#!fold-case} (or
+@code{#!no-fold-case}) within the file itself.
@node Keyword Syntax
@subsubsection Keyword Syntax
@cindex options - read
@cindex read options
@deffn {Scheme Procedure} read-options [setting]
-Display the current settings of the read options. If @var{setting} is
-omitted, only a short form of the current read options is printed.
-Otherwise if @var{setting} is the symbol @code{help}, a complete options
-description is displayed.
+Display the current settings of the global read options. If
+@var{setting} is omitted, only a short form of the current read options
+is printed. Otherwise if @var{setting} is the symbol @code{help}, a
+complete options description is displayed.
@end deffn
The set of available options, and their default values, may be had by
keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
+hungry-eol-escapes no In strings, consume leading whitespace after an
+ escaped end-of-line.
+curly-infix no Support SRFI-105 curly infix expressions.
@end smalllisp
+Note that Guile also includes a preliminary mechanism for setting read
+options on a per-port basis. For instance, the @code{case-insensitive}
+read option is set (or unset) on the port when the reader encounters the
+@code{#!fold-case} or @code{#!no-fold-case} reader directives.
+Similarly, the @code{#!curly-infix} reader directive sets the
+@code{curly-infix} read option on the port, and
+@code{#!curly-infix-and-bracket-lists} sets @code{curly-infix} and
+unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is
+currently no other way to access or set the per-port read options.
+
The boolean options may be toggled with @code{read-enable} and
@code{read-disable}. The non-boolean @code{keywords} option must be set
using @code{read-set!}.
@deffn {Scheme Procedure} read-enable option-name
@deffnx {Scheme Procedure} read-disable option-name
-@deffnx {Scheme Procedure} read-set! option-name value
+@deffnx {Scheme Syntax} read-set! option-name value
Modify the read options. @code{read-enable} should be used with boolean
options and switches them on, @code{read-disable} switches them off.
-@code{read-set!} can be used to set an option to a specific value.
+
+@code{read-set!} can be used to set an option to a specific value. Due
+to historical oddities, it is a macro that expects an unquoted option
+name.
@end deffn
For example, to make @code{read} fold all symbols to their lower case
(read-enable 'case-insensitive)
@end lisp
-For more information on the effect of the @code{r6rs-hex-escapes} option, see
-(@pxref{String Syntax}).
+For more information on the effect of the @code{r6rs-hex-escapes} and
+@code{hungry-eol-escapes} options, see (@pxref{String Syntax}).
@node Scheme Write
'#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! procedure.
+These options may be modified with the print-set! syntax.
-@deffn {Scheme Procedure} print-set! option-name value
-Modify the print options.
+@deffn {Scheme Syntax} print-set! option-name value
+Modify the print options. Due to historical oddities, @code{print-set!}
+is a macro that expects an unquoted option name.
@end deffn
@node Fly Evaluation
@subsection Procedures for On the Fly Evaluation
-@xref{Environments}.
+Scheme has the lovely property that its expressions may be represented
+as data. The @code{eval} procedure takes a Scheme datum and evaluates
+it as code.
@rnindex eval
@c ARGFIXME environment/environment specifier
@deffn {Scheme Procedure} eval exp module_or_state
@deffnx {C Function} scm_eval (exp, module_or_state)
Evaluate @var{exp}, a list representing a Scheme expression,
-in the top-level environment specified by @var{module}.
+in the top-level environment specified by @var{module_or_state}.
While @var{exp} is evaluated (using @code{primitive-eval}),
-@var{module} is made the current module. The current module
-is reset to its previous value when @var{eval} returns.
+@var{module_or_state} is made the current module. The current module
+is reset to its previous value when @code{eval} returns.
XXX - dynamic states.
Example: (eval '(+ 1 2) (interaction-environment))
@end deffn
evaluate expressions dynamically typed by the user.
@end deffn
-@deffn {Scheme Procedure} eval-string string [module]
-@deffnx {C Function} scm_eval_string (string)
+@xref{Environments}, for other environments.
+
+One does not always receive code as Scheme data, of course, and this is
+especially the case for Guile's other language implementations
+(@pxref{Other Languages}). For the case in which all you have is a
+string, we have @code{eval-string}. There is a legacy version of this
+procedure in the default environment, but you really want the one from
+@code{(ice-9 eval-string)}, so load it up:
+
+@example
+(use-modules (ice-9 eval-string))
+@end example
+
+@deffn {Scheme Procedure} eval-string string [#:module=#f] [#:file=#f] @
+ [#:line=#f] [#:column=#f] @
+ [#:lang=(current-language)] @
+ [#:compile?=#f]
+Parse @var{string} according to the current language, normally Scheme.
+Evaluate or compile the expressions it contains, in order, returning the
+last expression.
+
+If the @var{module} keyword argument is set, save a module excursion
+(@pxref{Module System Reflection}) and set the current module to
+@var{module} before evaluation.
+
+The @var{file}, @var{line}, and @var{column} keyword arguments can be
+used to indicate that the source string begins at a particular source
+location.
+
+Finally, @var{lang} is a language, defaulting to the current language,
+and the expression is compiled if @var{compile?} is true or there is no
+evaluator for the given language.
+@end deffn
+
+@deffn {C Function} scm_eval_string (string)
@deffnx {C Function} scm_eval_string_in_module (string, module)
-Evaluate @var{string} as the text representation of a Scheme form or
-forms, and return whatever value they produce. Evaluation takes place
-in the given module, or in the current module when no module is given.
-While the code is evaluated, the given module is made the current one.
-The current module is restored when this procedure returns.
+These C bindings call @code{eval-string} from @code{(ice-9
+eval-string)}, evaluating within @var{module} or the current module.
@end deffn
@deftypefn {C Function} SCM scm_c_eval_string (const char *string)
-@code{scm_eval_string}, but taking a C string instead of an
-@code{SCM}.
+@code{scm_eval_string}, but taking a C string in locale encoding instead
+of an @code{SCM}.
@end deftypefn
-@deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
+@deffn {Scheme Procedure} apply proc arg @dots{} arglst
@deffnx {C Function} scm_apply_0 (proc, arglst)
@deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
@deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
@deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
@deffnx {C Function} scm_apply (proc, arg, rest)
@rnindex apply
-Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the
+Call @var{proc} with arguments @var{arg} @dots{} and the
elements of the @var{arglst} list.
@code{scm_apply} takes parameters corresponding to a Scheme level
-@code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the
-last element of the @var{rest} list make up
-@var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the
-@var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL}
-then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
-@var{arglst}.
+@code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the
+last element of the @var{rest} list make up @var{arg} @dots{}, and the
+last element of @var{rest} is the @var{arglst} list. Or if @var{rest}
+is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and
+(@var{arg1}) is the @var{arglst}.
@var{arglst} is not modified, but the @var{rest} list passed to
@code{scm_apply} is modified.
@deffnx {C Function} scm_call_2 (proc, arg1, arg2)
@deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
@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 {Scheme Procedure} apply:nconc2last lst
-@deffnx {C Function} scm_nconc2last (lst)
-@var{lst} should be a list (@var{arg1} @dots{} @var{argN}
-@var{arglst}), with @var{arglst} being a list. This function returns
-a list comprising @var{arg1} to @var{argN} plus the elements of
-@var{arglst}. @var{lst} is modified to form the return. @var{arglst}
-is not modified, though the return does share structure with it.
+@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
-This operation collects up the arguments from a list which is
-@code{apply} style parameters.
+@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
+@var{nargs}, as a @code{size_t}.
@end deffn
@deffn {Scheme Procedure} primitive-eval exp
Functions from system modules in a Guile installation are normally
compiled already, so they load and run quickly.
+@cindex automatic compilation
Note that well-written Scheme programs will not typically call the
procedures in this section, for the same reason that it is often bad
-taste to use @code{eval}. The normal interface to the compiler is the
-command-line file compiler, which can be invoked from the shell as
-@code{guile-tools compile foo.scm}.
+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{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
counterexample is the REPL itself, or any code that reads expressions
from a port.)
+Automatic compilation generally works transparently, without any need
+for user intervention. However Guile does not yet do proper dependency
+tracking, so that if file @file{@var{a}.scm} uses macros from
+@file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm}
+would not be automatically recompiled. To forcibly invalidate the
+auto-compilation cache, pass the @code{--fresh-auto-compile} option to
+Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to
+@code{fresh} (instead of to @code{0} or @code{1}).
+
For more information on the compiler itself, see @ref{Compiling to the
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:
@item -o @var{ofile}
@itemx --output=@var{ofile}
-Write output bytecode to @var{ofile}. By convention, bytecode file names end
-in @code{.go}.
+Write output bytecode to @var{ofile}. By convention, bytecode file
+names end in @code{.go}. When @option{-o} is omitted, the output file
+name is as for @code{compile-file} (see below).
@item -W @var{warning}
@itemx --warn=@var{warning}
-Emit warnings of type @var{warning}; use @code{--warn=help} for a list of
-available warnings. Currently recognized warnings include
-@code{unused-variable}, @code{unused-toplevel}, @code{unbound-variable}, and
-@code{arity-mismatch}.
+@cindex warnings, compiler
+Emit warnings of type @var{warning}; use @code{--warn=help} for a list
+of available warnings and their description. Currently recognized
+warnings include @code{unused-variable}, @code{unused-toplevel},
+@code{unbound-variable}, @code{arity-mismatch}, @code{format},
+@code{duplicate-case-datum}, and @code{bad-case-datum}.
@item -f @var{lang}
@itemx --from=@var{lang}
@item -t @var{lang}
@itemx --to=@var{lang}
Use @var{lang} as the target language of @var{file}. If this option is omitted,
-@code{objcode} is assumed.
+@code{rtl} is assumed.
+
+@item -T @var{target}
+@itemx --target=@var{target}
+Produce code 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
+coding declaration as recognized by @code{file-encoding}
+(@pxref{Character Encoding of Source Files}).
@end deffn
The compiler can also be invoked directly by Scheme code using the procedures
below:
-@deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()]
+@deffn {Scheme Procedure} compile exp [#:env=#f] @
+ [#:from=(current-language)] @
+ [#:to=value] [#:opts=()]
Compile the expression @var{exp} in the environment @var{env}. If
@var{exp} is a procedure, the result will be a compiled procedure;
otherwise @code{compile} is mostly equivalent to @code{eval}.
the Virtual Machine}.
@end deffn
-@deffn {Scheme Procedure} compile-file file [to=objcode] [opts='()]
+@deffn {Scheme Procedure} compile-file file [#:output-file=#f] @
+ [#:from=(current-language)] [#:to='rtl] @
+ [#:env=(default-environment from)] @
+ [#:opts='()] @
+ [#:canonicalization='relative]
Compile the file named @var{file}.
-Output will be written to a file in the current directory whose name
-is computed as @code{(compiled-file-name @var{file})}.
+Output will be written to a @var{output-file}. If you do not supply an
+output file name, output is written to a file in the cache directory, as
+computed by @code{(compiled-file-name @var{file})}.
+
+@var{from} and @var{to} specify the source and target languages.
+@xref{Compiling to the Virtual Machine}, for more information on these
+options, and on @var{env} and @var{opts}.
+
+As with @command{guild compile}, @var{file} is assumed to be
+UTF-8-encoded unless it contains a coding declaration.
@end deffn
@deffn {Scheme Procedure} compiled-file-name file
-Compute an appropriate name for a compiled version of a Scheme file
-named @var{file}.
-
-Usually, the result will be the original file name with the
-@code{.scm} suffix replaced with @code{.go}, but the exact behavior
-depends on the contents of the @code{%load-extensions} and
-@code{%load-compiled-extensions} lists.
+Compute a cached location for a compiled version of a Scheme file named
+@var{file}.
+
+This file will usually be below the @file{$HOME/.cache/guile/ccache}
+directory, depending on the value of the @env{XDG_CACHE_HOME}
+environment variable. The intention is that @code{compiled-file-name}
+provides a fallback location for caching auto-compiled files. If you
+want to place a compile file in the @code{%load-compiled-path}, you
+should pass the @var{output-file} option to @code{compile-file},
+explicitly.
@end deffn
+@defvr {Scheme Variable} %auto-compilation-options
+This variable contains the options passed to the @code{compile-file}
+procedure when auto-compiling source files. By default, it enables
+useful compilation warnings. It can be customized from @file{~/.guile}.
+@end defvr
+
@node Loading
@subsection Loading Scheme Code from File
@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.
+
+@defvar %load-path
+List of directories which should be searched for Scheme modules and
+libraries. When Guile starts up, @code{%load-path} is initialized to
+the default load path @code{(list (%library-dir) (%site-dir)
+(%global-site-dir) (%package-data-dir))}. The @env{GUILE_LOAD_PATH}
+environment variable can be used to prepend or append additional
+directories (@pxref{Environment Variables}).
+
+@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
+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.
+@end deffn
+
+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
+
+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.
+
+If @var{filename} is a relative pathname and is not found in the list of
+search paths, one of three things may happen, depending on the optional
+second argument, @var{exception-on-not-found}. If it is @code{#f},
+@code{#f} will be returned. If it is a procedure, it will be called
+with no arguments. (This allows a distinction to be made between
+exceptions raised by loading a file, and exceptions related to the
+loader itself.) Otherwise an error is signalled.
+
+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
+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. The @env{GUILE_LOAD_COMPILED_PATH} environment variable
+can be used to prepend or append additional directories
+(@pxref{Environment Variables}).
+@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.2/ccache/ice-9/popen.go}, and use it instead of
+@code{/usr/share/guile/2.2/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} parse-path-with-ellipsis path base
+@deffnx {C Function} scm_parse_path_with_ellipsis (path, base)
+Parse @var{path}, which is expected to be a colon-separated string, into
+a list and return the resulting list with @var{base} (a list) spliced in
+place of the @code{...} path component, if present, or else @var{base}
+is added to the end. If @var{path} is @code{#f}, @var{base} 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
@cindex source file encoding
@cindex primitive-load
@cindex load
-Scheme source code files are usually encoded in ASCII, but, the
-built-in reader can interpret other character encodings. The
-procedure @code{primitive-load}, and by extension the functions that
-call it, such as @code{load}, first scan the top 500 characters of the
-file for a coding declaration.
+Scheme source code files are usually encoded in ASCII or UTF-8, but the
+built-in reader can interpret other character encodings as well. When
+Guile loads Scheme source code, it uses the @code{file-encoding}
+procedure (described below) to try to guess the encoding of the file.
+In the absence of any hints, UTF-8 is assumed. One way to provide a
+hint about the encoding of a source file is to place a coding
+declaration in the top 500 characters of the file.
A coding declaration has the form @code{coding: XXXXXX}, where
@code{XXXXXX} is the name of a character encoding in which the source
code file has been encoded. The coding declaration must appear in a
-scheme comment. It can either be a semicolon-initiated comment or a block
-@code{#!} comment.
+scheme comment. It can either be a semicolon-initiated comment, or the
+first block @code{#!} comment in the file.
The name of the character encoding in the coding declaration is
typically lower case and containing only letters, numbers, and hyphens,
by @code{file-encoding}, if any, again by using
@code{set-port-encoding!}. Then the code can be read as normal.
+Alternatively, one can use the @code{#:guess-encoding} keyword argument
+of @code{open-file} and related procedures. @xref{File Ports}.
+
@deffn {Scheme Procedure} file-encoding port
-@deffnx {C Function} scm_file_encoding port
-Scan the port for an Emacs-like character coding declaration near the
-top of the contents of a port with random-accessible contents
-(@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs,
-The GNU Emacs Reference Manual}). The coding declaration is of the form
-@code{coding: XXXXX} and must appear in a Scheme comment. Return a
-string containing the character encoding of the file if a declaration
-was found, or @code{#f} otherwise. The port is rewound.
+@deffnx {C Function} scm_file_encoding (port)
+Attempt to scan the first few hundred bytes from the @var{port} for
+hints about its character encoding. Return a string containing the
+encoding name or @code{#f} if the encoding cannot be determined. The
+port is rewound.
+
+Currently, the only supported method is to look for an Emacs-like
+character coding declaration (@pxref{Recognize Coding, how Emacs
+recognizes file encoding,, emacs, The GNU Emacs Reference Manual}). The
+coding declaration is of the form @code{coding: XXXXX} and must appear
+in a Scheme comment. Additional heuristics may be added in the future.
@end deffn
@cindex promises
Promises are a convenient way to defer a calculation until its result
-is actually needed, and to run such a calculation only once.
+is actually needed, and to run such a calculation only once. Also
+@pxref{SRFI-45}.
@deffn syntax delay expr
@rnindex delay
@end deffn
-@node VM Behaviour
-@subsection VM Behaviour
+@node Local Evaluation
+@subsection Local Evaluation
-Like the procedures from the previous section that operate on the
-evaluator, there are also procedures to modify the behavior of a
-virtual machine.
+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.
-The most useful thing that a user can do is to add to one of the
-virtual machine's predefined hooks:
+@example
+(use-modules (ice-9 local-eval))
+@end example
-@deffn {Scheme Procedure} vm-next-hook vm
-@deffnx {Scheme Procedure} vm-apply-hook vm
-@deffnx {Scheme Procedure} vm-push-continuation-hook vm
-@deffnx {Scheme Procedure} vm-pop-continuation-hook vm
-@deffnx {Scheme Procedure} vm-abort-continuation-hook vm
-@deffnx {Scheme Procedure} vm-restore-continuation-hook vm
-Accessors to a virtual machine's hooks. Usually you pass @code{(the-vm)}
-as the @var{vm}.
+@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} vm-trace-level vm
-Retrieve the ``trace level'' of the VM. If positive, the trace hooks associated
-with @var{vm} will be run. The initial trace level is 0.
+@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
-@deffn {Scheme Procedure} set-vm-trace-level! vm level
-Set the ``trace level'' of the VM.
+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}.
+
+If @var{file-name} is a relative path, it is searched for relative to
+the path that contains the file that the @code{include} form appears in.
+@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
-@xref{A Virtual Machine for Guile}, for more information on Guile's
-virtual machine.
+@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.
+
+@node REPL Servers
+@subsection REPL Servers
+
+@cindex REPL server
+
+The procedures in this section are provided by
+@lisp
+(use-modules (system repl server))
+@end lisp
+
+When an application is written in Guile, it is often convenient to
+allow the user to be able to interact with it by evaluating Scheme
+expressions in a REPL.
+
+The procedures of this module allow you to spawn a @dfn{REPL server},
+which permits interaction over a local or TCP connection. Guile itself
+uses them internally to implement the @option{--listen} switch,
+@ref{Command-line Options}.
+
+@deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
+ [#:addr] [#:port=37146]
+Return a stream socket bound to a given address @var{addr} and port
+number @var{port}. If the @var{host} is given, and @var{addr} is not,
+then the @var{host} string is converted to an address. If neither is
+given, we use the loopback address.
+@end deffn
+
+@deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
+Return a UNIX domain socket, bound to a given @var{path}.
+@end deffn
+
+@deffn {Scheme Procedure} run-server [server-socket]
+@deffnx {Scheme Procedure} spawn-server [server-socket]
+Create and run a REPL, making it available over the given
+@var{server-socket}. If @var{server-socket} is not provided, it
+defaults to the socket created by calling @code{make-tcp-server-socket}
+with no arguments.
+
+@code{run-server} runs the server in the current thread, whereas
+@code{spawn-server} runs the server in a new thread.
+@end deffn
+
+@deffn {Scheme Procedure} stop-server-and-clients!
+Closes the connection on all running server sockets.
+@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
HCoop / bpt / guile.git / blobdiff