2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Read/Load/Eval/Compile
8 @section Reading and Evaluating Scheme Code
10 This chapter describes Guile functions that are concerned with reading,
11 loading, evaluating, and compiling Scheme code at run time.
14 * Scheme Syntax:: Standard and extended Scheme syntax.
15 * Scheme Read:: Reading Scheme code.
16 * Scheme Write:: Writing Scheme values to a port.
17 * Fly Evaluation:: Procedures for on the fly evaluation.
18 * Compilation:: How to compile Scheme files and procedures.
19 * Loading:: Loading Scheme code from file.
20 * Load Paths:: Where Guile looks for code.
21 * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file.
22 * Delayed Evaluation:: Postponing evaluation until it is needed.
23 * Local Evaluation:: Evaluation in a local lexical environment.
24 * Local Inclusion:: Compile-time inclusion of one file in another.
29 @subsection Scheme Syntax: Standard and Guile Extensions
41 @node Expression Syntax
42 @subsubsection Expression Syntax
44 An expression to be evaluated takes one of the following forms.
49 A symbol is evaluated by dereferencing. A binding of that symbol is
50 sought and the value there used. For example,
57 @item (@var{proc} @var{args}@dots{})
58 A parenthesised expression is a function call. @var{proc} and each
59 argument are evaluated, then the function (which @var{proc} evaluated
60 to) is called with those arguments.
62 The order in which @var{proc} and the arguments are evaluated is
63 unspecified, so be careful when using expressions with side effects.
66 (max 1 2 3) @result{} 3
68 (define (get-some-proc) min)
69 ((get-some-proc) 1 2 3) @result{} 1
72 The same sort of parenthesised form is used for a macro invocation,
73 but in that case the arguments are not evaluated. See the
74 descriptions of macros for more on this (@pxref{Macros}, and
75 @pxref{Syntax Rules}).
78 Number, string, character and boolean constants evaluate ``to
79 themselves'', so can appear as literals.
84 "hello" @result{} "hello"
89 Note that an application must not attempt to modify literal strings,
90 since they may be in read-only memory.
92 @item (quote @var{data})
96 Quoting is used to obtain a literal symbol (instead of a variable
97 reference), a literal list (instead of a function call), or a literal
98 vector. @nicode{'} is simply a shorthand for a @code{quote} form.
103 '(1 2 3) @result{} (1 2 3)
104 '#(1 (2 3) 4) @result{} #(1 (2 3) 4)
105 (quote x) @result{} x
106 (quote (1 2 3)) @result{} (1 2 3)
107 (quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4)
110 Note that an application must not attempt to modify literal lists or
111 vectors obtained from a @code{quote} form, since they may be in
114 @item (quasiquote @var{data})
118 Backquote quasi-quotation is like @code{quote}, but selected
119 sub-expressions are evaluated. This is a convenient way to construct
120 a list or vector structure most of which is constant, but at certain
121 points should have expressions substituted.
123 The same effect can always be had with suitable @code{list},
124 @code{cons} or @code{vector} calls, but quasi-quoting is often easier.
128 @item (unquote @var{expr})
132 Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates
133 an expression to be evaluated and inserted. The comma syntax @code{,}
134 is simply a shorthand for an @code{unquote} form. For example,
137 `(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4)
138 `(1 (unquote (+ 1 1)) 3) @result{} (1 2 3)
139 `#(1 ,(/ 12 2)) @result{} #(1 6)
142 @item (unquote-splicing @var{expr})
144 @findex unquote-splicing
146 Within the quasiquote @var{data}, @code{unquote-splicing} or
147 @code{,@@} indicates an expression to be evaluated and the elements of
148 the returned list inserted. @var{expr} must evaluate to a list. The
149 ``comma-at'' syntax @code{,@@} is simply a shorthand for an
150 @code{unquote-splicing} form.
154 `(1 ,@@x 4) @result{} (1 2 3 4)
155 `(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4)
156 `#(9 ,@@x 9) @result{} #(9 2 3 9)
159 Notice @code{,@@} differs from plain @code{,} in the way one level of
160 nesting is stripped. For @code{,@@} the elements of a returned list
161 are inserted, whereas with @code{,} it would be the list itself
166 @c FIXME: What can we say about the mutability of a quasiquote
167 @c result? R5RS doesn't seem to specify anything, though where it
168 @c says backquote without commas is the same as plain quote then
169 @c presumably the "fixed" portions of a quasiquote expression must be
170 @c treated as immutable.
177 @subsubsection Comments
179 @c FIXME::martin: Review me!
181 Comments in Scheme source files are written by starting them with a
182 semicolon character (@code{;}). The comment then reaches up to the end
183 of the line. Comments can begin at any column, and the may be inserted
184 on the same line as Scheme code.
189 (define x 1) ; Comment after expression
191 ;; Display something.
193 ;;; Comment at left margin.
197 It is common to use a single semicolon for comments following
198 expressions on a line, to use two semicolons for comments which are
199 indented like code, and three semicolons for comments which start at
200 column 0, even if they are inside an indented code block. This
201 convention is used when indenting code in Emacs' Scheme mode.
205 @subsubsection Block Comments
206 @cindex multiline comments
207 @cindex block comments
211 @c FIXME::martin: Review me!
213 In addition to the standard line comments defined by R5RS, Guile has
214 another comment type for multiline comments, called @dfn{block
215 comments}. This type of comment begins with the character sequence
216 @code{#!} and ends with the characters @code{!#}, which must appear on a
217 line of their own. These comments are compatible with the block
218 comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
219 (scsh)}). The characters @code{#!} were chosen because they are the
220 magic characters used in shell scripts for indicating that the name of
221 the program for executing the script follows on the same line.
223 Thus a Guile script often starts like this.
226 #! /usr/local/bin/guile -s
230 More details on Guile scripting can be found in the scripting section
231 (@pxref{Guile Scripting}).
233 @cindex R6RS block comments
234 @cindex SRFI-30 block comments
235 Similarly, Guile (starting from version 2.0) supports nested block
236 comments as specified by R6RS and
237 @url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}:
240 (+ #| this is a #| nested |# block comment |# 2)
244 For backward compatibility, this syntax can be overridden with
245 @code{read-hash-extend} (@pxref{Reader Extensions,
246 @code{read-hash-extend}}).
248 There is one special case where the contents of a comment can actually
249 affect the interpretation of code. When a character encoding
250 declaration, such as @code{coding: utf-8} appears in one of the first
251 few lines of a source file, it indicates to Guile's default reader
252 that this source code file is not ASCII. For details see @ref{Character
253 Encoding of Source Files}.
255 @node Case Sensitivity
256 @subsubsection Case Sensitivity
260 @c FIXME::martin: Review me!
262 Scheme as defined in R5RS is not case sensitive when reading symbols.
263 Guile, on the contrary is case sensitive by default, so the identifiers
270 are the same in R5RS Scheme, but are different in Guile.
272 It is possible to turn off case sensitivity in Guile by setting the
273 reader option @code{case-insensitive}. For more information on reader
274 options, @xref{Scheme Read}.
277 (read-enable 'case-insensitive)
280 It is also possible to disable (or enable) case sensitivity within a
281 single file by placing the reader directives @code{#!fold-case} (or
282 @code{#!no-fold-case}) within the file itself.
285 @subsubsection Keyword Syntax
288 @node Reader Extensions
289 @subsubsection Reader Extensions
291 @deffn {Scheme Procedure} read-hash-extend chr proc
292 @deffnx {C Function} scm_read_hash_extend (chr, proc)
293 Install the procedure @var{proc} for reading expressions
294 starting with the character sequence @code{#} and @var{chr}.
295 @var{proc} will be called with two arguments: the character
296 @var{chr} and the port to read further data from. The object
297 returned will be the return value of @code{read}.
298 Passing @code{#f} for @var{proc} will remove a previous setting.
304 @subsection Reading Scheme Code
307 @deffn {Scheme Procedure} read [port]
308 @deffnx {C Function} scm_read (port)
309 Read an s-expression from the input port @var{port}, or from
310 the current input port if @var{port} is not specified.
311 Any whitespace before the next token is discarded.
314 The behaviour of Guile's Scheme reader can be modified by manipulating
317 @cindex options - read
319 @deffn {Scheme Procedure} read-options [setting]
320 Display the current settings of the global read options. If
321 @var{setting} is omitted, only a short form of the current read options
322 is printed. Otherwise if @var{setting} is the symbol @code{help}, a
323 complete options description is displayed.
326 The set of available options, and their default values, may be had by
327 invoking @code{read-options} at the prompt.
330 scheme@@(guile-user)> (read-options)
331 (square-brackets keywords #f positions)
332 scheme@@(guile-user)> (read-options 'help)
333 copy no Copy source code expressions.
334 positions yes Record positions of source code expressions.
335 case-insensitive no Convert symbols to lower case.
336 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
337 r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
338 square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
339 hungry-eol-escapes no In strings, consume leading whitespace after an
341 curly-infix no Support SRFI-105 curly infix expressions.
344 Note that Guile also includes a preliminary mechanism for setting read
345 options on a per-port basis. For instance, the @code{case-insensitive}
346 read option is set (or unset) on the port when the reader encounters the
347 @code{#!fold-case} or @code{#!no-fold-case} reader directives.
348 Similarly, the @code{#!curly-infix} reader directive sets the
349 @code{curly-infix} read option on the port, and
350 @code{#!curly-infix-and-bracket-lists} sets @code{curly-infix} and
351 unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is
352 currently no other way to access or set the per-port read options.
354 The boolean options may be toggled with @code{read-enable} and
355 @code{read-disable}. The non-boolean @code{keywords} option must be set
356 using @code{read-set!}.
358 @deffn {Scheme Procedure} read-enable option-name
359 @deffnx {Scheme Procedure} read-disable option-name
360 @deffnx {Scheme Syntax} read-set! option-name value
361 Modify the read options. @code{read-enable} should be used with boolean
362 options and switches them on, @code{read-disable} switches them off.
364 @code{read-set!} can be used to set an option to a specific value. Due
365 to historical oddities, it is a macro that expects an unquoted option
369 For example, to make @code{read} fold all symbols to their lower case
370 (perhaps for compatibility with older Scheme code), you can enter:
373 (read-enable 'case-insensitive)
376 For more information on the effect of the @code{r6rs-hex-escapes} and
377 @code{hungry-eol-escapes} options, see (@pxref{String Syntax}).
381 @subsection Writing Scheme Values
383 Any scheme value may be written to a port. Not all values may be read
384 back in (@pxref{Scheme Read}), however.
388 @deffn {Scheme Procedure} write obj [port]
389 Send a representation of @var{obj} to @var{port} or to the current
390 output port if not given.
392 The output is designed to be machine readable, and can be read back
393 with @code{read} (@pxref{Scheme Read}). Strings are printed in
394 double quotes, with escapes if necessary, and characters are printed in
399 @deffn {Scheme Procedure} display obj [port]
400 Send a representation of @var{obj} to @var{port} or to the current
401 output port if not given.
403 The output is designed for human readability, it differs from
404 @code{write} in that strings are printed without double quotes and
405 escapes, and characters are printed as per @code{write-char}, not in
409 As was the case with the Scheme reader, there are a few options that
410 affect the behavior of the Scheme printer.
412 @cindex options - print
413 @cindex print options
414 @deffn {Scheme Procedure} print-options [setting]
415 Display the current settings of the read options. If @var{setting} is
416 omitted, only a short form of the current read options is
417 printed. Otherwise if @var{setting} is the symbol @code{help}, a
418 complete options description is displayed.
421 The set of available options, and their default values, may be had by
422 invoking @code{print-options} at the prompt.
425 scheme@@(guile-user)> (print-options)
426 (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{")
427 scheme@@(guile-user)> (print-options 'help)
428 highlight-prefix @{ The string to print before highlighted values.
429 highlight-suffix @} The string to print after highlighted values.
430 quote-keywordish-symbols reader How to print symbols that have a colon
431 as their first or last character. The
432 value '#f' does not quote the colons;
433 '#t' quotes them; 'reader' quotes them
434 when the reader option 'keywords' is
436 escape-newlines yes Render newlines as \n when printing
440 These options may be modified with the print-set! syntax.
442 @deffn {Scheme Syntax} print-set! option-name value
443 Modify the print options. Due to historical oddities, @code{print-set!}
444 is a macro that expects an unquoted option name.
449 @subsection Procedures for On the Fly Evaluation
451 Scheme has the lovely property that its expressions may be represented
452 as data. The @code{eval} procedure takes a Scheme datum and evaluates
456 @c ARGFIXME environment/environment specifier
457 @deffn {Scheme Procedure} eval exp module_or_state
458 @deffnx {C Function} scm_eval (exp, module_or_state)
459 Evaluate @var{exp}, a list representing a Scheme expression,
460 in the top-level environment specified by @var{module_or_state}.
461 While @var{exp} is evaluated (using @code{primitive-eval}),
462 @var{module_or_state} is made the current module. The current module
463 is reset to its previous value when @code{eval} returns.
464 XXX - dynamic states.
465 Example: (eval '(+ 1 2) (interaction-environment))
468 @rnindex interaction-environment
469 @deffn {Scheme Procedure} interaction-environment
470 @deffnx {C Function} scm_interaction_environment ()
471 Return a specifier for the environment that contains
472 implementation--defined bindings, typically a superset of those
473 listed in the report. The intent is that this procedure will
474 return the environment in which the implementation would
475 evaluate expressions dynamically typed by the user.
478 @xref{Environments}, for other environments.
480 One does not always receive code as Scheme data, of course, and this is
481 especially the case for Guile's other language implementations
482 (@pxref{Other Languages}). For the case in which all you have is a
483 string, we have @code{eval-string}. There is a legacy version of this
484 procedure in the default environment, but you really want the one from
485 @code{(ice-9 eval-string)}, so load it up:
488 (use-modules (ice-9 eval-string))
491 @deffn {Scheme Procedure} eval-string string [module=#f] [file=#f] [line=#f] [column=#f] [lang=(current-language)] [compile?=#f]
492 Parse @var{string} according to the current language, normally Scheme.
493 Evaluate or compile the expressions it contains, in order, returning the
496 If the @var{module} keyword argument is set, save a module excursion
497 (@pxref{Module System Reflection}) and set the current module to
498 @var{module} before evaluation.
500 The @var{file}, @var{line}, and @var{column} keyword arguments can be
501 used to indicate that the source string begins at a particular source
504 Finally, @var{lang} is a language, defaulting to the current language,
505 and the expression is compiled if @var{compile?} is true or there is no
506 evaluator for the given language.
509 @deffn {C Function} scm_eval_string (string)
510 @deffnx {C Function} scm_eval_string_in_module (string, module)
511 These C bindings call @code{eval-string} from @code{(ice-9
512 eval-string)}, evaluating within @var{module} or the current module.
515 @deftypefn {C Function} SCM scm_c_eval_string (const char *string)
516 @code{scm_eval_string}, but taking a C string in locale encoding instead
520 @deffn {Scheme Procedure} apply proc arg @dots{} arglst
521 @deffnx {C Function} scm_apply_0 (proc, arglst)
522 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
523 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
524 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
525 @deffnx {C Function} scm_apply (proc, arg, rest)
527 Call @var{proc} with arguments @var{arg} @dots{} and the
528 elements of the @var{arglst} list.
530 @code{scm_apply} takes parameters corresponding to a Scheme level
531 @code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the
532 last element of the @var{rest} list make up @var{arg} @dots{}, and the
533 last element of @var{rest} is the @var{arglst} list. Or if @var{rest}
534 is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and
535 (@var{arg1}) is the @var{arglst}.
537 @var{arglst} is not modified, but the @var{rest} list passed to
538 @code{scm_apply} is modified.
541 @deffn {C Function} scm_call_0 (proc)
542 @deffnx {C Function} scm_call_1 (proc, arg1)
543 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
544 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
545 @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
546 @deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
547 @deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
548 @deffnx {C Function} scm_call_7 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
549 @deffnx {C Function} scm_call_8 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
550 @deffnx {C Function} scm_call_9 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
551 Call @var{proc} with the given arguments.
554 @deffn {C Function} scm_call (proc, ...)
555 Call @var{proc} with any number of arguments. The argument list must be
556 terminated by @code{SCM_UNDEFINED}. For example:
559 scm_call (scm_c_public_ref ("guile", "+"),
566 @deffn {C Function} scm_call_n (proc, argv, nargs)
567 Call @var{proc} with the array of arguments @var{argv}, as a
568 @code{SCM*}. The length of the arguments should be passed in
569 @var{nargs}, as a @code{size_t}.
572 @deffn {Scheme Procedure} apply:nconc2last lst
573 @deffnx {C Function} scm_nconc2last (lst)
574 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
575 @var{arglst}), with @var{arglst} being a list. This function returns
576 a list comprising @var{arg1} to @var{argN} plus the elements of
577 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
578 is not modified, though the return does share structure with it.
580 This operation collects up the arguments from a list which is
581 @code{apply} style parameters.
584 @deffn {Scheme Procedure} primitive-eval exp
585 @deffnx {C Function} scm_primitive_eval (exp)
586 Evaluate @var{exp} in the top-level environment specified by
592 @subsection Compiling Scheme Code
594 The @code{eval} procedure directly interprets the S-expression
595 representation of Scheme. An alternate strategy for evaluation is to
596 determine ahead of time what computations will be necessary to
597 evaluate the expression, and then use that recipe to produce the
598 desired results. This is known as @dfn{compilation}.
600 While it is possible to compile simple Scheme expressions such as
601 @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
602 interesting in the context of procedures. Compiling a lambda expression
603 produces a compiled procedure, which is just like a normal procedure
604 except typically much faster, because it can bypass the generic
607 Functions from system modules in a Guile installation are normally
608 compiled already, so they load and run quickly.
610 @cindex automatic compilation
611 Note that well-written Scheme programs will not typically call the
612 procedures in this section, for the same reason that it is often bad
613 taste to use @code{eval}. By default, Guile automatically compiles any
614 files it encounters that have not been compiled yet (@pxref{Invoking
615 Guile, @code{--auto-compile}}). The compiler can also be invoked
616 explicitly from the shell as @code{guild compile foo.scm}.
618 (Why are calls to @code{eval} and @code{compile} usually in bad taste?
619 Because they are limited, in that they can only really make sense for
620 top-level expressions. Also, most needs for ``compile-time''
621 computation are fulfilled by macros and closures. Of course one good
622 counterexample is the REPL itself, or any code that reads expressions
625 Automatic compilation generally works transparently, without any need
626 for user intervention. However Guile does not yet do proper dependency
627 tracking, so that if file @file{@var{a}.scm} uses macros from
628 @file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm}
629 would not be automatically recompiled. To forcibly invalidate the
630 auto-compilation cache, pass the @code{--fresh-auto-compile} option to
631 Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to
632 @code{fresh} (instead of to @code{0} or @code{1}).
634 For more information on the compiler itself, see @ref{Compiling to the
635 Virtual Machine}. For information on the virtual machine, see @ref{A
636 Virtual Machine for Guile}.
638 The command-line interface to Guile's compiler is the @command{guild
641 @deffn {Command} {guild compile} [@option{option}...] @var{file}...
642 Compile @var{file}, a source file, and store bytecode in the compilation cache
643 or in the file specified by the @option{-o} option. The following options are
649 @itemx --load-path=@var{dir}
650 Add @var{dir} to the front of the module load path.
653 @itemx --output=@var{ofile}
654 Write output bytecode to @var{ofile}. By convention, bytecode file
655 names end in @code{.go}. When @option{-o} is omitted, the output file
656 name is as for @code{compile-file} (see below).
658 @item -W @var{warning}
659 @itemx --warn=@var{warning}
660 @cindex warnings, compiler
661 Emit warnings of type @var{warning}; use @code{--warn=help} for a list
662 of available warnings and their description. Currently recognized
663 warnings include @code{unused-variable}, @code{unused-toplevel},
664 @code{unbound-variable}, @code{arity-mismatch}, and @code{format}.
667 @itemx --from=@var{lang}
668 Use @var{lang} as the source language of @var{file}. If this option is omitted,
669 @code{scheme} is assumed.
672 @itemx --to=@var{lang}
673 Use @var{lang} as the target language of @var{file}. If this option is omitted,
674 @code{objcode} is assumed.
676 @item -T @var{target}
677 @itemx --target=@var{target}
678 Produce bytecode for @var{target} instead of @var{%host-type}
679 (@pxref{Build Config, %host-type}). Target must be a valid GNU triplet,
680 such as @code{armv5tel-unknown-linux-gnueabi} (@pxref{Specifying Target
681 Triplets,,, autoconf, GNU Autoconf Manual}).
685 Each @var{file} is assumed to be UTF-8-encoded, unless it contains a
686 coding declaration as recognized by @code{file-encoding}
687 (@pxref{Character Encoding of Source Files}).
690 The compiler can also be invoked directly by Scheme code using the procedures
693 @deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()]
694 Compile the expression @var{exp} in the environment @var{env}. If
695 @var{exp} is a procedure, the result will be a compiled procedure;
696 otherwise @code{compile} is mostly equivalent to @code{eval}.
698 For a discussion of languages and compiler options, @xref{Compiling to
699 the Virtual Machine}.
702 @deffn {Scheme Procedure} compile-file file [output-file=#f] @
703 [from=(current-language)] [to='objcode] @
704 [env=(default-environment from)] [opts='()] @
705 [canonicalization 'relative]
706 Compile the file named @var{file}.
708 Output will be written to a @var{output-file}. If you do not supply an
709 output file name, output is written to a file in the cache directory, as
710 computed by @code{(compiled-file-name @var{file})}.
712 @var{from} and @var{to} specify the source and target languages.
713 @xref{Compiling to the Virtual Machine}, for more information on these
714 options, and on @var{env} and @var{opts}.
716 As with @command{guild compile}, @var{file} is assumed to be
717 UTF-8-encoded unless it contains a coding declaration.
720 @deffn {Scheme Procedure} compiled-file-name file
721 Compute a cached location for a compiled version of a Scheme file named
724 This file will usually be below the @file{$HOME/.cache/guile/ccache}
725 directory, depending on the value of the @env{XDG_CACHE_HOME}
726 environment variable. The intention is that @code{compiled-file-name}
727 provides a fallback location for caching auto-compiled files. If you
728 want to place a compile file in the @code{%load-compiled-path}, you
729 should pass the @var{output-file} option to @code{compile-file},
733 @defvr {Scheme Variable} %auto-compilation-options
734 This variable contains the options passed to the @code{compile-file}
735 procedure when auto-compiling source files. By default, it enables
736 useful compilation warnings. It can be customized from @file{~/.guile}.
740 @subsection Loading Scheme Code from File
743 @deffn {Scheme Procedure} load filename [reader]
744 Load @var{filename} and evaluate its contents in the top-level
747 @var{reader} if provided should be either @code{#f}, or a procedure with
748 the signature @code{(lambda (port) @dots{})} which reads the next
749 expression from @var{port}. If @var{reader} is @code{#f} or absent,
750 Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
752 The @var{reader} argument takes effect by setting the value of the
753 @code{current-reader} fluid (see below) before loading the file, and
754 restoring its previous value when loading is complete. The Scheme code
755 inside @var{filename} can itself change the current reader procedure on
756 the fly by setting @code{current-reader} fluid.
758 If the variable @code{%load-hook} is defined, it should be bound to a
759 procedure that will be called before any code is loaded. See
760 documentation for @code{%load-hook} later in this section.
763 @deffn {Scheme Procedure} load-compiled filename
764 Load the compiled file named @var{filename}.
766 Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
767 calling @code{load-compiled} on the resulting file is equivalent to
768 calling @code{load} on the source file.
771 @deffn {Scheme Procedure} primitive-load filename
772 @deffnx {C Function} scm_primitive_load (filename)
773 Load the file named @var{filename} and evaluate its contents in the
774 top-level environment. @var{filename} must either be a full pathname or
775 be a pathname relative to the current directory. If the variable
776 @code{%load-hook} is defined, it should be bound to a procedure that
777 will be called before any code is loaded. See the documentation for
778 @code{%load-hook} later in this section.
781 @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
782 @code{scm_primitive_load}, but taking a C string instead of an
786 @defvar current-reader
787 @code{current-reader} holds the read procedure that is currently being
788 used by the above loading procedures to read expressions (from the file
789 that they are loading). @code{current-reader} is a fluid, so it has an
790 independent value in each dynamic root and should be read and set using
791 @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
794 Changing @code{current-reader} is typically useful to introduce local
795 syntactic changes, such that code following the @code{fluid-set!} call
796 is read using the newly installed reader. The @code{current-reader}
797 change should take place at evaluation time when the code is evaluated,
798 or at compilation time when the code is compiled:
802 (eval-when (compile eval)
803 (fluid-set! current-reader my-own-reader))
806 The @code{eval-when} form above ensures that the @code{current-reader}
807 change occurs at the right time.
811 A procedure to be called @code{(%load-hook @var{filename})} whenever a
812 file is loaded, or @code{#f} for no such call. @code{%load-hook} is
813 used by all of the loading functions (@code{load} and
814 @code{primitive-load}, and @code{load-from-path} and
815 @code{primitive-load-path} documented in the next section).
817 For example an application can set this to show what's loaded,
820 (set! %load-hook (lambda (filename)
821 (format #t "Loading ~a ...\n" filename)))
822 (load-from-path "foo.scm")
823 @print{} Loading /usr/local/share/guile/site/foo.scm ...
827 @deffn {Scheme Procedure} current-load-port
828 @deffnx {C Function} scm_current_load_port ()
829 Return the current-load-port.
830 The load port is used internally by @code{primitive-load}.
834 @subsection Load Paths
836 The procedure in the previous section look for Scheme code in the file
837 system at specific location. Guile also has some procedures to search
838 the load path for code.
840 @cindex @env{GUILE_LOAD_PATH}
842 List of directories which should be searched for Scheme modules and
843 libraries. @code{%load-path} is initialized when Guile starts up to
844 @code{(list (%site-dir) (%library-dir) (%package-data-dir))}, prepended
845 with the contents of the @env{GUILE_LOAD_PATH} environment variable, if
846 it is set. @xref{Build Config}, for more on @code{%site-dir} and
850 @deffn {Scheme Procedure} load-from-path filename
851 Similar to @code{load}, but searches for @var{filename} in the load
852 paths. Preferentially loads a compiled version of the file, if it is
853 available and up-to-date.
856 A user can extend the load path by calling @code{add-to-load-path}.
858 @deffn {Scheme Syntax} add-to-load-path dir
859 Add @var{dir} to the load path.
862 For example, a script might include this form to add the directory that
863 it is in to the load path:
866 (add-to-load-path (dirname (current-filename)))
869 It's better to use @code{add-to-load-path} than to modify
870 @code{%load-path} directly, because @code{add-to-load-path} takes care
871 of modifying the path both at compile-time and at run-time.
873 @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
874 @deffnx {C Function} scm_primitive_load_path (filename)
875 Search @code{%load-path} for the file named @var{filename} and
876 load it into the top-level environment. If @var{filename} is a
877 relative pathname and is not found in the list of search paths,
878 an error is signalled. Preferentially loads a compiled version of the
879 file, if it is available and up-to-date.
881 By default or if @var{exception-on-not-found} is true, an exception is
882 raised if @var{filename} is not found. If @var{exception-on-not-found}
883 is @code{#f} and @var{filename} is not found, no exception is raised and
884 @code{#f} is returned. For compatibility with Guile 1.8 and earlier,
885 the C function takes only one argument, which can be either a string
886 (the file name) or an argument list.
889 @deffn {Scheme Procedure} %search-load-path filename
890 @deffnx {C Function} scm_sys_search_load_path (filename)
891 Search @code{%load-path} for the file named @var{filename}, which must
892 be readable by the current user. If @var{filename} is found in the list
893 of paths to search or is an absolute pathname, return its full pathname.
894 Otherwise, return @code{#f}. Filenames may have any of the optional
895 extensions in the @code{%load-extensions} list; @code{%search-load-path}
896 will try each extension automatically.
899 @defvar %load-extensions
900 A list of default file extensions for files containing Scheme code.
901 @code{%search-load-path} tries each of these extensions when looking for
902 a file to load. By default, @code{%load-extensions} is bound to the
903 list @code{("" ".scm")}.
906 As mentioned above, when Guile searches the @code{%load-path} for a
907 source file, it will also search the @code{%load-compiled-path} for a
908 corresponding compiled file. If the compiled file is as new or newer
909 than the source file, it will be loaded instead of the source file,
910 using @code{load-compiled}.
912 @defvar %load-compiled-path
913 Like @code{%load-path}, but for compiled files. By default, this path
914 has two entries: one for compiled files from Guile itself, and one for
918 When @code{primitive-load-path} searches the @code{%load-compiled-path}
919 for a corresponding compiled file for a relative path it does so by
920 appending @code{.go} to the relative path. For example, searching for
921 @code{ice-9/popen} could find
922 @code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
923 @code{/usr/share/guile/2.0/ice-9/popen.scm}.
925 If @code{primitive-load-path} does not find a corresponding @code{.go}
926 file in the @code{%load-compiled-path}, or the @code{.go} file is out of
927 date, it will search for a corresponding auto-compiled file in the
928 fallback path, possibly creating one if one does not exist.
930 @xref{Installing Site Packages}, for more on how to correctly install
931 site packages. @xref{Modules and the File System}, for more on the
932 relationship between load paths and modules. @xref{Compilation}, for
933 more on the fallback path and auto-compilation.
935 Finally, there are a couple of helper procedures for general path
938 @deffn {Scheme Procedure} parse-path path [tail]
939 @deffnx {C Function} scm_parse_path (path, tail)
940 Parse @var{path}, which is expected to be a colon-separated string, into
941 a list and return the resulting list with @var{tail} appended. If
942 @var{path} is @code{#f}, @var{tail} is returned.
945 @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
946 @deffnx {C Function} scm_search_path (path, filename, rest)
947 Search @var{path} for a directory containing a file named
948 @var{filename}. The file must be readable, and not a directory. If we
949 find one, return its full filename; otherwise, return @code{#f}. If
950 @var{filename} is absolute, return it unchanged. If given,
951 @var{extensions} is a list of strings; for each directory in @var{path},
952 we search for @var{filename} concatenated with each @var{extension}. If
953 @var{require-exts?} is true, require that the returned file name have
954 one of the given extensions; if @var{require-exts?} is not given, it
955 defaults to @code{#f}.
957 For compatibility with Guile 1.8 and earlier, the C function takes only
962 @node Character Encoding of Source Files
963 @subsection Character Encoding of Source Files
965 @cindex source file encoding
966 @cindex primitive-load
968 Scheme source code files are usually encoded in ASCII, but, the
969 built-in reader can interpret other character encodings. The
970 procedure @code{primitive-load}, and by extension the functions that
971 call it, such as @code{load}, first scan the top 500 characters of the
972 file for a coding declaration.
974 A coding declaration has the form @code{coding: XXXXXX}, where
975 @code{XXXXXX} is the name of a character encoding in which the source
976 code file has been encoded. The coding declaration must appear in a
977 scheme comment. It can either be a semicolon-initiated comment or a block
980 The name of the character encoding in the coding declaration is
981 typically lower case and containing only letters, numbers, and hyphens,
982 as recognized by @code{set-port-encoding!} (@pxref{Ports,
983 @code{set-port-encoding!}}). Common examples of character encoding
984 names are @code{utf-8} and @code{iso-8859-1},
985 @url{http://www.iana.org/assignments/character-sets, as defined by
986 IANA}. Thus, the coding declaration is mostly compatible with Emacs.
988 However, there are some differences in encoding names recognized by
989 Emacs and encoding names defined by IANA, the latter being essentially a
990 subset of the former. For instance, @code{latin-1} is a valid encoding
991 name for Emacs, but it's not according to the IANA standard, which Guile
992 follows; instead, you should use @code{iso-8859-1}, which is both
993 understood by Emacs and dubbed by IANA (IANA writes it uppercase but
994 Emacs wants it lowercase and Guile is case insensitive.)
996 For source code, only a subset of all possible character encodings can
997 be interpreted by the built-in source code reader. Only those
998 character encodings in which ASCII text appears unmodified can be
999 used. This includes @code{UTF-8} and @code{ISO-8859-1} through
1000 @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
1001 and @code{UTF-32} may not be used because they are not compatible with
1006 @cindex port encoding
1007 @findex set-port-encoding!
1008 There might be a scenario in which one would want to read non-ASCII
1009 code from a port, such as with the function @code{read}, instead of
1010 with @code{load}. If the port's character encoding is the same as the
1011 encoding of the code to be read by the port, not other special
1012 handling is necessary. The port will automatically do the character
1013 encoding conversion. The functions @code{setlocale} or by
1014 @code{set-port-encoding!} are used to set port encodings
1017 If a port is used to read code of unknown character encoding, it can
1018 accomplish this in three steps. First, the character encoding of the
1019 port should be set to ISO-8859-1 using @code{set-port-encoding!}.
1020 Then, the procedure @code{file-encoding}, described below, is used to
1021 scan for a coding declaration when reading from the port. As a side
1022 effect, it rewinds the port after its scan is complete. After that,
1023 the port's character encoding should be set to the encoding returned
1024 by @code{file-encoding}, if any, again by using
1025 @code{set-port-encoding!}. Then the code can be read as normal.
1027 @deffn {Scheme Procedure} file-encoding port
1028 @deffnx {C Function} scm_file_encoding (port)
1029 Scan the port for an Emacs-like character coding declaration near the
1030 top of the contents of a port with random-accessible contents
1031 (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs,
1032 The GNU Emacs Reference Manual}). The coding declaration is of the form
1033 @code{coding: XXXXX} and must appear in a Scheme comment. Return a
1034 string containing the character encoding of the file if a declaration
1035 was found, or @code{#f} otherwise. The port is rewound.
1039 @node Delayed Evaluation
1040 @subsection Delayed Evaluation
1041 @cindex delayed evaluation
1044 Promises are a convenient way to defer a calculation until its result
1045 is actually needed, and to run such a calculation only once.
1047 @deffn syntax delay expr
1049 Return a promise object which holds the given @var{expr} expression,
1050 ready to be evaluated by a later @code{force}.
1053 @deffn {Scheme Procedure} promise? obj
1054 @deffnx {C Function} scm_promise_p (obj)
1055 Return true if @var{obj} is a promise.
1059 @deffn {Scheme Procedure} force p
1060 @deffnx {C Function} scm_force (p)
1061 Return the value obtained from evaluating the @var{expr} in the given
1062 promise @var{p}. If @var{p} has previously been forced then its
1063 @var{expr} is not evaluated again, instead the value obtained at that
1064 time is simply returned.
1066 During a @code{force}, an @var{expr} can call @code{force} again on
1067 its own promise, resulting in a recursive evaluation of that
1068 @var{expr}. The first evaluation to return gives the value for the
1069 promise. Higher evaluations run to completion in the normal way, but
1070 their results are ignored, @code{force} always returns the first
1075 @node Local Evaluation
1076 @subsection Local Evaluation
1078 Guile includes a facility to capture a lexical environment, and later
1079 evaluate a new expression within that environment. This code is
1080 implemented in a module.
1083 (use-modules (ice-9 local-eval))
1086 @deffn syntax the-environment
1087 Captures and returns a lexical environment for use with
1088 @code{local-eval} or @code{local-compile}.
1091 @deffn {Scheme Procedure} local-eval exp env
1092 @deffnx {C Function} scm_local_eval (exp, env)
1093 @deffnx {Scheme Procedure} local-compile exp env [opts=()]
1094 Evaluate or compile the expression @var{exp} in the lexical environment
1098 Here is a simple example, illustrating that it is the variable
1099 that gets captured, not just its value at one point in time.
1102 (define e (let ((x 100)) (the-environment)))
1103 (define fetch-x (local-eval '(lambda () x) e))
1106 (local-eval '(set! x 42) e)
1111 While @var{exp} is evaluated within the lexical environment of
1112 @code{(the-environment)}, it has the dynamic environment of the call to
1115 @code{local-eval} and @code{local-compile} can only evaluate
1116 expressions, not definitions.
1119 (local-eval '(define foo 42)
1120 (let ((x 100)) (the-environment)))
1121 @result{} syntax error: definition in expression context
1124 Note that the current implementation of @code{(the-environment)} only
1125 captures ``normal'' lexical bindings, and pattern variables bound by
1126 @code{syntax-case}. It does not currently capture local syntax
1127 transformers bound by @code{let-syntax}, @code{letrec-syntax} or
1128 non-top-level @code{define-syntax} forms. Any attempt to reference such
1129 captured syntactic keywords via @code{local-eval} or
1130 @code{local-compile} produces an error.
1133 @node Local Inclusion
1134 @subsection Local Inclusion
1136 This section has discussed various means of linking Scheme code
1137 together: fundamentally, loading up files at run-time using @code{load}
1138 and @code{load-compiled}. Guile provides another option to compose
1139 parts of programs together at expansion-time instead of at run-time.
1141 @deffn {Scheme Syntax} include file-name
1142 Open @var{file-name}, at expansion-time, and read the Scheme forms that
1143 it contains, splicing them into the location of the @code{include},
1144 within a @code{begin}.
1147 If you are a C programmer, if @code{load} in Scheme is like
1148 @code{dlopen} in C, consider @code{include} to be like the C
1149 preprocessor's @code{#include}. When you use @code{include}, it is as
1150 if the contents of the included file were typed in instead of the
1151 @code{include} form.
1153 Because the code is included at compile-time, it is available to the
1154 macroexpander. Syntax definitions in the included file are available to
1155 later code in the form in which the @code{include} appears, without the
1156 need for @code{eval-when}. (@xref{Eval When}.)
1158 For the same reason, compiling a form that uses @code{include} results
1159 in one compilation unit, composed of multiple files. Loading the
1160 compiled file is one @code{stat} operation for the compilation unit,
1161 instead of @code{2*@var{n}} in the case of @code{load} (once for each
1162 loaded source file, and once each corresponding compiled file, in the
1165 Unlike @code{load}, @code{include} also works within nested lexical
1166 contexts. It so happens that the optimizer works best within a lexical
1167 context, because all of the uses of bindings in a lexical context are
1168 visible, so composing files by including them within a @code{(let ()
1169 ...)} can sometimes lead to important speed improvements.
1171 On the other hand, @code{include} does have all the disadvantages of
1172 early binding: once the code with the @code{include} is compiled, no
1173 change to the included file is reflected in the future behavior of the
1176 Also, the particular form of @code{include}, which requires an absolute
1177 path, or a path relative to the current directory at compile-time, is
1178 not very amenable to compiling the source in one place, but then
1179 installing the source to another place. For this reason, Guile provides
1180 another form, @code{include-from-path}, which looks for the source file
1181 to include within a load path.
1183 @deffn {Scheme Syntax} include-from-path file-name
1184 Like @code{include}, but instead of expecting @code{file-name} to be an
1185 absolute file name, it is expected to be a relative path to search in
1186 the @code{%load-path}.
1189 @code{include-from-path} is more useful when you want to install all of
1190 the source files for a package (as you should!). It makes it possible
1191 to evaluate an installed file from source, instead of relying on the
1192 @code{.go} file being up to date.
1195 @c TeX-master: "guile.texi"