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
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 * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file.
21 * Delayed Evaluation:: Postponing evaluation until it is needed.
26 @subsection Scheme Syntax: Standard and Guile Extensions
38 @node Expression Syntax
39 @subsubsection Expression Syntax
41 An expression to be evaluated takes one of the following forms.
46 A symbol is evaluated by dereferencing. A binding of that symbol is
47 sought and the value there used. For example,
54 @item (@var{proc} @var{args}@dots{})
55 A parenthesised expression is a function call. @var{proc} and each
56 argument are evaluated, then the function (which @var{proc} evaluated
57 to) is called with those arguments.
59 The order in which @var{proc} and the arguments are evaluated is
60 unspecified, so be careful when using expressions with side effects.
63 (max 1 2 3) @result{} 3
65 (define (get-some-proc) min)
66 ((get-some-proc) 1 2 3) @result{} 1
69 The same sort of parenthesised form is used for a macro invocation,
70 but in that case the arguments are not evaluated. See the
71 descriptions of macros for more on this (@pxref{Macros}, and
72 @pxref{Syntax Rules}).
75 Number, string, character and boolean constants evaluate ``to
76 themselves'', so can appear as literals.
81 "hello" @result{} "hello"
86 Note that an application must not attempt to modify literal strings,
87 since they may be in read-only memory.
89 @item (quote @var{data})
93 Quoting is used to obtain a literal symbol (instead of a variable
94 reference), a literal list (instead of a function call), or a literal
95 vector. @nicode{'} is simply a shorthand for a @code{quote} form.
100 '(1 2 3) @result{} (1 2 3)
101 '#(1 (2 3) 4) @result{} #(1 (2 3) 4)
102 (quote x) @result{} x
103 (quote (1 2 3)) @result{} (1 2 3)
104 (quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4)
107 Note that an application must not attempt to modify literal lists or
108 vectors obtained from a @code{quote} form, since they may be in
111 @item (quasiquote @var{data})
115 Backquote quasi-quotation is like @code{quote}, but selected
116 sub-expressions are evaluated. This is a convenient way to construct
117 a list or vector structure most of which is constant, but at certain
118 points should have expressions substituted.
120 The same effect can always be had with suitable @code{list},
121 @code{cons} or @code{vector} calls, but quasi-quoting is often easier.
125 @item (unquote @var{expr})
129 Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates
130 an expression to be evaluated and inserted. The comma syntax @code{,}
131 is simply a shorthand for an @code{unquote} form. For example,
134 `(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4)
135 `(1 (unquote (+ 1 1)) 3) @result{} (1 2 3)
136 `#(1 ,(/ 12 2)) @result{} #(1 6)
139 @item (unquote-splicing @var{expr})
141 @findex unquote-splicing
143 Within the quasiquote @var{data}, @code{unquote-splicing} or
144 @code{,@@} indicates an expression to be evaluated and the elements of
145 the returned list inserted. @var{expr} must evaluate to a list. The
146 ``comma-at'' syntax @code{,@@} is simply a shorthand for an
147 @code{unquote-splicing} form.
151 `(1 ,@@x 4) @result{} (1 2 3 4)
152 `(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4)
153 `#(9 ,@@x 9) @result{} #(9 2 3 9)
156 Notice @code{,@@} differs from plain @code{,} in the way one level of
157 nesting is stripped. For @code{,@@} the elements of a returned list
158 are inserted, whereas with @code{,} it would be the list itself
163 @c FIXME: What can we say about the mutability of a quasiquote
164 @c result? R5RS doesn't seem to specify anything, though where it
165 @c says backquote without commas is the same as plain quote then
166 @c presumably the "fixed" portions of a quasiquote expression must be
167 @c treated as immutable.
174 @subsubsection Comments
176 @c FIXME::martin: Review me!
178 Comments in Scheme source files are written by starting them with a
179 semicolon character (@code{;}). The comment then reaches up to the end
180 of the line. Comments can begin at any column, and the may be inserted
181 on the same line as Scheme code.
186 (define x 1) ; Comment after expression
188 ;; Display something.
190 ;;; Comment at left margin.
194 It is common to use a single semicolon for comments following
195 expressions on a line, to use two semicolons for comments which are
196 indented like code, and three semicolons for comments which start at
197 column 0, even if they are inside an indented code block. This
198 convention is used when indenting code in Emacs' Scheme mode.
202 @subsubsection Block Comments
203 @cindex multiline comments
204 @cindex block comments
208 @c FIXME::martin: Review me!
210 In addition to the standard line comments defined by R5RS, Guile has
211 another comment type for multiline comments, called @dfn{block
212 comments}. This type of comment begins with the character sequence
213 @code{#!} and ends with the characters @code{!#}, which must appear on a
214 line of their own. These comments are compatible with the block
215 comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
216 (scsh)}). The characters @code{#!} were chosen because they are the
217 magic characters used in shell scripts for indicating that the name of
218 the program for executing the script follows on the same line.
220 Thus a Guile script often starts like this.
223 #! /usr/local/bin/guile -s
227 More details on Guile scripting can be found in the scripting section
228 (@pxref{Guile Scripting}).
230 @cindex R6RS block comments
231 @cindex SRFI-30 block comments
232 Similarly, Guile (starting from version 2.0) supports nested block
233 comments as specified by R6RS and
234 @url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}:
237 (+ #| this is a #| nested |# block comment |# 2)
241 For backward compatibility, this syntax can be overridden with
242 @code{read-hash-extend} (@pxref{Reader Extensions,
243 @code{read-hash-extend}}).
245 There is one special case where the contents of a comment can actually
246 affect the interpretation of code. When a character encoding
247 declaration, such as @code{coding: utf-8} appears in one of the first
248 few lines of a source file, it indicates to Guile's default reader
249 that this source code file is not ASCII. For details see @ref{Character
250 Encoding of Source Files}.
252 @node Case Sensitivity
253 @subsubsection Case Sensitivity
255 @c FIXME::martin: Review me!
257 Scheme as defined in R5RS is not case sensitive when reading symbols.
258 Guile, on the contrary is case sensitive by default, so the identifiers
265 are the same in R5RS Scheme, but are different in Guile.
267 It is possible to turn off case sensitivity in Guile by setting the
268 reader option @code{case-insensitive}. For more information on reader
269 options, @xref{Scheme Read}.
272 (read-enable 'case-insensitive)
275 Note that this is seldom a problem, because Scheme programmers tend not
276 to use uppercase letters in their identifiers anyway.
280 @subsubsection Keyword Syntax
283 @node Reader Extensions
284 @subsubsection Reader Extensions
286 @deffn {Scheme Procedure} read-hash-extend chr proc
287 @deffnx {C Function} scm_read_hash_extend (chr, proc)
288 Install the procedure @var{proc} for reading expressions
289 starting with the character sequence @code{#} and @var{chr}.
290 @var{proc} will be called with two arguments: the character
291 @var{chr} and the port to read further data from. The object
292 returned will be the return value of @code{read}.
293 Passing @code{#f} for @var{proc} will remove a previous setting.
299 @subsection Reading Scheme Code
302 @deffn {Scheme Procedure} read [port]
303 @deffnx {C Function} scm_read (port)
304 Read an s-expression from the input port @var{port}, or from
305 the current input port if @var{port} is not specified.
306 Any whitespace before the next token is discarded.
309 The behaviour of Guile's Scheme reader can be modified by manipulating
312 @cindex options - read
314 @deffn {Scheme Procedure} read-options [setting]
315 Display the current settings of the read options. If @var{setting} is
316 omitted, only a short form of the current read options is printed.
317 Otherwise if @var{setting} is the symbol @code{help}, a complete options
318 description is displayed.
321 The set of available options, and their default values, may be had by
322 invoking @code{read-options} at the prompt.
325 scheme@@(guile-user)> (read-options)
326 (square-brackets keywords #f positions)
327 scheme@@(guile-user)> (read-options 'help)
328 copy no Copy source code expressions.
329 positions yes Record positions of source code expressions.
330 case-insensitive no Convert symbols to lower case.
331 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
332 r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
333 square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
334 hungry-eol-escapes no In strings, consume leading whitespace after an
338 The boolean options may be toggled with @code{read-enable} and
339 @code{read-disable}. The non-boolean @code{keywords} option must be set
340 using @code{read-set!}.
342 @deffn {Scheme Procedure} read-enable option-name
343 @deffnx {Scheme Procedure} read-disable option-name
344 @deffnx {Scheme Procedure} read-set! option-name value
345 Modify the read options. @code{read-enable} should be used with boolean
346 options and switches them on, @code{read-disable} switches them off.
347 @code{read-set!} can be used to set an option to a specific value.
350 For example, to make @code{read} fold all symbols to their lower case
351 (perhaps for compatibility with older Scheme code), you can enter:
354 (read-enable 'case-insensitive)
357 For more information on the effect of the @code{r6rs-hex-escapes} and
358 @code{hungry-eol-escapes} options, see (@pxref{String Syntax}).
362 @subsection Writing Scheme Values
364 Any scheme value may be written to a port. Not all values may be read
365 back in (@pxref{Scheme Read}), however.
369 @deffn {Scheme Procedure} write obj [port]
370 Send a representation of @var{obj} to @var{port} or to the current
371 output port if not given.
373 The output is designed to be machine readable, and can be read back
374 with @code{read} (@pxref{Scheme Read}). Strings are printed in
375 double quotes, with escapes if necessary, and characters are printed in
380 @deffn {Scheme Procedure} display obj [port]
381 Send a representation of @var{obj} to @var{port} or to the current
382 output port if not given.
384 The output is designed for human readability, it differs from
385 @code{write} in that strings are printed without double quotes and
386 escapes, and characters are printed as per @code{write-char}, not in
390 As was the case with the Scheme reader, there are a few options that
391 affect the behavior of the Scheme printer.
393 @cindex options - print
394 @cindex print options
395 @deffn {Scheme Procedure} print-options [setting]
396 Display the current settings of the read options. If @var{setting} is
397 omitted, only a short form of the current read options is
398 printed. Otherwise if @var{setting} is the symbol @code{help}, a
399 complete options description is displayed.
402 The set of available options, and their default values, may be had by
403 invoking @code{print-options} at the prompt.
406 scheme@@(guile-user)> (print-options)
407 (quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{")
408 scheme@@(guile-user)> (print-options 'help)
409 highlight-prefix @{ The string to print before highlighted values.
410 highlight-suffix @} The string to print after highlighted values.
411 quote-keywordish-symbols reader How to print symbols that have a colon
412 as their first or last character. The
413 value '#f' does not quote the colons;
414 '#t' quotes them; 'reader' quotes them
415 when the reader option 'keywords' is
419 These options may be modified with the print-set! procedure.
421 @deffn {Scheme Procedure} print-set! option-name value
422 Modify the print options.
427 @subsection Procedures for On the Fly Evaluation
429 Scheme has the lovely property that its expressions may be represented
430 as data. The @code{eval} procedure takes a Scheme datum and evaluates
434 @c ARGFIXME environment/environment specifier
435 @deffn {Scheme Procedure} eval exp module_or_state
436 @deffnx {C Function} scm_eval (exp, module_or_state)
437 Evaluate @var{exp}, a list representing a Scheme expression,
438 in the top-level environment specified by @var{module}.
439 While @var{exp} is evaluated (using @code{primitive-eval}),
440 @var{module} is made the current module. The current module
441 is reset to its previous value when @var{eval} returns.
442 XXX - dynamic states.
443 Example: (eval '(+ 1 2) (interaction-environment))
446 @rnindex interaction-environment
447 @deffn {Scheme Procedure} interaction-environment
448 @deffnx {C Function} scm_interaction_environment ()
449 Return a specifier for the environment that contains
450 implementation--defined bindings, typically a superset of those
451 listed in the report. The intent is that this procedure will
452 return the environment in which the implementation would
453 evaluate expressions dynamically typed by the user.
456 @xref{Environments}, for other environments.
458 One does not always receive code as Scheme data, of course, and this is
459 especially the case for Guile's other language implementations
460 (@pxref{Other Languages}). For the case in which all you have is a
461 string, we have @code{eval-string}. There is a legacy version of this
462 procedure in the default environment, but you really want the one from
463 @code{(ice-9 eval-string)}, so load it up:
466 (use-modules (ice-9 eval-string))
469 @deffn {Scheme Procedure} eval-string string [module=#f] [file=#f] [line=#f] [column=#f] [lang=(current-language)] [compile?=#f]
470 Parse @var{string} according to the current language, normally Scheme.
471 Evaluate or compile the expressions it contains, in order, returning the
474 If the @var{module} keyword argument is set, save a module excursion
475 (@pxref{Module System Reflection}) and set the current module to
476 @var{module} before evaluation.
478 The @var{file}, @var{line}, and @var{column} keyword arguments can be
479 used to indicate that the source string begins at a particular source
482 Finally, @var{lang} is a language, defaulting to the current language,
483 and the expression is compiled if @var{compile?} is true or there is no
484 evaluator for the given language.
487 @deffn {C Function} scm_eval_string (string)
488 @deffnx {C Function} scm_eval_string_in_module (string, module)
489 These C bindings call @code{eval-string} from @code{(ice-9
490 eval-string)}, evaluating within @var{module} or the current module.
493 @deftypefn {C Function} SCM scm_c_eval_string (const char *string)
494 @code{scm_eval_string}, but taking a C string in locale encoding instead
498 @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
499 @deffnx {C Function} scm_apply_0 (proc, arglst)
500 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
501 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
502 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
503 @deffnx {C Function} scm_apply (proc, arg, rest)
505 Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the
506 elements of the @var{arglst} list.
508 @code{scm_apply} takes parameters corresponding to a Scheme level
509 @code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the
510 last element of the @var{rest} list make up
511 @var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the
512 @var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL}
513 then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
516 @var{arglst} is not modified, but the @var{rest} list passed to
517 @code{scm_apply} is modified.
520 @deffn {C Function} scm_call_0 (proc)
521 @deffnx {C Function} scm_call_1 (proc, arg1)
522 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
523 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
524 @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
525 @deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
526 @deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
527 Call @var{proc} with the given arguments.
530 @deffn {C Function} scm_call_n (proc, argv, nargs)
531 Call @var{proc} with the array of arguments @var{argv}, as a
532 @code{SCM*}. The length of the arguments should be passed in
533 @var{nargs}, as a @code{size_t}.
536 @deffn {Scheme Procedure} apply:nconc2last lst
537 @deffnx {C Function} scm_nconc2last (lst)
538 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
539 @var{arglst}), with @var{arglst} being a list. This function returns
540 a list comprising @var{arg1} to @var{argN} plus the elements of
541 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
542 is not modified, though the return does share structure with it.
544 This operation collects up the arguments from a list which is
545 @code{apply} style parameters.
548 @deffn {Scheme Procedure} primitive-eval exp
549 @deffnx {C Function} scm_primitive_eval (exp)
550 Evaluate @var{exp} in the top-level environment specified by
556 @subsection Compiling Scheme Code
558 The @code{eval} procedure directly interprets the S-expression
559 representation of Scheme. An alternate strategy for evaluation is to
560 determine ahead of time what computations will be necessary to
561 evaluate the expression, and then use that recipe to produce the
562 desired results. This is known as @dfn{compilation}.
564 While it is possible to compile simple Scheme expressions such as
565 @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
566 interesting in the context of procedures. Compiling a lambda expression
567 produces a compiled procedure, which is just like a normal procedure
568 except typically much faster, because it can bypass the generic
571 Functions from system modules in a Guile installation are normally
572 compiled already, so they load and run quickly.
574 @cindex automatic compilation
575 Note that well-written Scheme programs will not typically call the
576 procedures in this section, for the same reason that it is often bad
577 taste to use @code{eval}. By default, Guile automatically compiles any
578 files it encounters that have not been compiled yet (@pxref{Invoking
579 Guile, @code{--auto-compile}}). The compiler can also be invoked
580 explicitly from the shell as @code{guile-tools compile foo.scm}.
582 (Why are calls to @code{eval} and @code{compile} usually in bad taste?
583 Because they are limited, in that they can only really make sense for
584 top-level expressions. Also, most needs for ``compile-time''
585 computation are fulfilled by macros and closures. Of course one good
586 counterexample is the REPL itself, or any code that reads expressions
589 Automatic compilation generally works transparently, without any need
590 for user intervention. However Guile does not yet do proper dependency
591 tracking, so that if file @file{@var{a}.scm} uses macros from
592 @file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm}
593 would not be automatically recompiled. To forcibly invalidate the
594 auto-compilation cache, pass the @code{--fresh-auto-compile} option to
595 Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to
596 @code{fresh} (instead of to @code{0} or @code{1}).
598 For more information on the compiler itself, see @ref{Compiling to the
599 Virtual Machine}. For information on the virtual machine, see @ref{A
600 Virtual Machine for Guile}.
602 The command-line interface to Guile's compiler is the @command{guile-tools
605 @deffn {Command} {guile-tools compile} [@option{option}...] @var{file}...
606 Compile @var{file}, a source file, and store bytecode in the compilation cache
607 or in the file specified by the @option{-o} option. The following options are
613 @itemx --load-path=@var{dir}
614 Add @var{dir} to the front of the module load path.
617 @itemx --output=@var{ofile}
618 Write output bytecode to @var{ofile}. By convention, bytecode file
619 names end in @code{.go}. When @option{-o} is omitted, the output file
620 name is as for @code{compile-file} (see below).
622 @item -W @var{warning}
623 @itemx --warn=@var{warning}
624 Emit warnings of type @var{warning}; use @code{--warn=help} for a list
625 of available warnings and their description. Currently recognized
626 warnings include @code{unused-variable}, @code{unused-toplevel},
627 @code{unbound-variable}, @code{arity-mismatch}, and @code{format}.
630 @itemx --from=@var{lang}
631 Use @var{lang} as the source language of @var{file}. If this option is omitted,
632 @code{scheme} is assumed.
635 @itemx --to=@var{lang}
636 Use @var{lang} as the target language of @var{file}. If this option is omitted,
637 @code{objcode} is assumed.
641 Each @var{file} is assumed to be UTF-8-encoded, unless it contains a
642 coding declaration as recognized by @code{file-encoding}
643 (@pxref{Character Encoding of Source Files}).
646 The compiler can also be invoked directly by Scheme code using the procedures
649 @deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()]
650 Compile the expression @var{exp} in the environment @var{env}. If
651 @var{exp} is a procedure, the result will be a compiled procedure;
652 otherwise @code{compile} is mostly equivalent to @code{eval}.
654 For a discussion of languages and compiler options, @xref{Compiling to
655 the Virtual Machine}.
658 @deffn {Scheme Procedure} compile-file file [output-file=#f] @
659 [from=(current-language)] [to='objcode] @
660 [env=(default-environment from)] [opts='()] @
661 [canonicalization 'relative]
662 Compile the file named @var{file}.
664 Output will be written to a @var{output-file}. If you do not supply an
665 output file name, output is written to a file in the cache directory, as
666 computed by @code{(compiled-file-name @var{file})}.
668 @var{from} and @var{to} specify the source and target languages.
669 @xref{Compiling to the Virtual Machine}, for more information on these
670 options, and on @var{env} and @var{opts}.
672 As with @command{guile-tools compile}, @var{file} is assumed to be
673 UTF-8-encoded unless it contains a coding declaration.
676 @deffn {Scheme Procedure} compiled-file-name file
677 Compute a cached location for a compiled version of a Scheme file named
680 This file will usually be below the @file{$HOME/.cache/guile/ccache}
681 directory, depending on the value of the @env{XDG_CACHE_HOME}
682 environment variable. The intention is that @code{compiled-file-name}
683 provides a fallback location for caching auto-compiled files. If you
684 want to place a compile file in the @code{%load-compiled-path}, you
685 should pass the @var{output-file} option to @code{compile-file},
689 @defvr {Scheme Variable} %auto-compilation-options
690 This variable contains the options passed to the @code{compile-file}
691 procedure when auto-compiling source files. By default, it enables
692 useful compilation warnings. It can be customized from @file{~/.guile}.
696 @subsection Loading Scheme Code from File
699 @deffn {Scheme Procedure} load filename [reader]
700 Load @var{filename} and evaluate its contents in the top-level
701 environment. The load paths are not searched.
703 @var{reader} if provided should be either @code{#f}, or a procedure with
704 the signature @code{(lambda (port) @dots{})} which reads the next
705 expression from @var{port}. If @var{reader} is @code{#f} or absent,
706 Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
708 The @var{reader} argument takes effect by setting the value of the
709 @code{current-reader} fluid (see below) before loading the file, and
710 restoring its previous value when loading is complete. The Scheme code
711 inside @var{filename} can itself change the current reader procedure on
712 the fly by setting @code{current-reader} fluid.
714 If the variable @code{%load-hook} is defined, it should be bound to a
715 procedure that will be called before any code is loaded. See
716 documentation for @code{%load-hook} later in this section.
719 @deffn {Scheme Procedure} load-compiled filename
720 Load the compiled file named @var{filename}. The load paths are not
723 Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
724 calling @code{load-compiled} on the resulting file is equivalent to
725 calling @code{load} on the source file.
728 @deffn {Scheme Procedure} load-from-path filename
729 Similar to @code{load}, but searches for @var{filename} in the load
730 paths. Preferentially loads a compiled version of the file, if it is
731 available and up-to-date.
734 @deffn {Scheme Procedure} primitive-load filename
735 @deffnx {C Function} scm_primitive_load (filename)
736 Load the file named @var{filename} and evaluate its contents in
737 the top-level environment. The load paths are not searched;
738 @var{filename} must either be a full pathname or be a pathname
739 relative to the current directory. If the variable
740 @code{%load-hook} is defined, it should be bound to a procedure
741 that will be called before any code is loaded. See the
742 documentation for @code{%load-hook} later in this section.
745 @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
746 @code{scm_primitive_load}, but taking a C string instead of an
750 @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
751 @deffnx {C Function} scm_primitive_load_path (filename)
752 Search @code{%load-path} for the file named @var{filename} and
753 load it into the top-level environment. If @var{filename} is a
754 relative pathname and is not found in the list of search paths,
755 an error is signalled. Preferentially loads a compiled version of the
756 file, if it is available and up-to-date.
758 By default or if @var{exception-on-not-found} is true, an exception is
759 raised if @var{filename} is not found. If @var{exception-on-not-found}
760 is @code{#f} and @var{filename} is not found, no exception is raised and
761 @code{#f} is returned. For compatibility with Guile 1.8 and earlier,
762 the C function takes only one argument, which can be either a string
763 (the file name) or an argument list.
766 @deffn {Scheme Procedure} %search-load-path filename
767 @deffnx {C Function} scm_sys_search_load_path (filename)
768 Search @code{%load-path} for the file named @var{filename},
769 which must be readable by the current user. If @var{filename}
770 is found in the list of paths to search or is an absolute
771 pathname, return its full pathname. Otherwise, return
772 @code{#f}. Filenames may have any of the optional extensions
773 in the @code{%load-extensions} list; @code{%search-load-path}
774 will try each extension automatically.
777 @defvar current-reader
778 @code{current-reader} holds the read procedure that is currently being
779 used by the above loading procedures to read expressions (from the file
780 that they are loading). @code{current-reader} is a fluid, so it has an
781 independent value in each dynamic root and should be read and set using
782 @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
785 Changing @code{current-reader} is typically useful to introduce local
786 syntactic changes, such that code following the @code{fluid-set!} call
787 is read using the newly installed reader. The @code{current-reader}
788 change should take place at evaluation time when the code is evaluated,
789 or at compilation time when the code is compiled:
793 (eval-when (compile eval)
794 (fluid-set! current-reader my-own-reader))
797 The @code{eval-when} form above ensures that the @code{current-reader}
798 change occurs at the right time.
802 A procedure to be called @code{(%load-hook @var{filename})} whenever a
803 file is loaded, or @code{#f} for no such call. @code{%load-hook} is
804 used by all of the above loading functions (@code{load},
805 @code{load-path}, @code{primitive-load} and
806 @code{primitive-load-path}).
808 For example an application can set this to show what's loaded,
811 (set! %load-hook (lambda (filename)
812 (format #t "Loading ~a ...\n" filename)))
813 (load-from-path "foo.scm")
814 @print{} Loading /usr/local/share/guile/site/foo.scm ...
818 @deffn {Scheme Procedure} current-load-port
819 @deffnx {C Function} scm_current_load_port ()
820 Return the current-load-port.
821 The load port is used internally by @code{primitive-load}.
824 @defvar %load-extensions
825 A list of default file extensions for files containing Scheme code.
826 @code{%search-load-path} tries each of these extensions when looking for
827 a file to load. By default, @code{%load-extensions} is bound to the
828 list @code{("" ".scm")}.
831 @node Character Encoding of Source Files
832 @subsection Character Encoding of Source Files
834 @cindex source file encoding
835 @cindex primitive-load
837 Scheme source code files are usually encoded in ASCII, but, the
838 built-in reader can interpret other character encodings. The
839 procedure @code{primitive-load}, and by extension the functions that
840 call it, such as @code{load}, first scan the top 500 characters of the
841 file for a coding declaration.
843 A coding declaration has the form @code{coding: XXXXXX}, where
844 @code{XXXXXX} is the name of a character encoding in which the source
845 code file has been encoded. The coding declaration must appear in a
846 scheme comment. It can either be a semicolon-initiated comment or a block
849 The name of the character encoding in the coding declaration is
850 typically lower case and containing only letters, numbers, and hyphens,
851 as recognized by @code{set-port-encoding!} (@pxref{Ports,
852 @code{set-port-encoding!}}). Common examples of character encoding
853 names are @code{utf-8} and @code{iso-8859-1},
854 @url{http://www.iana.org/assignments/character-sets, as defined by
855 IANA}. Thus, the coding declaration is mostly compatible with Emacs.
857 However, there are some differences in encoding names recognized by
858 Emacs and encoding names defined by IANA, the latter being essentially a
859 subset of the former. For instance, @code{latin-1} is a valid encoding
860 name for Emacs, but it's not according to the IANA standard, which Guile
861 follows; instead, you should use @code{iso-8859-1}, which is both
862 understood by Emacs and dubbed by IANA (IANA writes it uppercase but
863 Emacs wants it lowercase and Guile is case insensitive.)
865 For source code, only a subset of all possible character encodings can
866 be interpreted by the built-in source code reader. Only those
867 character encodings in which ASCII text appears unmodified can be
868 used. This includes @code{UTF-8} and @code{ISO-8859-1} through
869 @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
870 and @code{UTF-32} may not be used because they are not compatible with
875 @cindex port encoding
876 @findex set-port-encoding!
877 There might be a scenario in which one would want to read non-ASCII
878 code from a port, such as with the function @code{read}, instead of
879 with @code{load}. If the port's character encoding is the same as the
880 encoding of the code to be read by the port, not other special
881 handling is necessary. The port will automatically do the character
882 encoding conversion. The functions @code{setlocale} or by
883 @code{set-port-encoding!} are used to set port encodings
886 If a port is used to read code of unknown character encoding, it can
887 accomplish this in three steps. First, the character encoding of the
888 port should be set to ISO-8859-1 using @code{set-port-encoding!}.
889 Then, the procedure @code{file-encoding}, described below, is used to
890 scan for a coding declaration when reading from the port. As a side
891 effect, it rewinds the port after its scan is complete. After that,
892 the port's character encoding should be set to the encoding returned
893 by @code{file-encoding}, if any, again by using
894 @code{set-port-encoding!}. Then the code can be read as normal.
896 @deffn {Scheme Procedure} file-encoding port
897 @deffnx {C Function} scm_file_encoding port
898 Scan the port for an Emacs-like character coding declaration near the
899 top of the contents of a port with random-accessible contents
900 (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs,
901 The GNU Emacs Reference Manual}). The coding declaration is of the form
902 @code{coding: XXXXX} and must appear in a Scheme comment. Return a
903 string containing the character encoding of the file if a declaration
904 was found, or @code{#f} otherwise. The port is rewound.
908 @node Delayed Evaluation
909 @subsection Delayed Evaluation
910 @cindex delayed evaluation
913 Promises are a convenient way to defer a calculation until its result
914 is actually needed, and to run such a calculation only once.
916 @deffn syntax delay expr
918 Return a promise object which holds the given @var{expr} expression,
919 ready to be evaluated by a later @code{force}.
922 @deffn {Scheme Procedure} promise? obj
923 @deffnx {C Function} scm_promise_p (obj)
924 Return true if @var{obj} is a promise.
928 @deffn {Scheme Procedure} force p
929 @deffnx {C Function} scm_force (p)
930 Return the value obtained from evaluating the @var{expr} in the given
931 promise @var{p}. If @var{p} has previously been forced then its
932 @var{expr} is not evaluated again, instead the value obtained at that
933 time is simply returned.
935 During a @code{force}, an @var{expr} can call @code{force} again on
936 its own promise, resulting in a recursive evaluation of that
937 @var{expr}. The first evaluation to return gives the value for the
938 promise. Higher evaluations run to completion in the normal way, but
939 their results are ignored, @code{force} always returns the first
945 @c TeX-master: "guile.texi"