X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/a37593c7c8d518bbd0ff3b1b1362a5a6213027fc..34e89877342f20fdb8a531ad78dab34cfd2b0843:/doc/ref/api-evaluation.texi diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index d8412154c..7d67d9a21 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -1,10 +1,9 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006 -@c Free Software Foundation, Inc. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, +@c 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@page @node Read/Load/Eval/Compile @section Reading and Evaluating Scheme Code @@ -14,13 +13,16 @@ loading, evaluating, and compiling Scheme code at run time. @menu * Scheme Syntax:: Standard and extended Scheme syntax. * Scheme Read:: Reading Scheme code. +* Scheme Write:: Writing Scheme values to a port. * 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 environment. -* Evaluator Behaviour:: Modifying Guile's evaluator. -* 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 @@ -229,9 +231,32 @@ Thus a Guile script often starts like this. More details on Guile scripting can be found in the scripting section (@pxref{Guile Scripting}). +@cindex R6RS block comments +@cindex SRFI-30 block comments +Similarly, Guile (starting from version 2.0) supports nested block +comments as specified by R6RS and +@url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}: + +@lisp +(+ 1 #| this is a #| nested |# block comment |# 2) +@result{} 3 +@end lisp + +For backward compatibility, this syntax can be overridden with +@code{read-hash-extend} (@pxref{Reader Extensions, +@code{read-hash-extend}}). + +There is one special case where the contents of a comment can actually +affect the interpretation of code. When a character encoding +declaration, such as @code{coding: utf-8} appears in one of the first +few lines of a source file, it indicates to Guile's default reader +that this source code file is not ASCII. For details see @ref{Character +Encoding of Source Files}. @node Case Sensitivity @subsubsection Case Sensitivity +@cindex fold-case +@cindex no-fold-case @c FIXME::martin: Review me! @@ -246,16 +271,16 @@ Guile-Whuzzy are the same in R5RS Scheme, but are different in Guile. It is possible to turn off case sensitivity in Guile by setting the -reader option @code{case-insensitive}. More on reader options can be -found at (@pxref{Reader options}). +reader option @code{case-insensitive}. For more information on reader +options, @xref{Scheme Read}. @lisp (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 @@ -270,7 +295,9 @@ Install the procedure @var{proc} for reading expressions starting with the character sequence @code{#} and @var{chr}. @var{proc} will be called with two arguments: the character @var{chr} and the port to read further data from. The object -returned will be the return value of @code{read}. +returned will be the return value of @code{read}. +Passing @code{#f} for @var{proc} will remove a previous setting. + @end deffn @@ -286,55 +313,161 @@ Any whitespace before the next token is discarded. @end deffn The behaviour of Guile's Scheme reader can be modified by manipulating -its read options. For more information about options, @xref{User level -options interfaces}. If you want to know which reader options are -available, @xref{Reader options}. - -@c FIXME::martin: This is taken from libguile/options.c. Is there -@c actually a difference between 'help and 'full? +its read options. +@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, @var{setting} should be one of the following symbols: -@table @code -@item help -Display the complete option settings. -@item full -Like @code{help}, but also print programmer options. -@end table +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 +invoking @code{read-options} at the prompt. + +@smalllisp +scheme@@(guile-user)> (read-options) +(square-brackets keywords #f positions) +scheme@@(guile-user)> (read-options 'help) +copy no Copy source code expressions. +positions yes Record positions of source code expressions. +case-insensitive no Convert symbols to lower case. +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. +r7rs-symbols no Support R7RS |...| symbol notation. +@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 -@deffn {Scheme Procedure} read-options-interface [setting] -@deffnx {C Function} scm_read_options (setting) -Option interface for the read options. Instead of using -this procedure directly, use the procedures @code{read-enable}, -@code{read-disable}, @code{read-set!} and @code{read-options}. +For example, to make @code{read} fold all symbols to their lower case +(perhaps for compatibility with older Scheme code), you can enter: + +@lisp +(read-enable 'case-insensitive) +@end lisp + +For more information on the effect of the @code{r6rs-hex-escapes} and +@code{hungry-eol-escapes} options, see (@pxref{String Syntax}). + +For more information on the @code{r7rs-symbols} option, see +(@pxref{Symbol Read Syntax}). + + +@node Scheme Write +@subsection Writing Scheme Values + +Any scheme value may be written to a port. Not all values may be read +back in (@pxref{Scheme Read}), however. + +@rnindex write +@rnindex print +@deffn {Scheme Procedure} write obj [port] +Send a representation of @var{obj} to @var{port} or to the current +output port if not given. + +The output is designed to be machine readable, and can be read back +with @code{read} (@pxref{Scheme Read}). Strings are printed in +double quotes, with escapes if necessary, and characters are printed in +@samp{#\} notation. +@end deffn + +@rnindex display +@deffn {Scheme Procedure} display obj [port] +Send a representation of @var{obj} to @var{port} or to the current +output port if not given. + +The output is designed for human readability, it differs from +@code{write} in that strings are printed without double quotes and +escapes, and characters are printed as per @code{write-char}, not in +@samp{#\} form. +@end deffn + +As was the case with the Scheme reader, there are a few options that +affect the behavior of the Scheme printer. + +@cindex options - print +@cindex print options +@deffn {Scheme Procedure} print-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. +@end deffn + +The set of available options, and their default values, may be had by +invoking @code{print-options} at the prompt. + +@smalllisp +scheme@@(guile-user)> (print-options) +(quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{") +scheme@@(guile-user)> (print-options 'help) +highlight-prefix @{ The string to print before highlighted values. +highlight-suffix @} The string to print after highlighted values. +quote-keywordish-symbols reader How to print symbols that have a colon + as their first or last character. The + value '#f' does not quote the colons; + '#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'. +r7rs-symbols no Escape symbols using R7RS |...| symbol + notation. +@end smalllisp + +These options may be modified with the print-set! syntax. + +@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 @@ -349,38 +482,67 @@ return the environment in which the implementation would 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. @@ -391,9 +553,32 @@ then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the @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 {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 +@var{nargs}, as a @code{size_t}. +@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} @@ -432,12 +617,13 @@ interpreter. 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 @var{foo.scm}}. This interface needs more -documentation. +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 @@ -446,11 +632,78 @@ computation are fulfilled by macros and closures. Of course one good 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}. -@deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()] +The command-line interface to Guile's compiler is the @command{guild +compile} command: + +@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: + +@table @option + +@item -L @var{dir} +@itemx --load-path=@var{dir} +Add @var{dir} to the front of the module load path. + +@item -o @var{ofile} +@itemx --output=@var{ofile} +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} +@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} +Use @var{lang} as the source language of @var{file}. If this option is omitted, +@code{scheme} is assumed. + +@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. + +@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 +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=()] 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}. @@ -459,30 +712,51 @@ For a discussion of languages and compiler options, @xref{Compiling to 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='objcode] @ + [#: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 @@ -501,29 +775,21 @@ documentation for @code{%load-hook} later in this section. @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) @@ -531,26 +797,6 @@ documentation for @code{%load-hook} later in this section. @code{SCM}. @end deftypefn -@deffn {Scheme Procedure} primitive-load-path filename -@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. -@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 @@ -558,14 +804,29 @@ that they are loading). @code{current-reader} is a fluid, so it has an independent value in each dynamic root and should be read and set using @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic States}). + +Changing @code{current-reader} is typically useful to introduce local +syntactic changes, such that code following the @code{fluid-set!} call +is read using the newly installed reader. The @code{current-reader} +change should take place at evaluation time when the code is evaluated, +or at compilation time when the code is compiled: + +@findex eval-when +@example +(eval-when (compile eval) + (fluid-set! current-reader my-own-reader)) +@end example + +The @code{eval-when} form above ensures that the @code{current-reader} +change occurs at the right time. @end defvar @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, @@ -583,6 +844,79 @@ Return the current-load-port. 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 @@ -590,6 +924,157 @@ 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. 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.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} 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 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 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, +as recognized by @code{set-port-encoding!} (@pxref{Ports, +@code{set-port-encoding!}}). Common examples of character encoding +names are @code{utf-8} and @code{iso-8859-1}, +@url{http://www.iana.org/assignments/character-sets, as defined by +IANA}. Thus, the coding declaration is mostly compatible with Emacs. + +However, there are some differences in encoding names recognized by +Emacs and encoding names defined by IANA, the latter being essentially a +subset of the former. For instance, @code{latin-1} is a valid encoding +name for Emacs, but it's not according to the IANA standard, which Guile +follows; instead, you should use @code{iso-8859-1}, which is both +understood by Emacs and dubbed by IANA (IANA writes it uppercase but +Emacs wants it lowercase and Guile is case insensitive.) + +For source code, only a subset of all possible character encodings can +be interpreted by the built-in source code reader. Only those +character encodings in which ASCII text appears unmodified can be +used. This includes @code{UTF-8} and @code{ISO-8859-1} through +@code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16} +and @code{UTF-32} may not be used because they are not compatible with +ASCII. + +@cindex read +@cindex encoding +@cindex port encoding +@findex set-port-encoding! +There might be a scenario in which one would want to read non-ASCII +code from a port, such as with the function @code{read}, instead of +with @code{load}. If the port's character encoding is the same as the +encoding of the code to be read by the port, not other special +handling is necessary. The port will automatically do the character +encoding conversion. The functions @code{setlocale} or by +@code{set-port-encoding!} are used to set port encodings +(@pxref{Ports}). + +If a port is used to read code of unknown character encoding, it can +accomplish this in three steps. First, the character encoding of the +port should be set to ISO-8859-1 using @code{set-port-encoding!}. +Then, the procedure @code{file-encoding}, described below, is used to +scan for a coding declaration when reading from the port. As a side +effect, it rewinds the port after its scan is complete. After that, +the port's character encoding should be set to the encoding returned +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) +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 + @node Delayed Evaluation @subsection Delayed Evaluation @@ -597,7 +1082,8 @@ list @code{("" ".scm")}. @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 @@ -630,115 +1116,170 @@ value. @node Local Evaluation @subsection Local Evaluation -[the-environment] +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] +@deffn {Scheme Procedure} local-eval exp env @deffnx {C Function} scm_local_eval (exp, env) -Evaluate @var{exp} in its environment. If @var{env} is supplied, -it is the environment in which to evaluate @var{exp}. Otherwise, -@var{exp} must be a memoized code object (in which case, its environment -is implicit). +@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. -@node Evaluator Behaviour -@subsection Evaluator Behaviour +@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 -@c FIXME::martin: Maybe this node name is bad, but the old name clashed with -@c `Evaluator options' under `Options and Config'. +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}. -The behaviour of Guile's evaluator can be modified by manipulating the -evaluator options. For more information about options, @xref{User level -options interfaces}. If you want to know which evaluator options are -available, @xref{Evaluator options}. +@code{local-eval} and @code{local-compile} can only evaluate +expressions, not definitions. -@c FIXME::martin: This is taken from libguile/options.c. Is there -@c actually a difference between 'help and 'full? +@example +(local-eval '(define foo 42) + (let ((x 100)) (the-environment))) +@result{} syntax error: definition in expression context +@end example -@deffn {Scheme Procedure} eval-options [setting] -Display the current settings of the evaluator options. If @var{setting} -is omitted, only a short form of the current evaluator options is -printed. Otherwise, @var{setting} should be one of the following -symbols: -@table @code -@item help -Display the complete option settings. -@item full -Like @code{help}, but also print programmer options. -@end table -@end deffn +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 Procedure} eval-enable option-name -@deffnx {Scheme Procedure} eval-disable option-name -@deffnx {Scheme Procedure} eval-set! option-name value -Modify the evaluator options. @code{eval-enable} should be used with boolean -options and switches them on, @code{eval-disable} switches them off. -@code{eval-set!} can be used to set an option to a specific value. +@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} for appears in. @end deffn -@deffn {Scheme Procedure} eval-options-interface [setting] -@deffnx {C Function} scm_eval_options_interface (setting) -Option interface for the evaluation options. Instead of using -this procedure directly, use the procedures @code{eval-enable}, -@code{eval-disable}, @code{eval-set!} and @code{eval-options}. +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 -@c FIXME::martin: Why aren't these procedure named like the other options -@c procedures? +@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. -@deffn {Scheme Procedure} traps [setting] -Display the current settings of the evaluator traps options. If -@var{setting} is omitted, only a short form of the current evaluator -traps options is printed. Otherwise, @var{setting} should be one of the -following symbols: -@table @code -@item help -Display the complete option settings. -@item full -Like @code{help}, but also print programmer options. -@end table -@end deffn +@node REPL Servers +@subsection REPL Servers -@deffn {Scheme Procedure} trap-enable option-name -@deffnx {Scheme Procedure} trap-disable option-name -@deffnx {Scheme Procedure} trap-set! option-name value -Modify the evaluator options. @code{trap-enable} should be used with boolean -options and switches them on, @code{trap-disable} switches them off. -@code{trap-set!} can be used to set an option to a specific value. +@cindex REPL server -See @ref{Evaluator trap options} for more information on the available -trap handlers. -@end deffn +The procedures in this section are provided by +@lisp +(use-modules (system repl server)) +@end lisp -@deffn {Scheme Procedure} evaluator-traps-interface [setting] -@deffnx {C Function} scm_evaluator_traps (setting) -Option interface for the evaluator trap options. +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 -@node VM Behaviour -@subsection VM Behaviour - -Like the procedures from the previous section that operate on the -evaluator, there are also procedures to modify the behavior of a -virtual machine. +@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 -The most useful thing that a user can do is to add to one of the -virtual machine's predefined hooks: +@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. -@deffn {Scheme Procedure} vm-next-hook vm -@deffnx {Scheme Procedure} vm-apply-hook vm -@deffnx {Scheme Procedure} vm-boot-hook vm -@deffnx {Scheme Procedure} vm-return-hook vm -@deffnx {Scheme Procedure} vm-break-hook vm -@deffnx {Scheme Procedure} vm-exit-hook vm -@deffnx {Scheme Procedure} vm-halt-hook vm -@deffnx {Scheme Procedure} vm-enter-hook vm -Accessors to a virtual machine's hooks. Usually you pass -@code{(the-vm)} as the @var{vm}. +@code{run-server} runs the server in the current thread, whereas +@code{spawn-server} runs the server in a new thread. @end deffn -@xref{A Virtual Machine for Guile}, for more information on Guile's -virtual machine. +@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"