@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 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.
-@page
@node Read/Load/Eval/Compile
@section Reading and Evaluating Scheme Code
@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.
@end menu
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
+(+ #| 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
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)
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
@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
-@end deffn
+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.
+@end smalllisp
+
+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
+(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}).
+
+
+@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
-@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}.
+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'.
+@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
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
@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)
Call @var{proc} with the given arguments.
@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}
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
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{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}
+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}, and @code{format}.
+
+@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;
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}.
+Compute a cached location 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.
+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
-@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
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,
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
@end defvar
+@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.
+
+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.
+
+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.
+
+@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.
+@end deffn
+
+
@node Delayed Evaluation
@subsection Delayed Evaluation
@cindex delayed evaluation
@end deffn
-@node Local Evaluation
-@subsection Local Evaluation
-
-[the-environment]
-
-@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).
-@end deffn
-
-
-@node Evaluator Behaviour
-@subsection Evaluator Behaviour
-
-@c FIXME::martin: Maybe this node name is bad, but the old name clashed with
-@c `Evaluator options' under `Options and Config'.
-
-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}.
-
-@c FIXME::martin: This is taken from libguile/options.c. Is there
-@c actually a difference between 'help and 'full?
-
-@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
-
-@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.
-@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}.
-@end deffn
-
-@c FIXME::martin: Why aren't these procedure named like the other options
-@c procedures?
-
-@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
-
-@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.
-
-See @ref{Evaluator trap options} for more information on the available
-trap handlers.
-@end deffn
-
-@deffn {Scheme Procedure} evaluator-traps-interface [setting]
-@deffnx {C Function} scm_evaluator_traps (setting)
-Option interface for the evaluator trap options.
-@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.
-
-The most useful thing that a user can do is to add to one of the
-virtual machine's predefined hooks:
-
-@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}.
-@end deffn
-
-@xref{A Virtual Machine for Guile}, for more information on Guile's
-virtual machine.
-
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
HCoop / bpt / guile.git / blobdiff