mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
21ad60a1d2
* module/ice-9/boot-9.scm (current-filename): Canonicalize the path, so that the result is independent of the current directory, and so that `dirname' can traverse up the file system, as in the add-to-load-path example. (add-to-path): Remove. The eval-when semantics make this macro too tricky to explain -- people will start using it on other path-like things, in lexical contours, whereas it only really makes sense with load-like paths at the toplevel. * doc/ref/api-evaluation.texi (Loading): Fix link to load-with-path docs, and remove add-to-path docs.
985 lines
36 KiB
Text
985 lines
36 KiB
Text
@c -*-texinfo-*-
|
|
@c This is part of the GNU Guile Reference Manual.
|
|
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012
|
|
@c Free Software Foundation, Inc.
|
|
@c See the file guile.texi for copying conditions.
|
|
|
|
@node Read/Load/Eval/Compile
|
|
@section Reading and Evaluating Scheme Code
|
|
|
|
This chapter describes Guile functions that are concerned with reading,
|
|
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.
|
|
@end menu
|
|
|
|
|
|
@node Scheme Syntax
|
|
@subsection Scheme Syntax: Standard and Guile Extensions
|
|
|
|
@menu
|
|
* Expression Syntax::
|
|
* Comments::
|
|
* Block Comments::
|
|
* Case Sensitivity::
|
|
* Keyword Syntax::
|
|
* Reader Extensions::
|
|
@end menu
|
|
|
|
|
|
@node Expression Syntax
|
|
@subsubsection Expression Syntax
|
|
|
|
An expression to be evaluated takes one of the following forms.
|
|
|
|
@table @nicode
|
|
|
|
@item @var{symbol}
|
|
A symbol is evaluated by dereferencing. A binding of that symbol is
|
|
sought and the value there used. For example,
|
|
|
|
@example
|
|
(define x 123)
|
|
x @result{} 123
|
|
@end example
|
|
|
|
@item (@var{proc} @var{args}@dots{})
|
|
A parenthesised expression is a function call. @var{proc} and each
|
|
argument are evaluated, then the function (which @var{proc} evaluated
|
|
to) is called with those arguments.
|
|
|
|
The order in which @var{proc} and the arguments are evaluated is
|
|
unspecified, so be careful when using expressions with side effects.
|
|
|
|
@example
|
|
(max 1 2 3) @result{} 3
|
|
|
|
(define (get-some-proc) min)
|
|
((get-some-proc) 1 2 3) @result{} 1
|
|
@end example
|
|
|
|
The same sort of parenthesised form is used for a macro invocation,
|
|
but in that case the arguments are not evaluated. See the
|
|
descriptions of macros for more on this (@pxref{Macros}, and
|
|
@pxref{Syntax Rules}).
|
|
|
|
@item @var{constant}
|
|
Number, string, character and boolean constants evaluate ``to
|
|
themselves'', so can appear as literals.
|
|
|
|
@example
|
|
123 @result{} 123
|
|
99.9 @result{} 99.9
|
|
"hello" @result{} "hello"
|
|
#\z @result{} #\z
|
|
#t @result{} #t
|
|
@end example
|
|
|
|
Note that an application must not attempt to modify literal strings,
|
|
since they may be in read-only memory.
|
|
|
|
@item (quote @var{data})
|
|
@itemx '@var{data}
|
|
@findex quote
|
|
@findex '
|
|
Quoting is used to obtain a literal symbol (instead of a variable
|
|
reference), a literal list (instead of a function call), or a literal
|
|
vector. @nicode{'} is simply a shorthand for a @code{quote} form.
|
|
For example,
|
|
|
|
@example
|
|
'x @result{} x
|
|
'(1 2 3) @result{} (1 2 3)
|
|
'#(1 (2 3) 4) @result{} #(1 (2 3) 4)
|
|
(quote x) @result{} x
|
|
(quote (1 2 3)) @result{} (1 2 3)
|
|
(quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4)
|
|
@end example
|
|
|
|
Note that an application must not attempt to modify literal lists or
|
|
vectors obtained from a @code{quote} form, since they may be in
|
|
read-only memory.
|
|
|
|
@item (quasiquote @var{data})
|
|
@itemx `@var{data}
|
|
@findex quasiquote
|
|
@findex `
|
|
Backquote quasi-quotation is like @code{quote}, but selected
|
|
sub-expressions are evaluated. This is a convenient way to construct
|
|
a list or vector structure most of which is constant, but at certain
|
|
points should have expressions substituted.
|
|
|
|
The same effect can always be had with suitable @code{list},
|
|
@code{cons} or @code{vector} calls, but quasi-quoting is often easier.
|
|
|
|
@table @nicode
|
|
|
|
@item (unquote @var{expr})
|
|
@itemx ,@var{expr}
|
|
@findex unquote
|
|
@findex ,
|
|
Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates
|
|
an expression to be evaluated and inserted. The comma syntax @code{,}
|
|
is simply a shorthand for an @code{unquote} form. For example,
|
|
|
|
@example
|
|
`(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4)
|
|
`(1 (unquote (+ 1 1)) 3) @result{} (1 2 3)
|
|
`#(1 ,(/ 12 2)) @result{} #(1 6)
|
|
@end example
|
|
|
|
@item (unquote-splicing @var{expr})
|
|
@itemx ,@@@var{expr}
|
|
@findex unquote-splicing
|
|
@findex ,@@
|
|
Within the quasiquote @var{data}, @code{unquote-splicing} or
|
|
@code{,@@} indicates an expression to be evaluated and the elements of
|
|
the returned list inserted. @var{expr} must evaluate to a list. The
|
|
``comma-at'' syntax @code{,@@} is simply a shorthand for an
|
|
@code{unquote-splicing} form.
|
|
|
|
@example
|
|
(define x '(2 3))
|
|
`(1 ,@@x 4) @result{} (1 2 3 4)
|
|
`(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4)
|
|
`#(9 ,@@x 9) @result{} #(9 2 3 9)
|
|
@end example
|
|
|
|
Notice @code{,@@} differs from plain @code{,} in the way one level of
|
|
nesting is stripped. For @code{,@@} the elements of a returned list
|
|
are inserted, whereas with @code{,} it would be the list itself
|
|
inserted.
|
|
@end table
|
|
|
|
@c
|
|
@c FIXME: What can we say about the mutability of a quasiquote
|
|
@c result? R5RS doesn't seem to specify anything, though where it
|
|
@c says backquote without commas is the same as plain quote then
|
|
@c presumably the "fixed" portions of a quasiquote expression must be
|
|
@c treated as immutable.
|
|
@c
|
|
|
|
@end table
|
|
|
|
|
|
@node Comments
|
|
@subsubsection Comments
|
|
|
|
@c FIXME::martin: Review me!
|
|
|
|
Comments in Scheme source files are written by starting them with a
|
|
semicolon character (@code{;}). The comment then reaches up to the end
|
|
of the line. Comments can begin at any column, and the may be inserted
|
|
on the same line as Scheme code.
|
|
|
|
@lisp
|
|
; Comment
|
|
;; Comment too
|
|
(define x 1) ; Comment after expression
|
|
(let ((y 1))
|
|
;; Display something.
|
|
(display y)
|
|
;;; Comment at left margin.
|
|
(display (+ y 1)))
|
|
@end lisp
|
|
|
|
It is common to use a single semicolon for comments following
|
|
expressions on a line, to use two semicolons for comments which are
|
|
indented like code, and three semicolons for comments which start at
|
|
column 0, even if they are inside an indented code block. This
|
|
convention is used when indenting code in Emacs' Scheme mode.
|
|
|
|
|
|
@node Block Comments
|
|
@subsubsection Block Comments
|
|
@cindex multiline comments
|
|
@cindex block comments
|
|
@cindex #!
|
|
@cindex !#
|
|
|
|
@c FIXME::martin: Review me!
|
|
|
|
In addition to the standard line comments defined by R5RS, Guile has
|
|
another comment type for multiline comments, called @dfn{block
|
|
comments}. This type of comment begins with the character sequence
|
|
@code{#!} and ends with the characters @code{!#}, which must appear on a
|
|
line of their own. These comments are compatible with the block
|
|
comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
|
|
(scsh)}). The characters @code{#!} were chosen because they are the
|
|
magic characters used in shell scripts for indicating that the name of
|
|
the program for executing the script follows on the same line.
|
|
|
|
Thus a Guile script often starts like this.
|
|
|
|
@lisp
|
|
#! /usr/local/bin/guile -s
|
|
!#
|
|
@end lisp
|
|
|
|
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
|
|
|
|
@c FIXME::martin: Review me!
|
|
|
|
Scheme as defined in R5RS is not case sensitive when reading symbols.
|
|
Guile, on the contrary is case sensitive by default, so the identifiers
|
|
|
|
@lisp
|
|
guile-whuzzy
|
|
Guile-Whuzzy
|
|
@end lisp
|
|
|
|
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}. 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.
|
|
|
|
|
|
@node Keyword Syntax
|
|
@subsubsection Keyword Syntax
|
|
|
|
|
|
@node Reader Extensions
|
|
@subsubsection Reader Extensions
|
|
|
|
@deffn {Scheme Procedure} read-hash-extend chr proc
|
|
@deffnx {C Function} scm_read_hash_extend (chr, proc)
|
|
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}.
|
|
Passing @code{#f} for @var{proc} will remove a previous setting.
|
|
|
|
@end deffn
|
|
|
|
|
|
@node Scheme Read
|
|
@subsection Reading Scheme Code
|
|
|
|
@rnindex read
|
|
@deffn {Scheme Procedure} read [port]
|
|
@deffnx {C Function} scm_read (port)
|
|
Read an s-expression from the input port @var{port}, or from
|
|
the current input port if @var{port} is not specified.
|
|
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.
|
|
|
|
@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.
|
|
@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 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. 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
|
|
|
|
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
|
|
|
|
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}.
|
|
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.
|
|
XXX - dynamic states.
|
|
Example: (eval '(+ 1 2) (interaction-environment))
|
|
@end deffn
|
|
|
|
@rnindex interaction-environment
|
|
@deffn {Scheme Procedure} interaction-environment
|
|
@deffnx {C Function} scm_interaction_environment ()
|
|
Return a specifier for the environment that contains
|
|
implementation--defined bindings, typically a superset of those
|
|
listed in the report. The intent is that this procedure will
|
|
return the environment in which the implementation would
|
|
evaluate expressions dynamically typed by the user.
|
|
@end deffn
|
|
|
|
@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)
|
|
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 in locale encoding instead
|
|
of an @code{SCM}.
|
|
@end deftypefn
|
|
|
|
@deffn {Scheme Procedure} apply proc arg1 @dots{} argN 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
|
|
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}.
|
|
|
|
@var{arglst} is not modified, but the @var{rest} list passed to
|
|
@code{scm_apply} is modified.
|
|
@end deffn
|
|
|
|
@deffn {C Function} scm_call_0 (proc)
|
|
@deffnx {C Function} scm_call_1 (proc, arg1)
|
|
@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}
|
|
@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.
|
|
|
|
This operation collects up the arguments from a list which is
|
|
@code{apply} style parameters.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Procedure} primitive-eval exp
|
|
@deffnx {C Function} scm_primitive_eval (exp)
|
|
Evaluate @var{exp} in the top-level environment specified by
|
|
the current module.
|
|
@end deffn
|
|
|
|
|
|
@node Compilation
|
|
@subsection Compiling Scheme Code
|
|
|
|
The @code{eval} procedure directly interprets the S-expression
|
|
representation of Scheme. An alternate strategy for evaluation is to
|
|
determine ahead of time what computations will be necessary to
|
|
evaluate the expression, and then use that recipe to produce the
|
|
desired results. This is known as @dfn{compilation}.
|
|
|
|
While it is possible to compile simple Scheme expressions such as
|
|
@code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
|
|
interesting in the context of procedures. Compiling a lambda expression
|
|
produces a compiled procedure, which is just like a normal procedure
|
|
except typically much faster, because it can bypass the generic
|
|
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}. 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
|
|
top-level expressions. Also, most needs for ``compile-time''
|
|
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}.
|
|
|
|
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;
|
|
otherwise @code{compile} is mostly equivalent to @code{eval}.
|
|
|
|
For a discussion of languages and compiler options, @xref{Compiling to
|
|
the Virtual Machine}.
|
|
@end deffn
|
|
|
|
@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 @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 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.
|
|
|
|
@var{reader} if provided should be either @code{#f}, or a procedure with
|
|
the signature @code{(lambda (port) @dots{})} which reads the next
|
|
expression from @var{port}. If @var{reader} is @code{#f} or absent,
|
|
Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
|
|
|
|
The @var{reader} argument takes effect by setting the value of the
|
|
@code{current-reader} fluid (see below) before loading the file, and
|
|
restoring its previous value when loading is complete. The Scheme code
|
|
inside @var{filename} can itself change the current reader procedure on
|
|
the fly by setting @code{current-reader} fluid.
|
|
|
|
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
|
|
documentation for @code{%load-hook} later in this section.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Procedure} load-compiled filename
|
|
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} 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. @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_primitive_load}, but taking a C string instead of an
|
|
@code{SCM}.
|
|
@end deftypefn
|
|
|
|
@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
|
|
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 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,
|
|
|
|
@example
|
|
(set! %load-hook (lambda (filename)
|
|
(format #t "Loading ~a ...\n" filename)))
|
|
(load-from-path "foo.scm")
|
|
@print{} Loading /usr/local/share/guile/site/foo.scm ...
|
|
@end example
|
|
@end defvar
|
|
|
|
@deffn {Scheme Procedure} current-load-port
|
|
@deffnx {C Function} scm_current_load_port ()
|
|
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.
|
|
|
|
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
|
|
a file to load. By default, @code{%load-extensions} is bound to the
|
|
list @code{("" ".scm")}.
|
|
@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
|
|
@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.
|
|
|
|
@deffn syntax delay expr
|
|
@rnindex delay
|
|
Return a promise object which holds the given @var{expr} expression,
|
|
ready to be evaluated by a later @code{force}.
|
|
@end deffn
|
|
|
|
@deffn {Scheme Procedure} promise? obj
|
|
@deffnx {C Function} scm_promise_p (obj)
|
|
Return true if @var{obj} is a promise.
|
|
@end deffn
|
|
|
|
@rnindex force
|
|
@deffn {Scheme Procedure} force p
|
|
@deffnx {C Function} scm_force (p)
|
|
Return the value obtained from evaluating the @var{expr} in the given
|
|
promise @var{p}. If @var{p} has previously been forced then its
|
|
@var{expr} is not evaluated again, instead the value obtained at that
|
|
time is simply returned.
|
|
|
|
During a @code{force}, an @var{expr} can call @code{force} again on
|
|
its own promise, resulting in a recursive evaluation of that
|
|
@var{expr}. The first evaluation to return gives the value for the
|
|
promise. Higher evaluations run to completion in the normal way, but
|
|
their results are ignored, @code{force} always returns the first
|
|
value.
|
|
@end deffn
|
|
|
|
|
|
@c Local Variables:
|
|
@c TeX-master: "guile.texi"
|
|
@c End:
|