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,
4 @c 2010, 2011, 2012, 2013, 2014 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.
25 * REPL Servers:: Serving a REPL over a socket.
30 @subsection Scheme Syntax: Standard and Guile Extensions
42 @node Expression Syntax
43 @subsubsection Expression Syntax
45 An expression to be evaluated takes one of the following forms.
50 A symbol is evaluated by dereferencing. A binding of that symbol is
51 sought and the value there used. For example,
58 @item (@var{proc} @var{args}@dots{})
59 A parenthesised expression is a function call. @var{proc} and each
60 argument are evaluated, then the function (which @var{proc} evaluated
61 to) is called with those arguments.
63 The order in which @var{proc} and the arguments are evaluated is
64 unspecified, so be careful when using expressions with side effects.
67 (max 1 2 3) @result{} 3
69 (define (get-some-proc) min)
70 ((get-some-proc) 1 2 3) @result{} 1
73 The same sort of parenthesised form is used for a macro invocation,
74 but in that case the arguments are not evaluated. See the
75 descriptions of macros for more on this (@pxref{Macros}, and
76 @pxref{Syntax Rules}).
79 Number, string, character and boolean constants evaluate ``to
80 themselves'', so can appear as literals.
85 "hello" @result{} "hello"
90 Note that an application must not attempt to modify literal strings,
91 since they may be in read-only memory.
93 @item (quote @var{data})
97 Quoting is used to obtain a literal symbol (instead of a variable
98 reference), a literal list (instead of a function call), or a literal
99 vector. @nicode{'} is simply a shorthand for a @code{quote} form.
104 '(1 2 3) @result{} (1 2 3)
105 '#(1 (2 3) 4) @result{} #(1 (2 3) 4)
106 (quote x) @result{} x
107 (quote (1 2 3)) @result{} (1 2 3)
108 (quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4)
111 Note that an application must not attempt to modify literal lists or
112 vectors obtained from a @code{quote} form, since they may be in
115 @item (quasiquote @var{data})
119 Backquote quasi-quotation is like @code{quote}, but selected
120 sub-expressions are evaluated. This is a convenient way to construct
121 a list or vector structure most of which is constant, but at certain
122 points should have expressions substituted.
124 The same effect can always be had with suitable @code{list},
125 @code{cons} or @code{vector} calls, but quasi-quoting is often easier.
129 @item (unquote @var{expr})
133 Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates
134 an expression to be evaluated and inserted. The comma syntax @code{,}
135 is simply a shorthand for an @code{unquote} form. For example,
138 `(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4)
139 `(1 (unquote (+ 1 1)) 3) @result{} (1 2 3)
140 `#(1 ,(/ 12 2)) @result{} #(1 6)
143 @item (unquote-splicing @var{expr})
145 @findex unquote-splicing
147 Within the quasiquote @var{data}, @code{unquote-splicing} or
148 @code{,@@} indicates an expression to be evaluated and the elements of
149 the returned list inserted. @var{expr} must evaluate to a list. The
150 ``comma-at'' syntax @code{,@@} is simply a shorthand for an
151 @code{unquote-splicing} form.
155 `(1 ,@@x 4) @result{} (1 2 3 4)
156 `(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4)
157 `#(9 ,@@x 9) @result{} #(9 2 3 9)
160 Notice @code{,@@} differs from plain @code{,} in the way one level of
161 nesting is stripped. For @code{,@@} the elements of a returned list
162 are inserted, whereas with @code{,} it would be the list itself
167 @c FIXME: What can we say about the mutability of a quasiquote
168 @c result? R5RS doesn't seem to specify anything, though where it
169 @c says backquote without commas is the same as plain quote then
170 @c presumably the "fixed" portions of a quasiquote expression must be
171 @c treated as immutable.
178 @subsubsection Comments
180 @c FIXME::martin: Review me!
182 Comments in Scheme source files are written by starting them with a
183 semicolon character (@code{;}). The comment then reaches up to the end
184 of the line. Comments can begin at any column, and the may be inserted
185 on the same line as Scheme code.
190 (define x 1) ; Comment after expression
192 ;; Display something.
194 ;;; Comment at left margin.
198 It is common to use a single semicolon for comments following
199 expressions on a line, to use two semicolons for comments which are
200 indented like code, and three semicolons for comments which start at
201 column 0, even if they are inside an indented code block. This
202 convention is used when indenting code in Emacs' Scheme mode.
206 @subsubsection Block Comments
207 @cindex multiline comments
208 @cindex block comments
212 @c FIXME::martin: Review me!
214 In addition to the standard line comments defined by R5RS, Guile has
215 another comment type for multiline comments, called @dfn{block
216 comments}. This type of comment begins with the character sequence
217 @code{#!} and ends with the characters @code{!#}, which must appear on a
218 line of their own. These comments are compatible with the block
219 comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
220 (scsh)}). The characters @code{#!} were chosen because they are the
221 magic characters used in shell scripts for indicating that the name of
222 the program for executing the script follows on the same line.
224 Thus a Guile script often starts like this.
227 #! /usr/local/bin/guile -s
231 More details on Guile scripting can be found in the scripting section
232 (@pxref{Guile Scripting}).
234 @cindex R6RS block comments
235 @cindex SRFI-30 block comments
236 Similarly, Guile (starting from version 2.0) supports nested block
237 comments as specified by R6RS and
238 @url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}:
241 (+ 1 #| this is a #| nested |# block comment |# 2)
245 For backward compatibility, this syntax can be overridden with
246 @code{read-hash-extend} (@pxref{Reader Extensions,
247 @code{read-hash-extend}}).
249 There is one special case where the contents of a comment can actually
250 affect the interpretation of code. When a character encoding
251 declaration, such as @code{coding: utf-8} appears in one of the first
252 few lines of a source file, it indicates to Guile's default reader
253 that this source code file is not ASCII. For details see @ref{Character
254 Encoding of Source Files}.
256 @node Case Sensitivity
257 @subsubsection Case Sensitivity
261 @c FIXME::martin: Review me!
263 Scheme as defined in R5RS is not case sensitive when reading symbols.
264 Guile, on the contrary is case sensitive by default, so the identifiers
271 are the same in R5RS Scheme, but are different in Guile.
273 It is possible to turn off case sensitivity in Guile by setting the
274 reader option @code{case-insensitive}. For more information on reader
275 options, @xref{Scheme Read}.
278 (read-enable 'case-insensitive)
281 It is also possible to disable (or enable) case sensitivity within a
282 single file by placing the reader directives @code{#!fold-case} (or
283 @code{#!no-fold-case}) within the file itself.
286 @subsubsection Keyword Syntax
289 @node Reader Extensions
290 @subsubsection Reader Extensions
292 @deffn {Scheme Procedure} read-hash-extend chr proc
293 @deffnx {C Function} scm_read_hash_extend (chr, proc)
294 Install the procedure @var{proc} for reading expressions
295 starting with the character sequence @code{#} and @var{chr}.
296 @var{proc} will be called with two arguments: the character
297 @var{chr} and the port to read further data from. The object
298 returned will be the return value of @code{read}.
299 Passing @code{#f} for @var{proc} will remove a previous setting.
305 @subsection Reading Scheme Code
308 @deffn {Scheme Procedure} read [port]
309 @deffnx {C Function} scm_read (port)
310 Read an s-expression from the input port @var{port}, or from
311 the current input port if @var{port} is not specified.
312 Any whitespace before the next token is discarded.
315 The behaviour of Guile's Scheme reader can be modified by manipulating
318 @cindex options - read
320 @deffn {Scheme Procedure} read-options [setting]
321 Display the current settings of the global read options. If
322 @var{setting} is omitted, only a short form of the current read options
323 is printed. Otherwise if @var{setting} is the symbol @code{help}, a
324 complete options description is displayed.
327 The set of available options, and their default values, may be had by
328 invoking @code{read-options} at the prompt.
331 scheme@@(guile-user)> (read-options)
332 (square-brackets keywords #f positions)
333 scheme@@(guile-user)> (read-options 'help)
334 copy no Copy source code expressions.
335 positions yes Record positions of source code expressions.
336 case-insensitive no Convert symbols to lower case.
337 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
338 r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
339 square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
340 hungry-eol-escapes no In strings, consume leading whitespace after an
342 curly-infix no Support SRFI-105 curly infix expressions.
343 r7rs-symbols no Support R7RS |...| symbol notation.
346 Note that Guile also includes a preliminary mechanism for setting read
347 options on a per-port basis. For instance, the @code{case-insensitive}
348 read option is set (or unset) on the port when the reader encounters the
349 @code{#!fold-case} or @code{#!no-fold-case} reader directives.
350 Similarly, the @code{#!curly-infix} reader directive sets the
351 @code{curly-infix} read option on the port, and
352 @code{#!curly-infix-and-bracket-lists} sets @code{curly-infix} and
353 unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is
354 currently no other way to access or set the per-port read options.
356 The boolean options may be toggled with @code{read-enable} and
357 @code{read-disable}. The non-boolean @code{keywords} option must be set
358 using @code{read-set!}.
360 @deffn {Scheme Procedure} read-enable option-name
361 @deffnx {Scheme Procedure} read-disable option-name
362 @deffnx {Scheme Syntax} read-set! option-name value
363 Modify the read options. @code{read-enable} should be used with boolean
364 options and switches them on, @code{read-disable} switches them off.
366 @code{read-set!} can be used to set an option to a specific value. Due
367 to historical oddities, it is a macro that expects an unquoted option
371 For example, to make @code{read} fold all symbols to their lower case
372 (perhaps for compatibility with older Scheme code), you can enter:
375 (read-enable 'case-insensitive)
378 For more information on the effect of the @code{r6rs-hex-escapes} and
379 @code{hungry-eol-escapes} options, see (@pxref{String Syntax}).
381 For more information on the @code{r7rs-symbols} option, see
382 (@pxref{Symbol Read Syntax}).
386 @subsection Writing Scheme Values
388 Any scheme value may be written to a port. Not all values may be read
389 back in (@pxref{Scheme Read}), however.
393 @deffn {Scheme Procedure} write obj [port]
394 Send a representation of @var{obj} to @var{port} or to the current
395 output port if not given.
397 The output is designed to be machine readable, and can be read back
398 with @code{read} (@pxref{Scheme Read}). Strings are printed in
399 double quotes, with escapes if necessary, and characters are printed in
404 @deffn {Scheme Procedure} display obj [port]
405 Send a representation of @var{obj} to @var{port} or to the current
406 output port if not given.
408 The output is designed for human readability, it differs from
409 @code{write} in that strings are printed without double quotes and
410 escapes, and characters are printed as per @code{write-char}, not in
414 As was the case with the Scheme reader, there are a few options that
415 affect the behavior of the Scheme printer.
417 @cindex options - print
418 @cindex print options
419 @deffn {Scheme Procedure} print-options [setting]
420 Display the current settings of the read options. If @var{setting} is
421 omitted, only a short form of the current read options is
422 printed. Otherwise if @var{setting} is the symbol @code{help}, a
423 complete options description is displayed.
426 The set of available options, and their default values, may be had by
427 invoking @code{print-options} at the prompt.
430 scheme@@(guile-user)> (print-options)
431 (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{")
432 scheme@@(guile-user)> (print-options 'help)
433 highlight-prefix @{ The string to print before highlighted values.
434 highlight-suffix @} The string to print after highlighted values.
435 quote-keywordish-symbols reader How to print symbols that have a colon
436 as their first or last character. The
437 value '#f' does not quote the colons;
438 '#t' quotes them; 'reader' quotes them
439 when the reader option 'keywords' is
441 escape-newlines yes Render newlines as \n when printing
443 r7rs-symbols no Escape symbols using R7RS |...| symbol
447 These options may be modified with the print-set! syntax.
449 @deffn {Scheme Syntax} print-set! option-name value
450 Modify the print options. Due to historical oddities, @code{print-set!}
451 is a macro that expects an unquoted option name.
456 @subsection Procedures for On the Fly Evaluation
458 Scheme has the lovely property that its expressions may be represented
459 as data. The @code{eval} procedure takes a Scheme datum and evaluates
463 @c ARGFIXME environment/environment specifier
464 @deffn {Scheme Procedure} eval exp module_or_state
465 @deffnx {C Function} scm_eval (exp, module_or_state)
466 Evaluate @var{exp}, a list representing a Scheme expression,
467 in the top-level environment specified by @var{module_or_state}.
468 While @var{exp} is evaluated (using @code{primitive-eval}),
469 @var{module_or_state} is made the current module. The current module
470 is reset to its previous value when @code{eval} returns.
471 XXX - dynamic states.
472 Example: (eval '(+ 1 2) (interaction-environment))
475 @rnindex interaction-environment
476 @deffn {Scheme Procedure} interaction-environment
477 @deffnx {C Function} scm_interaction_environment ()
478 Return a specifier for the environment that contains
479 implementation--defined bindings, typically a superset of those
480 listed in the report. The intent is that this procedure will
481 return the environment in which the implementation would
482 evaluate expressions dynamically typed by the user.
485 @xref{Environments}, for other environments.
487 One does not always receive code as Scheme data, of course, and this is
488 especially the case for Guile's other language implementations
489 (@pxref{Other Languages}). For the case in which all you have is a
490 string, we have @code{eval-string}. There is a legacy version of this
491 procedure in the default environment, but you really want the one from
492 @code{(ice-9 eval-string)}, so load it up:
495 (use-modules (ice-9 eval-string))
498 @deffn {Scheme Procedure} eval-string string [#:module=#f] [#:file=#f] @
499 [#:line=#f] [#:column=#f] @
500 [#:lang=(current-language)] @
502 Parse @var{string} according to the current language, normally Scheme.
503 Evaluate or compile the expressions it contains, in order, returning the
506 If the @var{module} keyword argument is set, save a module excursion
507 (@pxref{Module System Reflection}) and set the current module to
508 @var{module} before evaluation.
510 The @var{file}, @var{line}, and @var{column} keyword arguments can be
511 used to indicate that the source string begins at a particular source
514 Finally, @var{lang} is a language, defaulting to the current language,
515 and the expression is compiled if @var{compile?} is true or there is no
516 evaluator for the given language.
519 @deffn {C Function} scm_eval_string (string)
520 @deffnx {C Function} scm_eval_string_in_module (string, module)
521 These C bindings call @code{eval-string} from @code{(ice-9
522 eval-string)}, evaluating within @var{module} or the current module.
525 @deftypefn {C Function} SCM scm_c_eval_string (const char *string)
526 @code{scm_eval_string}, but taking a C string in locale encoding instead
530 @deffn {Scheme Procedure} apply proc arg @dots{} arglst
531 @deffnx {C Function} scm_apply_0 (proc, arglst)
532 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
533 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
534 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
535 @deffnx {C Function} scm_apply (proc, arg, rest)
537 Call @var{proc} with arguments @var{arg} @dots{} and the
538 elements of the @var{arglst} list.
540 @code{scm_apply} takes parameters corresponding to a Scheme level
541 @code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the
542 last element of the @var{rest} list make up @var{arg} @dots{}, and the
543 last element of @var{rest} is the @var{arglst} list. Or if @var{rest}
544 is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and
545 (@var{arg1}) is the @var{arglst}.
547 @var{arglst} is not modified, but the @var{rest} list passed to
548 @code{scm_apply} is modified.
551 @deffn {C Function} scm_call_0 (proc)
552 @deffnx {C Function} scm_call_1 (proc, arg1)
553 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
554 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
555 @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
556 @deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
557 @deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
558 @deffnx {C Function} scm_call_7 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
559 @deffnx {C Function} scm_call_8 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
560 @deffnx {C Function} scm_call_9 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
561 Call @var{proc} with the given arguments.
564 @deffn {C Function} scm_call (proc, ...)
565 Call @var{proc} with any number of arguments. The argument list must be
566 terminated by @code{SCM_UNDEFINED}. For example:
569 scm_call (scm_c_public_ref ("guile", "+"),
576 @deffn {C Function} scm_call_n (proc, argv, nargs)
577 Call @var{proc} with the array of arguments @var{argv}, as a
578 @code{SCM*}. The length of the arguments should be passed in
579 @var{nargs}, as a @code{size_t}.
582 @deffn {Scheme Procedure} apply:nconc2last lst
583 @deffnx {C Function} scm_nconc2last (lst)
584 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
585 @var{arglst}), with @var{arglst} being a list. This function returns
586 a list comprising @var{arg1} to @var{argN} plus the elements of
587 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
588 is not modified, though the return does share structure with it.
590 This operation collects up the arguments from a list which is
591 @code{apply} style parameters.
594 @deffn {Scheme Procedure} primitive-eval exp
595 @deffnx {C Function} scm_primitive_eval (exp)
596 Evaluate @var{exp} in the top-level environment specified by
602 @subsection Compiling Scheme Code
604 The @code{eval} procedure directly interprets the S-expression
605 representation of Scheme. An alternate strategy for evaluation is to
606 determine ahead of time what computations will be necessary to
607 evaluate the expression, and then use that recipe to produce the
608 desired results. This is known as @dfn{compilation}.
610 While it is possible to compile simple Scheme expressions such as
611 @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
612 interesting in the context of procedures. Compiling a lambda expression
613 produces a compiled procedure, which is just like a normal procedure
614 except typically much faster, because it can bypass the generic
617 Functions from system modules in a Guile installation are normally
618 compiled already, so they load and run quickly.
620 @cindex automatic compilation
621 Note that well-written Scheme programs will not typically call the
622 procedures in this section, for the same reason that it is often bad
623 taste to use @code{eval}. By default, Guile automatically compiles any
624 files it encounters that have not been compiled yet (@pxref{Invoking
625 Guile, @code{--auto-compile}}). The compiler can also be invoked
626 explicitly from the shell as @code{guild compile foo.scm}.
628 (Why are calls to @code{eval} and @code{compile} usually in bad taste?
629 Because they are limited, in that they can only really make sense for
630 top-level expressions. Also, most needs for ``compile-time''
631 computation are fulfilled by macros and closures. Of course one good
632 counterexample is the REPL itself, or any code that reads expressions
635 Automatic compilation generally works transparently, without any need
636 for user intervention. However Guile does not yet do proper dependency
637 tracking, so that if file @file{@var{a}.scm} uses macros from
638 @file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm}
639 would not be automatically recompiled. To forcibly invalidate the
640 auto-compilation cache, pass the @code{--fresh-auto-compile} option to
641 Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to
642 @code{fresh} (instead of to @code{0} or @code{1}).
644 For more information on the compiler itself, see @ref{Compiling to the
645 Virtual Machine}. For information on the virtual machine, see @ref{A
646 Virtual Machine for Guile}.
648 The command-line interface to Guile's compiler is the @command{guild
651 @deffn {Command} {guild compile} [@option{option}...] @var{file}...
652 Compile @var{file}, a source file, and store bytecode in the compilation cache
653 or in the file specified by the @option{-o} option. The following options are
659 @itemx --load-path=@var{dir}
660 Add @var{dir} to the front of the module load path.
663 @itemx --output=@var{ofile}
664 Write output bytecode to @var{ofile}. By convention, bytecode file
665 names end in @code{.go}. When @option{-o} is omitted, the output file
666 name is as for @code{compile-file} (see below).
668 @item -W @var{warning}
669 @itemx --warn=@var{warning}
670 @cindex warnings, compiler
671 Emit warnings of type @var{warning}; use @code{--warn=help} for a list
672 of available warnings and their description. Currently recognized
673 warnings include @code{unused-variable}, @code{unused-toplevel},
674 @code{unbound-variable}, @code{arity-mismatch}, @code{format},
675 @code{duplicate-case-datum}, and @code{bad-case-datum}.
678 @itemx --from=@var{lang}
679 Use @var{lang} as the source language of @var{file}. If this option is omitted,
680 @code{scheme} is assumed.
683 @itemx --to=@var{lang}
684 Use @var{lang} as the target language of @var{file}. If this option is omitted,
685 @code{objcode} is assumed.
687 @item -T @var{target}
688 @itemx --target=@var{target}
689 Produce bytecode for @var{target} instead of @var{%host-type}
690 (@pxref{Build Config, %host-type}). Target must be a valid GNU triplet,
691 such as @code{armv5tel-unknown-linux-gnueabi} (@pxref{Specifying Target
692 Triplets,,, autoconf, GNU Autoconf Manual}).
696 Each @var{file} is assumed to be UTF-8-encoded, unless it contains a
697 coding declaration as recognized by @code{file-encoding}
698 (@pxref{Character Encoding of Source Files}).
701 The compiler can also be invoked directly by Scheme code using the procedures
704 @deffn {Scheme Procedure} compile exp [#:env=#f] @
705 [#:from=(current-language)] @
706 [#:to=value] [#:opts=()]
707 Compile the expression @var{exp} in the environment @var{env}. If
708 @var{exp} is a procedure, the result will be a compiled procedure;
709 otherwise @code{compile} is mostly equivalent to @code{eval}.
711 For a discussion of languages and compiler options, @xref{Compiling to
712 the Virtual Machine}.
715 @deffn {Scheme Procedure} compile-file file [#:output-file=#f] @
716 [#:from=(current-language)] [#:to='objcode] @
717 [#:env=(default-environment from)] @
719 [#:canonicalization='relative]
720 Compile the file named @var{file}.
722 Output will be written to a @var{output-file}. If you do not supply an
723 output file name, output is written to a file in the cache directory, as
724 computed by @code{(compiled-file-name @var{file})}.
726 @var{from} and @var{to} specify the source and target languages.
727 @xref{Compiling to the Virtual Machine}, for more information on these
728 options, and on @var{env} and @var{opts}.
730 As with @command{guild compile}, @var{file} is assumed to be
731 UTF-8-encoded unless it contains a coding declaration.
734 @deffn {Scheme Procedure} compiled-file-name file
735 Compute a cached location for a compiled version of a Scheme file named
738 This file will usually be below the @file{$HOME/.cache/guile/ccache}
739 directory, depending on the value of the @env{XDG_CACHE_HOME}
740 environment variable. The intention is that @code{compiled-file-name}
741 provides a fallback location for caching auto-compiled files. If you
742 want to place a compile file in the @code{%load-compiled-path}, you
743 should pass the @var{output-file} option to @code{compile-file},
747 @defvr {Scheme Variable} %auto-compilation-options
748 This variable contains the options passed to the @code{compile-file}
749 procedure when auto-compiling source files. By default, it enables
750 useful compilation warnings. It can be customized from @file{~/.guile}.
754 @subsection Loading Scheme Code from File
757 @deffn {Scheme Procedure} load filename [reader]
758 Load @var{filename} and evaluate its contents in the top-level
761 @var{reader} if provided should be either @code{#f}, or a procedure with
762 the signature @code{(lambda (port) @dots{})} which reads the next
763 expression from @var{port}. If @var{reader} is @code{#f} or absent,
764 Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
766 The @var{reader} argument takes effect by setting the value of the
767 @code{current-reader} fluid (see below) before loading the file, and
768 restoring its previous value when loading is complete. The Scheme code
769 inside @var{filename} can itself change the current reader procedure on
770 the fly by setting @code{current-reader} fluid.
772 If the variable @code{%load-hook} is defined, it should be bound to a
773 procedure that will be called before any code is loaded. See
774 documentation for @code{%load-hook} later in this section.
777 @deffn {Scheme Procedure} load-compiled filename
778 Load the compiled file named @var{filename}.
780 Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
781 calling @code{load-compiled} on the resulting file is equivalent to
782 calling @code{load} on the source file.
785 @deffn {Scheme Procedure} primitive-load filename
786 @deffnx {C Function} scm_primitive_load (filename)
787 Load the file named @var{filename} and evaluate its contents in the
788 top-level environment. @var{filename} must either be a full pathname or
789 be a pathname relative to the current directory. If the variable
790 @code{%load-hook} is defined, it should be bound to a procedure that
791 will be called before any code is loaded. See the documentation for
792 @code{%load-hook} later in this section.
795 @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
796 @code{scm_primitive_load}, but taking a C string instead of an
800 @defvar current-reader
801 @code{current-reader} holds the read procedure that is currently being
802 used by the above loading procedures to read expressions (from the file
803 that they are loading). @code{current-reader} is a fluid, so it has an
804 independent value in each dynamic root and should be read and set using
805 @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
808 Changing @code{current-reader} is typically useful to introduce local
809 syntactic changes, such that code following the @code{fluid-set!} call
810 is read using the newly installed reader. The @code{current-reader}
811 change should take place at evaluation time when the code is evaluated,
812 or at compilation time when the code is compiled:
816 (eval-when (compile eval)
817 (fluid-set! current-reader my-own-reader))
820 The @code{eval-when} form above ensures that the @code{current-reader}
821 change occurs at the right time.
825 A procedure to be called @code{(%load-hook @var{filename})} whenever a
826 file is loaded, or @code{#f} for no such call. @code{%load-hook} is
827 used by all of the loading functions (@code{load} and
828 @code{primitive-load}, and @code{load-from-path} and
829 @code{primitive-load-path} documented in the next section).
831 For example an application can set this to show what's loaded,
834 (set! %load-hook (lambda (filename)
835 (format #t "Loading ~a ...\n" filename)))
836 (load-from-path "foo.scm")
837 @print{} Loading /usr/local/share/guile/site/foo.scm ...
841 @deffn {Scheme Procedure} current-load-port
842 @deffnx {C Function} scm_current_load_port ()
843 Return the current-load-port.
844 The load port is used internally by @code{primitive-load}.
848 @subsection Load Paths
850 The procedure in the previous section look for Scheme code in the file
851 system at specific location. Guile also has some procedures to search
852 the load path for code.
855 List of directories which should be searched for Scheme modules and
856 libraries. When Guile starts up, @code{%load-path} is initialized to
857 the default load path @code{(list (%library-dir) (%site-dir)
858 (%global-site-dir) (%package-data-dir))}. The @env{GUILE_LOAD_PATH}
859 environment variable can be used to prepend or append additional
860 directories (@pxref{Environment Variables}).
862 @xref{Build Config}, for more on @code{%site-dir} and related
866 @deffn {Scheme Procedure} load-from-path filename
867 Similar to @code{load}, but searches for @var{filename} in the load
868 paths. Preferentially loads a compiled version of the file, if it is
869 available and up-to-date.
872 A user can extend the load path by calling @code{add-to-load-path}.
874 @deffn {Scheme Syntax} add-to-load-path dir
875 Add @var{dir} to the load path.
878 For example, a script might include this form to add the directory that
879 it is in to the load path:
882 (add-to-load-path (dirname (current-filename)))
885 It's better to use @code{add-to-load-path} than to modify
886 @code{%load-path} directly, because @code{add-to-load-path} takes care
887 of modifying the path both at compile-time and at run-time.
889 @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
890 @deffnx {C Function} scm_primitive_load_path (filename)
891 Search @code{%load-path} for the file named @var{filename} and
892 load it into the top-level environment. If @var{filename} is a
893 relative pathname and is not found in the list of search paths,
894 an error is signalled. Preferentially loads a compiled version of the
895 file, if it is available and up-to-date.
897 If @var{filename} is a relative pathname and is not found in the list of
898 search paths, one of three things may happen, depending on the optional
899 second argument, @var{exception-on-not-found}. If it is @code{#f},
900 @code{#f} will be returned. If it is a procedure, it will be called
901 with no arguments. (This allows a distinction to be made between
902 exceptions raised by loading a file, and exceptions related to the
903 loader itself.) Otherwise an error is signalled.
905 For compatibility with Guile 1.8 and earlier, the C function takes only
906 one argument, which can be either a string (the file name) or an
910 @deffn {Scheme Procedure} %search-load-path filename
911 @deffnx {C Function} scm_sys_search_load_path (filename)
912 Search @code{%load-path} for the file named @var{filename}, which must
913 be readable by the current user. If @var{filename} is found in the list
914 of paths to search or is an absolute pathname, return its full pathname.
915 Otherwise, return @code{#f}. Filenames may have any of the optional
916 extensions in the @code{%load-extensions} list; @code{%search-load-path}
917 will try each extension automatically.
920 @defvar %load-extensions
921 A list of default file extensions for files containing Scheme code.
922 @code{%search-load-path} tries each of these extensions when looking for
923 a file to load. By default, @code{%load-extensions} is bound to the
924 list @code{("" ".scm")}.
927 As mentioned above, when Guile searches the @code{%load-path} for a
928 source file, it will also search the @code{%load-compiled-path} for a
929 corresponding compiled file. If the compiled file is as new or newer
930 than the source file, it will be loaded instead of the source file,
931 using @code{load-compiled}.
933 @defvar %load-compiled-path
934 Like @code{%load-path}, but for compiled files. By default, this path
935 has two entries: one for compiled files from Guile itself, and one for
936 site packages. The @env{GUILE_LOAD_COMPILED_PATH} environment variable
937 can be used to prepend or append additional directories
938 (@pxref{Environment Variables}).
941 When @code{primitive-load-path} searches the @code{%load-compiled-path}
942 for a corresponding compiled file for a relative path it does so by
943 appending @code{.go} to the relative path. For example, searching for
944 @code{ice-9/popen} could find
945 @code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
946 @code{/usr/share/guile/2.0/ice-9/popen.scm}.
948 If @code{primitive-load-path} does not find a corresponding @code{.go}
949 file in the @code{%load-compiled-path}, or the @code{.go} file is out of
950 date, it will search for a corresponding auto-compiled file in the
951 fallback path, possibly creating one if one does not exist.
953 @xref{Installing Site Packages}, for more on how to correctly install
954 site packages. @xref{Modules and the File System}, for more on the
955 relationship between load paths and modules. @xref{Compilation}, for
956 more on the fallback path and auto-compilation.
958 Finally, there are a couple of helper procedures for general path
961 @deffn {Scheme Procedure} parse-path path [tail]
962 @deffnx {C Function} scm_parse_path (path, tail)
963 Parse @var{path}, which is expected to be a colon-separated string, into
964 a list and return the resulting list with @var{tail} appended. If
965 @var{path} is @code{#f}, @var{tail} is returned.
968 @deffn {Scheme Procedure} parse-path-with-ellipsis path base
969 @deffnx {C Function} scm_parse_path_with_ellipsis (path, base)
970 Parse @var{path}, which is expected to be a colon-separated string, into
971 a list and return the resulting list with @var{base} (a list) spliced in
972 place of the @code{...} path component, if present, or else @var{base}
973 is added to the end. If @var{path} is @code{#f}, @var{base} is
977 @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
978 @deffnx {C Function} scm_search_path (path, filename, rest)
979 Search @var{path} for a directory containing a file named
980 @var{filename}. The file must be readable, and not a directory. If we
981 find one, return its full filename; otherwise, return @code{#f}. If
982 @var{filename} is absolute, return it unchanged. If given,
983 @var{extensions} is a list of strings; for each directory in @var{path},
984 we search for @var{filename} concatenated with each @var{extension}. If
985 @var{require-exts?} is true, require that the returned file name have
986 one of the given extensions; if @var{require-exts?} is not given, it
987 defaults to @code{#f}.
989 For compatibility with Guile 1.8 and earlier, the C function takes only
994 @node Character Encoding of Source Files
995 @subsection Character Encoding of Source Files
997 @cindex source file encoding
998 @cindex primitive-load
1000 Scheme source code files are usually encoded in ASCII or UTF-8, but the
1001 built-in reader can interpret other character encodings as well. When
1002 Guile loads Scheme source code, it uses the @code{file-encoding}
1003 procedure (described below) to try to guess the encoding of the file.
1004 In the absence of any hints, UTF-8 is assumed. One way to provide a
1005 hint about the encoding of a source file is to place a coding
1006 declaration in the top 500 characters of the file.
1008 A coding declaration has the form @code{coding: XXXXXX}, where
1009 @code{XXXXXX} is the name of a character encoding in which the source
1010 code file has been encoded. The coding declaration must appear in a
1011 scheme comment. It can either be a semicolon-initiated comment, or the
1012 first block @code{#!} comment in the file.
1014 The name of the character encoding in the coding declaration is
1015 typically lower case and containing only letters, numbers, and hyphens,
1016 as recognized by @code{set-port-encoding!} (@pxref{Ports,
1017 @code{set-port-encoding!}}). Common examples of character encoding
1018 names are @code{utf-8} and @code{iso-8859-1},
1019 @url{http://www.iana.org/assignments/character-sets, as defined by
1020 IANA}. Thus, the coding declaration is mostly compatible with Emacs.
1022 However, there are some differences in encoding names recognized by
1023 Emacs and encoding names defined by IANA, the latter being essentially a
1024 subset of the former. For instance, @code{latin-1} is a valid encoding
1025 name for Emacs, but it's not according to the IANA standard, which Guile
1026 follows; instead, you should use @code{iso-8859-1}, which is both
1027 understood by Emacs and dubbed by IANA (IANA writes it uppercase but
1028 Emacs wants it lowercase and Guile is case insensitive.)
1030 For source code, only a subset of all possible character encodings can
1031 be interpreted by the built-in source code reader. Only those
1032 character encodings in which ASCII text appears unmodified can be
1033 used. This includes @code{UTF-8} and @code{ISO-8859-1} through
1034 @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
1035 and @code{UTF-32} may not be used because they are not compatible with
1040 @cindex port encoding
1041 @findex set-port-encoding!
1042 There might be a scenario in which one would want to read non-ASCII
1043 code from a port, such as with the function @code{read}, instead of
1044 with @code{load}. If the port's character encoding is the same as the
1045 encoding of the code to be read by the port, not other special
1046 handling is necessary. The port will automatically do the character
1047 encoding conversion. The functions @code{setlocale} or by
1048 @code{set-port-encoding!} are used to set port encodings
1051 If a port is used to read code of unknown character encoding, it can
1052 accomplish this in three steps. First, the character encoding of the
1053 port should be set to ISO-8859-1 using @code{set-port-encoding!}.
1054 Then, the procedure @code{file-encoding}, described below, is used to
1055 scan for a coding declaration when reading from the port. As a side
1056 effect, it rewinds the port after its scan is complete. After that,
1057 the port's character encoding should be set to the encoding returned
1058 by @code{file-encoding}, if any, again by using
1059 @code{set-port-encoding!}. Then the code can be read as normal.
1061 Alternatively, one can use the @code{#:guess-encoding} keyword argument
1062 of @code{open-file} and related procedures. @xref{File Ports}.
1064 @deffn {Scheme Procedure} file-encoding port
1065 @deffnx {C Function} scm_file_encoding (port)
1066 Attempt to scan the first few hundred bytes from the @var{port} for
1067 hints about its character encoding. Return a string containing the
1068 encoding name or @code{#f} if the encoding cannot be determined. The
1071 Currently, the only supported method is to look for an Emacs-like
1072 character coding declaration (@pxref{Recognize Coding, how Emacs
1073 recognizes file encoding,, emacs, The GNU Emacs Reference Manual}). The
1074 coding declaration is of the form @code{coding: XXXXX} and must appear
1075 in a Scheme comment. Additional heuristics may be added in the future.
1079 @node Delayed Evaluation
1080 @subsection Delayed Evaluation
1081 @cindex delayed evaluation
1084 Promises are a convenient way to defer a calculation until its result
1085 is actually needed, and to run such a calculation only once. Also
1088 @deffn syntax delay expr
1090 Return a promise object which holds the given @var{expr} expression,
1091 ready to be evaluated by a later @code{force}.
1094 @deffn {Scheme Procedure} promise? obj
1095 @deffnx {C Function} scm_promise_p (obj)
1096 Return true if @var{obj} is a promise.
1100 @deffn {Scheme Procedure} force p
1101 @deffnx {C Function} scm_force (p)
1102 Return the value obtained from evaluating the @var{expr} in the given
1103 promise @var{p}. If @var{p} has previously been forced then its
1104 @var{expr} is not evaluated again, instead the value obtained at that
1105 time is simply returned.
1107 During a @code{force}, an @var{expr} can call @code{force} again on
1108 its own promise, resulting in a recursive evaluation of that
1109 @var{expr}. The first evaluation to return gives the value for the
1110 promise. Higher evaluations run to completion in the normal way, but
1111 their results are ignored, @code{force} always returns the first
1116 @node Local Evaluation
1117 @subsection Local Evaluation
1119 Guile includes a facility to capture a lexical environment, and later
1120 evaluate a new expression within that environment. This code is
1121 implemented in a module.
1124 (use-modules (ice-9 local-eval))
1127 @deffn syntax the-environment
1128 Captures and returns a lexical environment for use with
1129 @code{local-eval} or @code{local-compile}.
1132 @deffn {Scheme Procedure} local-eval exp env
1133 @deffnx {C Function} scm_local_eval (exp, env)
1134 @deffnx {Scheme Procedure} local-compile exp env [opts=()]
1135 Evaluate or compile the expression @var{exp} in the lexical environment
1139 Here is a simple example, illustrating that it is the variable
1140 that gets captured, not just its value at one point in time.
1143 (define e (let ((x 100)) (the-environment)))
1144 (define fetch-x (local-eval '(lambda () x) e))
1147 (local-eval '(set! x 42) e)
1152 While @var{exp} is evaluated within the lexical environment of
1153 @code{(the-environment)}, it has the dynamic environment of the call to
1156 @code{local-eval} and @code{local-compile} can only evaluate
1157 expressions, not definitions.
1160 (local-eval '(define foo 42)
1161 (let ((x 100)) (the-environment)))
1162 @result{} syntax error: definition in expression context
1165 Note that the current implementation of @code{(the-environment)} only
1166 captures ``normal'' lexical bindings, and pattern variables bound by
1167 @code{syntax-case}. It does not currently capture local syntax
1168 transformers bound by @code{let-syntax}, @code{letrec-syntax} or
1169 non-top-level @code{define-syntax} forms. Any attempt to reference such
1170 captured syntactic keywords via @code{local-eval} or
1171 @code{local-compile} produces an error.
1174 @node Local Inclusion
1175 @subsection Local Inclusion
1177 This section has discussed various means of linking Scheme code
1178 together: fundamentally, loading up files at run-time using @code{load}
1179 and @code{load-compiled}. Guile provides another option to compose
1180 parts of programs together at expansion-time instead of at run-time.
1182 @deffn {Scheme Syntax} include file-name
1183 Open @var{file-name}, at expansion-time, and read the Scheme forms that
1184 it contains, splicing them into the location of the @code{include},
1185 within a @code{begin}.
1187 If @var{file-name} is a relative path, it is searched for relative to
1188 the path that contains the file that the @code{include} for appears in.
1191 If you are a C programmer, if @code{load} in Scheme is like
1192 @code{dlopen} in C, consider @code{include} to be like the C
1193 preprocessor's @code{#include}. When you use @code{include}, it is as
1194 if the contents of the included file were typed in instead of the
1195 @code{include} form.
1197 Because the code is included at compile-time, it is available to the
1198 macroexpander. Syntax definitions in the included file are available to
1199 later code in the form in which the @code{include} appears, without the
1200 need for @code{eval-when}. (@xref{Eval When}.)
1202 For the same reason, compiling a form that uses @code{include} results
1203 in one compilation unit, composed of multiple files. Loading the
1204 compiled file is one @code{stat} operation for the compilation unit,
1205 instead of @code{2*@var{n}} in the case of @code{load} (once for each
1206 loaded source file, and once each corresponding compiled file, in the
1209 Unlike @code{load}, @code{include} also works within nested lexical
1210 contexts. It so happens that the optimizer works best within a lexical
1211 context, because all of the uses of bindings in a lexical context are
1212 visible, so composing files by including them within a @code{(let ()
1213 ...)} can sometimes lead to important speed improvements.
1215 On the other hand, @code{include} does have all the disadvantages of
1216 early binding: once the code with the @code{include} is compiled, no
1217 change to the included file is reflected in the future behavior of the
1220 Also, the particular form of @code{include}, which requires an absolute
1221 path, or a path relative to the current directory at compile-time, is
1222 not very amenable to compiling the source in one place, but then
1223 installing the source to another place. For this reason, Guile provides
1224 another form, @code{include-from-path}, which looks for the source file
1225 to include within a load path.
1227 @deffn {Scheme Syntax} include-from-path file-name
1228 Like @code{include}, but instead of expecting @code{file-name} to be an
1229 absolute file name, it is expected to be a relative path to search in
1230 the @code{%load-path}.
1233 @code{include-from-path} is more useful when you want to install all of
1234 the source files for a package (as you should!). It makes it possible
1235 to evaluate an installed file from source, instead of relying on the
1236 @code{.go} file being up to date.
1239 @subsection REPL Servers
1243 The procedures in this section are provided by
1245 (use-modules (system repl server))
1248 When an application is written in Guile, it is often convenient to
1249 allow the user to be able to interact with it by evaluating Scheme
1250 expressions in a REPL.
1252 The procedures of this module allow you to spawn a @dfn{REPL server},
1253 which permits interaction over a local or TCP connection. Guile itself
1254 uses them internally to implement the @option{--listen} switch,
1255 @ref{Command-line Options}.
1257 @deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
1258 [#:addr] [#:port=37146]
1259 Return a stream socket bound to a given address @var{addr} and port
1260 number @var{port}. If the @var{host} is given, and @var{addr} is not,
1261 then the @var{host} string is converted to an address. If neither is
1262 given, we use the loopback address.
1265 @deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
1266 Return a UNIX domain socket, bound to a given @var{path}.
1269 @deffn {Scheme Procedure} run-server [server-socket]
1270 @deffnx {Scheme Procedure} spawn-server [server-socket]
1271 Create and run a REPL, making it available over the given
1272 @var{server-socket}. If @var{server-socket} is not provided, it
1273 defaults to the socket created by calling @code{make-tcp-server-socket}
1276 @code{run-server} runs the server in the current thread, whereas
1277 @code{spawn-server} runs the server in a new thread.
1280 @deffn {Scheme Procedure} stop-server-and-clients!
1281 Closes the connection on all running server sockets.
1285 @c TeX-master: "guile.texi"