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, 2013
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.
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 (+ #| 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.
345 Note that Guile also includes a preliminary mechanism for setting read
346 options on a per-port basis. For instance, the @code{case-insensitive}
347 read option is set (or unset) on the port when the reader encounters the
348 @code{#!fold-case} or @code{#!no-fold-case} reader directives.
349 Similarly, the @code{#!curly-infix} reader directive sets the
350 @code{curly-infix} read option on the port, and
351 @code{#!curly-infix-and-bracket-lists} sets @code{curly-infix} and
352 unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is
353 currently no other way to access or set the per-port read options.
355 The boolean options may be toggled with @code{read-enable} and
356 @code{read-disable}. The non-boolean @code{keywords} option must be set
357 using @code{read-set!}.
359 @deffn {Scheme Procedure} read-enable option-name
360 @deffnx {Scheme Procedure} read-disable option-name
361 @deffnx {Scheme Syntax} read-set! option-name value
362 Modify the read options. @code{read-enable} should be used with boolean
363 options and switches them on, @code{read-disable} switches them off.
365 @code{read-set!} can be used to set an option to a specific value. Due
366 to historical oddities, it is a macro that expects an unquoted option
370 For example, to make @code{read} fold all symbols to their lower case
371 (perhaps for compatibility with older Scheme code), you can enter:
374 (read-enable 'case-insensitive)
377 For more information on the effect of the @code{r6rs-hex-escapes} and
378 @code{hungry-eol-escapes} options, see (@pxref{String Syntax}).
382 @subsection Writing Scheme Values
384 Any scheme value may be written to a port. Not all values may be read
385 back in (@pxref{Scheme Read}), however.
389 @deffn {Scheme Procedure} write obj [port]
390 Send a representation of @var{obj} to @var{port} or to the current
391 output port if not given.
393 The output is designed to be machine readable, and can be read back
394 with @code{read} (@pxref{Scheme Read}). Strings are printed in
395 double quotes, with escapes if necessary, and characters are printed in
400 @deffn {Scheme Procedure} display obj [port]
401 Send a representation of @var{obj} to @var{port} or to the current
402 output port if not given.
404 The output is designed for human readability, it differs from
405 @code{write} in that strings are printed without double quotes and
406 escapes, and characters are printed as per @code{write-char}, not in
410 As was the case with the Scheme reader, there are a few options that
411 affect the behavior of the Scheme printer.
413 @cindex options - print
414 @cindex print options
415 @deffn {Scheme Procedure} print-options [setting]
416 Display the current settings of the read options. If @var{setting} is
417 omitted, only a short form of the current read options is
418 printed. Otherwise if @var{setting} is the symbol @code{help}, a
419 complete options description is displayed.
422 The set of available options, and their default values, may be had by
423 invoking @code{print-options} at the prompt.
426 scheme@@(guile-user)> (print-options)
427 (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{")
428 scheme@@(guile-user)> (print-options 'help)
429 highlight-prefix @{ The string to print before highlighted values.
430 highlight-suffix @} The string to print after highlighted values.
431 quote-keywordish-symbols reader How to print symbols that have a colon
432 as their first or last character. The
433 value '#f' does not quote the colons;
434 '#t' quotes them; 'reader' quotes them
435 when the reader option 'keywords' is
437 escape-newlines yes Render newlines as \n when printing
441 These options may be modified with the print-set! syntax.
443 @deffn {Scheme Syntax} print-set! option-name value
444 Modify the print options. Due to historical oddities, @code{print-set!}
445 is a macro that expects an unquoted option name.
450 @subsection Procedures for On the Fly Evaluation
452 Scheme has the lovely property that its expressions may be represented
453 as data. The @code{eval} procedure takes a Scheme datum and evaluates
457 @c ARGFIXME environment/environment specifier
458 @deffn {Scheme Procedure} eval exp module_or_state
459 @deffnx {C Function} scm_eval (exp, module_or_state)
460 Evaluate @var{exp}, a list representing a Scheme expression,
461 in the top-level environment specified by @var{module_or_state}.
462 While @var{exp} is evaluated (using @code{primitive-eval}),
463 @var{module_or_state} is made the current module. The current module
464 is reset to its previous value when @code{eval} returns.
465 XXX - dynamic states.
466 Example: (eval '(+ 1 2) (interaction-environment))
469 @rnindex interaction-environment
470 @deffn {Scheme Procedure} interaction-environment
471 @deffnx {C Function} scm_interaction_environment ()
472 Return a specifier for the environment that contains
473 implementation--defined bindings, typically a superset of those
474 listed in the report. The intent is that this procedure will
475 return the environment in which the implementation would
476 evaluate expressions dynamically typed by the user.
479 @xref{Environments}, for other environments.
481 One does not always receive code as Scheme data, of course, and this is
482 especially the case for Guile's other language implementations
483 (@pxref{Other Languages}). For the case in which all you have is a
484 string, we have @code{eval-string}. There is a legacy version of this
485 procedure in the default environment, but you really want the one from
486 @code{(ice-9 eval-string)}, so load it up:
489 (use-modules (ice-9 eval-string))
492 @deffn {Scheme Procedure} eval-string string [#:module=#f] [#:file=#f] @
493 [#:line=#f] [#:column=#f] @
494 [#:lang=(current-language)] @
496 Parse @var{string} according to the current language, normally Scheme.
497 Evaluate or compile the expressions it contains, in order, returning the
500 If the @var{module} keyword argument is set, save a module excursion
501 (@pxref{Module System Reflection}) and set the current module to
502 @var{module} before evaluation.
504 The @var{file}, @var{line}, and @var{column} keyword arguments can be
505 used to indicate that the source string begins at a particular source
508 Finally, @var{lang} is a language, defaulting to the current language,
509 and the expression is compiled if @var{compile?} is true or there is no
510 evaluator for the given language.
513 @deffn {C Function} scm_eval_string (string)
514 @deffnx {C Function} scm_eval_string_in_module (string, module)
515 These C bindings call @code{eval-string} from @code{(ice-9
516 eval-string)}, evaluating within @var{module} or the current module.
519 @deftypefn {C Function} SCM scm_c_eval_string (const char *string)
520 @code{scm_eval_string}, but taking a C string in locale encoding instead
524 @deffn {Scheme Procedure} apply proc arg @dots{} arglst
525 @deffnx {C Function} scm_apply_0 (proc, arglst)
526 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
527 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
528 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
529 @deffnx {C Function} scm_apply (proc, arg, rest)
531 Call @var{proc} with arguments @var{arg} @dots{} and the
532 elements of the @var{arglst} list.
534 @code{scm_apply} takes parameters corresponding to a Scheme level
535 @code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the
536 last element of the @var{rest} list make up @var{arg} @dots{}, and the
537 last element of @var{rest} is the @var{arglst} list. Or if @var{rest}
538 is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and
539 (@var{arg1}) is the @var{arglst}.
541 @var{arglst} is not modified, but the @var{rest} list passed to
542 @code{scm_apply} is modified.
545 @deffn {C Function} scm_call_0 (proc)
546 @deffnx {C Function} scm_call_1 (proc, arg1)
547 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
548 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
549 @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
550 @deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
551 @deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
552 @deffnx {C Function} scm_call_7 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
553 @deffnx {C Function} scm_call_8 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
554 @deffnx {C Function} scm_call_9 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
555 Call @var{proc} with the given arguments.
558 @deffn {C Function} scm_call (proc, ...)
559 Call @var{proc} with any number of arguments. The argument list must be
560 terminated by @code{SCM_UNDEFINED}. For example:
563 scm_call (scm_c_public_ref ("guile", "+"),
570 @deffn {C Function} scm_call_n (proc, argv, nargs)
571 Call @var{proc} with the array of arguments @var{argv}, as a
572 @code{SCM*}. The length of the arguments should be passed in
573 @var{nargs}, as a @code{size_t}.
576 @deffn {Scheme Procedure} apply:nconc2last lst
577 @deffnx {C Function} scm_nconc2last (lst)
578 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
579 @var{arglst}), with @var{arglst} being a list. This function returns
580 a list comprising @var{arg1} to @var{argN} plus the elements of
581 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
582 is not modified, though the return does share structure with it.
584 This operation collects up the arguments from a list which is
585 @code{apply} style parameters.
588 @deffn {Scheme Procedure} primitive-eval exp
589 @deffnx {C Function} scm_primitive_eval (exp)
590 Evaluate @var{exp} in the top-level environment specified by
596 @subsection Compiling Scheme Code
598 The @code{eval} procedure directly interprets the S-expression
599 representation of Scheme. An alternate strategy for evaluation is to
600 determine ahead of time what computations will be necessary to
601 evaluate the expression, and then use that recipe to produce the
602 desired results. This is known as @dfn{compilation}.
604 While it is possible to compile simple Scheme expressions such as
605 @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
606 interesting in the context of procedures. Compiling a lambda expression
607 produces a compiled procedure, which is just like a normal procedure
608 except typically much faster, because it can bypass the generic
611 Functions from system modules in a Guile installation are normally
612 compiled already, so they load and run quickly.
614 @cindex automatic compilation
615 Note that well-written Scheme programs will not typically call the
616 procedures in this section, for the same reason that it is often bad
617 taste to use @code{eval}. By default, Guile automatically compiles any
618 files it encounters that have not been compiled yet (@pxref{Invoking
619 Guile, @code{--auto-compile}}). The compiler can also be invoked
620 explicitly from the shell as @code{guild compile foo.scm}.
622 (Why are calls to @code{eval} and @code{compile} usually in bad taste?
623 Because they are limited, in that they can only really make sense for
624 top-level expressions. Also, most needs for ``compile-time''
625 computation are fulfilled by macros and closures. Of course one good
626 counterexample is the REPL itself, or any code that reads expressions
629 Automatic compilation generally works transparently, without any need
630 for user intervention. However Guile does not yet do proper dependency
631 tracking, so that if file @file{@var{a}.scm} uses macros from
632 @file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm}
633 would not be automatically recompiled. To forcibly invalidate the
634 auto-compilation cache, pass the @code{--fresh-auto-compile} option to
635 Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to
636 @code{fresh} (instead of to @code{0} or @code{1}).
638 For more information on the compiler itself, see @ref{Compiling to the
639 Virtual Machine}. For information on the virtual machine, see @ref{A
640 Virtual Machine for Guile}.
642 The command-line interface to Guile's compiler is the @command{guild
645 @deffn {Command} {guild compile} [@option{option}...] @var{file}...
646 Compile @var{file}, a source file, and store bytecode in the compilation cache
647 or in the file specified by the @option{-o} option. The following options are
653 @itemx --load-path=@var{dir}
654 Add @var{dir} to the front of the module load path.
657 @itemx --output=@var{ofile}
658 Write output bytecode to @var{ofile}. By convention, bytecode file
659 names end in @code{.go}. When @option{-o} is omitted, the output file
660 name is as for @code{compile-file} (see below).
662 @item -W @var{warning}
663 @itemx --warn=@var{warning}
664 @cindex warnings, compiler
665 Emit warnings of type @var{warning}; use @code{--warn=help} for a list
666 of available warnings and their description. Currently recognized
667 warnings include @code{unused-variable}, @code{unused-toplevel},
668 @code{unbound-variable}, @code{arity-mismatch}, @code{format},
669 @code{duplicate-case-datum}, and @code{bad-case-datum}.
672 @itemx --from=@var{lang}
673 Use @var{lang} as the source language of @var{file}. If this option is omitted,
674 @code{scheme} is assumed.
677 @itemx --to=@var{lang}
678 Use @var{lang} as the target language of @var{file}. If this option is omitted,
679 @code{objcode} is assumed.
681 @item -T @var{target}
682 @itemx --target=@var{target}
683 Produce bytecode for @var{target} instead of @var{%host-type}
684 (@pxref{Build Config, %host-type}). Target must be a valid GNU triplet,
685 such as @code{armv5tel-unknown-linux-gnueabi} (@pxref{Specifying Target
686 Triplets,,, autoconf, GNU Autoconf Manual}).
690 Each @var{file} is assumed to be UTF-8-encoded, unless it contains a
691 coding declaration as recognized by @code{file-encoding}
692 (@pxref{Character Encoding of Source Files}).
695 The compiler can also be invoked directly by Scheme code using the procedures
698 @deffn {Scheme Procedure} compile exp [#:env=#f] @
699 [#:from=(current-language)] @
700 [#:to=value] [#:opts=()]
701 Compile the expression @var{exp} in the environment @var{env}. If
702 @var{exp} is a procedure, the result will be a compiled procedure;
703 otherwise @code{compile} is mostly equivalent to @code{eval}.
705 For a discussion of languages and compiler options, @xref{Compiling to
706 the Virtual Machine}.
709 @deffn {Scheme Procedure} compile-file file [#:output-file=#f] @
710 [#:from=(current-language)] [#:to='objcode] @
711 [#:env=(default-environment from)] @
713 [#:canonicalization='relative]
714 Compile the file named @var{file}.
716 Output will be written to a @var{output-file}. If you do not supply an
717 output file name, output is written to a file in the cache directory, as
718 computed by @code{(compiled-file-name @var{file})}.
720 @var{from} and @var{to} specify the source and target languages.
721 @xref{Compiling to the Virtual Machine}, for more information on these
722 options, and on @var{env} and @var{opts}.
724 As with @command{guild compile}, @var{file} is assumed to be
725 UTF-8-encoded unless it contains a coding declaration.
728 @deffn {Scheme Procedure} compiled-file-name file
729 Compute a cached location for a compiled version of a Scheme file named
732 This file will usually be below the @file{$HOME/.cache/guile/ccache}
733 directory, depending on the value of the @env{XDG_CACHE_HOME}
734 environment variable. The intention is that @code{compiled-file-name}
735 provides a fallback location for caching auto-compiled files. If you
736 want to place a compile file in the @code{%load-compiled-path}, you
737 should pass the @var{output-file} option to @code{compile-file},
741 @defvr {Scheme Variable} %auto-compilation-options
742 This variable contains the options passed to the @code{compile-file}
743 procedure when auto-compiling source files. By default, it enables
744 useful compilation warnings. It can be customized from @file{~/.guile}.
748 @subsection Loading Scheme Code from File
751 @deffn {Scheme Procedure} load filename [reader]
752 Load @var{filename} and evaluate its contents in the top-level
755 @var{reader} if provided should be either @code{#f}, or a procedure with
756 the signature @code{(lambda (port) @dots{})} which reads the next
757 expression from @var{port}. If @var{reader} is @code{#f} or absent,
758 Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
760 The @var{reader} argument takes effect by setting the value of the
761 @code{current-reader} fluid (see below) before loading the file, and
762 restoring its previous value when loading is complete. The Scheme code
763 inside @var{filename} can itself change the current reader procedure on
764 the fly by setting @code{current-reader} fluid.
766 If the variable @code{%load-hook} is defined, it should be bound to a
767 procedure that will be called before any code is loaded. See
768 documentation for @code{%load-hook} later in this section.
771 @deffn {Scheme Procedure} load-compiled filename
772 Load the compiled file named @var{filename}.
774 Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
775 calling @code{load-compiled} on the resulting file is equivalent to
776 calling @code{load} on the source file.
779 @deffn {Scheme Procedure} primitive-load filename
780 @deffnx {C Function} scm_primitive_load (filename)
781 Load the file named @var{filename} and evaluate its contents in the
782 top-level environment. @var{filename} must either be a full pathname or
783 be a pathname relative to the current directory. If the variable
784 @code{%load-hook} is defined, it should be bound to a procedure that
785 will be called before any code is loaded. See the documentation for
786 @code{%load-hook} later in this section.
789 @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
790 @code{scm_primitive_load}, but taking a C string instead of an
794 @defvar current-reader
795 @code{current-reader} holds the read procedure that is currently being
796 used by the above loading procedures to read expressions (from the file
797 that they are loading). @code{current-reader} is a fluid, so it has an
798 independent value in each dynamic root and should be read and set using
799 @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
802 Changing @code{current-reader} is typically useful to introduce local
803 syntactic changes, such that code following the @code{fluid-set!} call
804 is read using the newly installed reader. The @code{current-reader}
805 change should take place at evaluation time when the code is evaluated,
806 or at compilation time when the code is compiled:
810 (eval-when (compile eval)
811 (fluid-set! current-reader my-own-reader))
814 The @code{eval-when} form above ensures that the @code{current-reader}
815 change occurs at the right time.
819 A procedure to be called @code{(%load-hook @var{filename})} whenever a
820 file is loaded, or @code{#f} for no such call. @code{%load-hook} is
821 used by all of the loading functions (@code{load} and
822 @code{primitive-load}, and @code{load-from-path} and
823 @code{primitive-load-path} documented in the next section).
825 For example an application can set this to show what's loaded,
828 (set! %load-hook (lambda (filename)
829 (format #t "Loading ~a ...\n" filename)))
830 (load-from-path "foo.scm")
831 @print{} Loading /usr/local/share/guile/site/foo.scm ...
835 @deffn {Scheme Procedure} current-load-port
836 @deffnx {C Function} scm_current_load_port ()
837 Return the current-load-port.
838 The load port is used internally by @code{primitive-load}.
842 @subsection Load Paths
844 The procedure in the previous section look for Scheme code in the file
845 system at specific location. Guile also has some procedures to search
846 the load path for code.
849 List of directories which should be searched for Scheme modules and
850 libraries. When Guile starts up, @code{%load-path} is initialized to
851 the default load path @code{(list (%library-dir) (%site-dir)
852 (%global-site-dir) (%package-data-dir))}. The @env{GUILE_LOAD_PATH}
853 environment variable can be used to prepend or append additional
854 directories (@pxref{Environment Variables}).
856 @xref{Build Config}, for more on @code{%site-dir} and related
860 @deffn {Scheme Procedure} load-from-path filename
861 Similar to @code{load}, but searches for @var{filename} in the load
862 paths. Preferentially loads a compiled version of the file, if it is
863 available and up-to-date.
866 A user can extend the load path by calling @code{add-to-load-path}.
868 @deffn {Scheme Syntax} add-to-load-path dir
869 Add @var{dir} to the load path.
872 For example, a script might include this form to add the directory that
873 it is in to the load path:
876 (add-to-load-path (dirname (current-filename)))
879 It's better to use @code{add-to-load-path} than to modify
880 @code{%load-path} directly, because @code{add-to-load-path} takes care
881 of modifying the path both at compile-time and at run-time.
883 @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
884 @deffnx {C Function} scm_primitive_load_path (filename)
885 Search @code{%load-path} for the file named @var{filename} and
886 load it into the top-level environment. If @var{filename} is a
887 relative pathname and is not found in the list of search paths,
888 an error is signalled. Preferentially loads a compiled version of the
889 file, if it is available and up-to-date.
891 If @var{filename} is a relative pathname and is not found in the list of
892 search paths, one of three things may happen, depending on the optional
893 second argument, @var{exception-on-not-found}. If it is @code{#f},
894 @code{#f} will be returned. If it is a procedure, it will be called
895 with no arguments. (This allows a distinction to be made between
896 exceptions raised by loading a file, and exceptions related to the
897 loader itself.) Otherwise an error is signalled.
899 For compatibility with Guile 1.8 and earlier, the C function takes only
900 one argument, which can be either a string (the file name) or an
904 @deffn {Scheme Procedure} %search-load-path filename
905 @deffnx {C Function} scm_sys_search_load_path (filename)
906 Search @code{%load-path} for the file named @var{filename}, which must
907 be readable by the current user. If @var{filename} is found in the list
908 of paths to search or is an absolute pathname, return its full pathname.
909 Otherwise, return @code{#f}. Filenames may have any of the optional
910 extensions in the @code{%load-extensions} list; @code{%search-load-path}
911 will try each extension automatically.
914 @defvar %load-extensions
915 A list of default file extensions for files containing Scheme code.
916 @code{%search-load-path} tries each of these extensions when looking for
917 a file to load. By default, @code{%load-extensions} is bound to the
918 list @code{("" ".scm")}.
921 As mentioned above, when Guile searches the @code{%load-path} for a
922 source file, it will also search the @code{%load-compiled-path} for a
923 corresponding compiled file. If the compiled file is as new or newer
924 than the source file, it will be loaded instead of the source file,
925 using @code{load-compiled}.
927 @defvar %load-compiled-path
928 Like @code{%load-path}, but for compiled files. By default, this path
929 has two entries: one for compiled files from Guile itself, and one for
930 site packages. The @env{GUILE_LOAD_COMPILED_PATH} environment variable
931 can be used to prepend or append additional directories
932 (@pxref{Environment Variables}).
935 When @code{primitive-load-path} searches the @code{%load-compiled-path}
936 for a corresponding compiled file for a relative path it does so by
937 appending @code{.go} to the relative path. For example, searching for
938 @code{ice-9/popen} could find
939 @code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
940 @code{/usr/share/guile/2.0/ice-9/popen.scm}.
942 If @code{primitive-load-path} does not find a corresponding @code{.go}
943 file in the @code{%load-compiled-path}, or the @code{.go} file is out of
944 date, it will search for a corresponding auto-compiled file in the
945 fallback path, possibly creating one if one does not exist.
947 @xref{Installing Site Packages}, for more on how to correctly install
948 site packages. @xref{Modules and the File System}, for more on the
949 relationship between load paths and modules. @xref{Compilation}, for
950 more on the fallback path and auto-compilation.
952 Finally, there are a couple of helper procedures for general path
955 @deffn {Scheme Procedure} parse-path path [tail]
956 @deffnx {C Function} scm_parse_path (path, tail)
957 Parse @var{path}, which is expected to be a colon-separated string, into
958 a list and return the resulting list with @var{tail} appended. If
959 @var{path} is @code{#f}, @var{tail} is returned.
962 @deffn {Scheme Procedure} parse-path-with-ellipsis path base
963 @deffnx {C Function} scm_parse_path_with_ellipsis (path, base)
964 Parse @var{path}, which is expected to be a colon-separated string, into
965 a list and return the resulting list with @var{base} (a list) spliced in
966 place of the @code{...} path component, if present, or else @var{base}
967 is added to the end. If @var{path} is @code{#f}, @var{base} is
971 @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
972 @deffnx {C Function} scm_search_path (path, filename, rest)
973 Search @var{path} for a directory containing a file named
974 @var{filename}. The file must be readable, and not a directory. If we
975 find one, return its full filename; otherwise, return @code{#f}. If
976 @var{filename} is absolute, return it unchanged. If given,
977 @var{extensions} is a list of strings; for each directory in @var{path},
978 we search for @var{filename} concatenated with each @var{extension}. If
979 @var{require-exts?} is true, require that the returned file name have
980 one of the given extensions; if @var{require-exts?} is not given, it
981 defaults to @code{#f}.
983 For compatibility with Guile 1.8 and earlier, the C function takes only
988 @node Character Encoding of Source Files
989 @subsection Character Encoding of Source Files
991 @cindex source file encoding
992 @cindex primitive-load
994 Scheme source code files are usually encoded in ASCII or UTF-8, but the
995 built-in reader can interpret other character encodings as well. When
996 Guile loads Scheme source code, it uses the @code{file-encoding}
997 procedure (described below) to try to guess the encoding of the file.
998 In the absence of any hints, UTF-8 is assumed. One way to provide a
999 hint about the encoding of a source file is to place a coding
1000 declaration in the top 500 characters of the file.
1002 A coding declaration has the form @code{coding: XXXXXX}, where
1003 @code{XXXXXX} is the name of a character encoding in which the source
1004 code file has been encoded. The coding declaration must appear in a
1005 scheme comment. It can either be a semicolon-initiated comment, or the
1006 first block @code{#!} comment in the file.
1008 The name of the character encoding in the coding declaration is
1009 typically lower case and containing only letters, numbers, and hyphens,
1010 as recognized by @code{set-port-encoding!} (@pxref{Ports,
1011 @code{set-port-encoding!}}). Common examples of character encoding
1012 names are @code{utf-8} and @code{iso-8859-1},
1013 @url{http://www.iana.org/assignments/character-sets, as defined by
1014 IANA}. Thus, the coding declaration is mostly compatible with Emacs.
1016 However, there are some differences in encoding names recognized by
1017 Emacs and encoding names defined by IANA, the latter being essentially a
1018 subset of the former. For instance, @code{latin-1} is a valid encoding
1019 name for Emacs, but it's not according to the IANA standard, which Guile
1020 follows; instead, you should use @code{iso-8859-1}, which is both
1021 understood by Emacs and dubbed by IANA (IANA writes it uppercase but
1022 Emacs wants it lowercase and Guile is case insensitive.)
1024 For source code, only a subset of all possible character encodings can
1025 be interpreted by the built-in source code reader. Only those
1026 character encodings in which ASCII text appears unmodified can be
1027 used. This includes @code{UTF-8} and @code{ISO-8859-1} through
1028 @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
1029 and @code{UTF-32} may not be used because they are not compatible with
1034 @cindex port encoding
1035 @findex set-port-encoding!
1036 There might be a scenario in which one would want to read non-ASCII
1037 code from a port, such as with the function @code{read}, instead of
1038 with @code{load}. If the port's character encoding is the same as the
1039 encoding of the code to be read by the port, not other special
1040 handling is necessary. The port will automatically do the character
1041 encoding conversion. The functions @code{setlocale} or by
1042 @code{set-port-encoding!} are used to set port encodings
1045 If a port is used to read code of unknown character encoding, it can
1046 accomplish this in three steps. First, the character encoding of the
1047 port should be set to ISO-8859-1 using @code{set-port-encoding!}.
1048 Then, the procedure @code{file-encoding}, described below, is used to
1049 scan for a coding declaration when reading from the port. As a side
1050 effect, it rewinds the port after its scan is complete. After that,
1051 the port's character encoding should be set to the encoding returned
1052 by @code{file-encoding}, if any, again by using
1053 @code{set-port-encoding!}. Then the code can be read as normal.
1055 Alternatively, one can use the @code{#:guess-encoding} keyword argument
1056 of @code{open-file} and related procedures. @xref{File Ports}.
1058 @deffn {Scheme Procedure} file-encoding port
1059 @deffnx {C Function} scm_file_encoding (port)
1060 Attempt to scan the first few hundred bytes from the @var{port} for
1061 hints about its character encoding. Return a string containing the
1062 encoding name or @code{#f} if the encoding cannot be determined. The
1065 Currently, the only supported method is to look for an Emacs-like
1066 character coding declaration (@pxref{Recognize Coding, how Emacs
1067 recognizes file encoding,, emacs, The GNU Emacs Reference Manual}). The
1068 coding declaration is of the form @code{coding: XXXXX} and must appear
1069 in a Scheme comment. Additional heuristics may be added in the future.
1073 @node Delayed Evaluation
1074 @subsection Delayed Evaluation
1075 @cindex delayed evaluation
1078 Promises are a convenient way to defer a calculation until its result
1079 is actually needed, and to run such a calculation only once. Also
1082 @deffn syntax delay expr
1084 Return a promise object which holds the given @var{expr} expression,
1085 ready to be evaluated by a later @code{force}.
1088 @deffn {Scheme Procedure} promise? obj
1089 @deffnx {C Function} scm_promise_p (obj)
1090 Return true if @var{obj} is a promise.
1094 @deffn {Scheme Procedure} force p
1095 @deffnx {C Function} scm_force (p)
1096 Return the value obtained from evaluating the @var{expr} in the given
1097 promise @var{p}. If @var{p} has previously been forced then its
1098 @var{expr} is not evaluated again, instead the value obtained at that
1099 time is simply returned.
1101 During a @code{force}, an @var{expr} can call @code{force} again on
1102 its own promise, resulting in a recursive evaluation of that
1103 @var{expr}. The first evaluation to return gives the value for the
1104 promise. Higher evaluations run to completion in the normal way, but
1105 their results are ignored, @code{force} always returns the first
1110 @node Local Evaluation
1111 @subsection Local Evaluation
1113 Guile includes a facility to capture a lexical environment, and later
1114 evaluate a new expression within that environment. This code is
1115 implemented in a module.
1118 (use-modules (ice-9 local-eval))
1121 @deffn syntax the-environment
1122 Captures and returns a lexical environment for use with
1123 @code{local-eval} or @code{local-compile}.
1126 @deffn {Scheme Procedure} local-eval exp env
1127 @deffnx {C Function} scm_local_eval (exp, env)
1128 @deffnx {Scheme Procedure} local-compile exp env [opts=()]
1129 Evaluate or compile the expression @var{exp} in the lexical environment
1133 Here is a simple example, illustrating that it is the variable
1134 that gets captured, not just its value at one point in time.
1137 (define e (let ((x 100)) (the-environment)))
1138 (define fetch-x (local-eval '(lambda () x) e))
1141 (local-eval '(set! x 42) e)
1146 While @var{exp} is evaluated within the lexical environment of
1147 @code{(the-environment)}, it has the dynamic environment of the call to
1150 @code{local-eval} and @code{local-compile} can only evaluate
1151 expressions, not definitions.
1154 (local-eval '(define foo 42)
1155 (let ((x 100)) (the-environment)))
1156 @result{} syntax error: definition in expression context
1159 Note that the current implementation of @code{(the-environment)} only
1160 captures ``normal'' lexical bindings, and pattern variables bound by
1161 @code{syntax-case}. It does not currently capture local syntax
1162 transformers bound by @code{let-syntax}, @code{letrec-syntax} or
1163 non-top-level @code{define-syntax} forms. Any attempt to reference such
1164 captured syntactic keywords via @code{local-eval} or
1165 @code{local-compile} produces an error.
1168 @node Local Inclusion
1169 @subsection Local Inclusion
1171 This section has discussed various means of linking Scheme code
1172 together: fundamentally, loading up files at run-time using @code{load}
1173 and @code{load-compiled}. Guile provides another option to compose
1174 parts of programs together at expansion-time instead of at run-time.
1176 @deffn {Scheme Syntax} include file-name
1177 Open @var{file-name}, at expansion-time, and read the Scheme forms that
1178 it contains, splicing them into the location of the @code{include},
1179 within a @code{begin}.
1181 If @var{file-name} is a relative path, it is searched for relative to
1182 the path that contains the file that the @code{include} for appears in.
1185 If you are a C programmer, if @code{load} in Scheme is like
1186 @code{dlopen} in C, consider @code{include} to be like the C
1187 preprocessor's @code{#include}. When you use @code{include}, it is as
1188 if the contents of the included file were typed in instead of the
1189 @code{include} form.
1191 Because the code is included at compile-time, it is available to the
1192 macroexpander. Syntax definitions in the included file are available to
1193 later code in the form in which the @code{include} appears, without the
1194 need for @code{eval-when}. (@xref{Eval When}.)
1196 For the same reason, compiling a form that uses @code{include} results
1197 in one compilation unit, composed of multiple files. Loading the
1198 compiled file is one @code{stat} operation for the compilation unit,
1199 instead of @code{2*@var{n}} in the case of @code{load} (once for each
1200 loaded source file, and once each corresponding compiled file, in the
1203 Unlike @code{load}, @code{include} also works within nested lexical
1204 contexts. It so happens that the optimizer works best within a lexical
1205 context, because all of the uses of bindings in a lexical context are
1206 visible, so composing files by including them within a @code{(let ()
1207 ...)} can sometimes lead to important speed improvements.
1209 On the other hand, @code{include} does have all the disadvantages of
1210 early binding: once the code with the @code{include} is compiled, no
1211 change to the included file is reflected in the future behavior of the
1214 Also, the particular form of @code{include}, which requires an absolute
1215 path, or a path relative to the current directory at compile-time, is
1216 not very amenable to compiling the source in one place, but then
1217 installing the source to another place. For this reason, Guile provides
1218 another form, @code{include-from-path}, which looks for the source file
1219 to include within a load path.
1221 @deffn {Scheme Syntax} include-from-path file-name
1222 Like @code{include}, but instead of expecting @code{file-name} to be an
1223 absolute file name, it is expected to be a relative path to search in
1224 the @code{%load-path}.
1227 @code{include-from-path} is more useful when you want to install all of
1228 the source files for a package (as you should!). It makes it possible
1229 to evaluate an installed file from source, instead of relying on the
1230 @code{.go} file being up to date.
1233 @subsection REPL Servers
1237 The procedures in this section are provided by
1239 (use-modules (system repl server))
1242 When an application is written in Guile, it is often convenient to
1243 allow the user to be able to interact with it by evaluating Scheme
1244 expressions in a REPL.
1246 The procedures of this module allow you to spawn a @dfn{REPL server},
1247 which permits interaction over a local or TCP connection. Guile itself
1248 uses them internally to implement the @option{--listen} switch,
1249 @ref{Command-line Options}.
1251 @deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
1252 [#:addr] [#:port=37146]
1253 Return a stream socket bound to a given address @var{addr} and port
1254 number @var{port}. If the @var{host} is given, and @var{addr} is not,
1255 then the @var{host} string is converted to an address. If neither is
1256 given, we use the loopback address.
1259 @deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
1260 Return a UNIX domain socket, bound to a given @var{path}.
1263 @deffn {Scheme Procedure} run-server [server-socket]
1264 @deffnx {Scheme Procedure} spawn-server [server-socket]
1265 Create and run a REPL, making it available over the given
1266 @var{server-socket}. If @var{server-socket} is not provided, it
1267 defaults to the socket created by calling @code{make-tcp-server-socket}
1270 @code{run-server} runs the server in the current thread, whereas
1271 @code{spawn-server} runs the server in a new thread.
1274 @deffn {Scheme Procedure} stop-server-and-clients!
1275 Closes the connection on all running server sockets.
1279 @c TeX-master: "guile.texi"