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 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Read/Load/Eval/Compile
9 @section Reading and Evaluating Scheme Code
11 This chapter describes Guile functions that are concerned with reading,
12 loading, evaluating, and compiling Scheme code at run time.
15 * Scheme Syntax:: Standard and extended Scheme syntax.
16 * Scheme Read:: Reading Scheme code.
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.
22 * Local Evaluation:: Evaluation in a local environment.
23 * Evaluator Behaviour:: Modifying Guile's evaluator.
24 * VM Behaviour:: Modifying Guile's virtual machine.
29 @subsection Scheme Syntax: Standard and Guile Extensions
41 @node Expression Syntax
42 @subsubsection Expression Syntax
44 An expression to be evaluated takes one of the following forms.
49 A symbol is evaluated by dereferencing. A binding of that symbol is
50 sought and the value there used. For example,
57 @item (@var{proc} @var{args}@dots{})
58 A parenthesised expression is a function call. @var{proc} and each
59 argument are evaluated, then the function (which @var{proc} evaluated
60 to) is called with those arguments.
62 The order in which @var{proc} and the arguments are evaluated is
63 unspecified, so be careful when using expressions with side effects.
66 (max 1 2 3) @result{} 3
68 (define (get-some-proc) min)
69 ((get-some-proc) 1 2 3) @result{} 1
72 The same sort of parenthesised form is used for a macro invocation,
73 but in that case the arguments are not evaluated. See the
74 descriptions of macros for more on this (@pxref{Macros}, and
75 @pxref{Syntax Rules}).
78 Number, string, character and boolean constants evaluate ``to
79 themselves'', so can appear as literals.
84 "hello" @result{} "hello"
89 Note that an application must not attempt to modify literal strings,
90 since they may be in read-only memory.
92 @item (quote @var{data})
96 Quoting is used to obtain a literal symbol (instead of a variable
97 reference), a literal list (instead of a function call), or a literal
98 vector. @nicode{'} is simply a shorthand for a @code{quote} form.
103 '(1 2 3) @result{} (1 2 3)
104 '#(1 (2 3) 4) @result{} #(1 (2 3) 4)
105 (quote x) @result{} x
106 (quote (1 2 3)) @result{} (1 2 3)
107 (quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4)
110 Note that an application must not attempt to modify literal lists or
111 vectors obtained from a @code{quote} form, since they may be in
114 @item (quasiquote @var{data})
118 Backquote quasi-quotation is like @code{quote}, but selected
119 sub-expressions are evaluated. This is a convenient way to construct
120 a list or vector structure most of which is constant, but at certain
121 points should have expressions substituted.
123 The same effect can always be had with suitable @code{list},
124 @code{cons} or @code{vector} calls, but quasi-quoting is often easier.
128 @item (unquote @var{expr})
132 Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates
133 an expression to be evaluated and inserted. The comma syntax @code{,}
134 is simply a shorthand for an @code{unquote} form. For example,
137 `(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4)
138 `(1 (unquote (+ 1 1)) 3) @result{} (1 2 3)
139 `#(1 ,(/ 12 2)) @result{} #(1 6)
142 @item (unquote-splicing @var{expr})
144 @findex unquote-splicing
146 Within the quasiquote @var{data}, @code{unquote-splicing} or
147 @code{,@@} indicates an expression to be evaluated and the elements of
148 the returned list inserted. @var{expr} must evaluate to a list. The
149 ``comma-at'' syntax @code{,@@} is simply a shorthand for an
150 @code{unquote-splicing} form.
154 `(1 ,@@x 4) @result{} (1 2 3 4)
155 `(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4)
156 `#(9 ,@@x 9) @result{} #(9 2 3 9)
159 Notice @code{,@@} differs from plain @code{,} in the way one level of
160 nesting is stripped. For @code{,@@} the elements of a returned list
161 are inserted, whereas with @code{,} it would be the list itself
166 @c FIXME: What can we say about the mutability of a quasiquote
167 @c result? R5RS doesn't seem to specify anything, though where it
168 @c says backquote without commas is the same as plain quote then
169 @c presumably the "fixed" portions of a quasiquote expression must be
170 @c treated as immutable.
177 @subsubsection Comments
179 @c FIXME::martin: Review me!
181 Comments in Scheme source files are written by starting them with a
182 semicolon character (@code{;}). The comment then reaches up to the end
183 of the line. Comments can begin at any column, and the may be inserted
184 on the same line as Scheme code.
189 (define x 1) ; Comment after expression
191 ;; Display something.
193 ;;; Comment at left margin.
197 It is common to use a single semicolon for comments following
198 expressions on a line, to use two semicolons for comments which are
199 indented like code, and three semicolons for comments which start at
200 column 0, even if they are inside an indented code block. This
201 convention is used when indenting code in Emacs' Scheme mode.
205 @subsubsection Block Comments
206 @cindex multiline comments
207 @cindex block comments
211 @c FIXME::martin: Review me!
213 In addition to the standard line comments defined by R5RS, Guile has
214 another comment type for multiline comments, called @dfn{block
215 comments}. This type of comment begins with the character sequence
216 @code{#!} and ends with the characters @code{!#}, which must appear on a
217 line of their own. These comments are compatible with the block
218 comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
219 (scsh)}). The characters @code{#!} were chosen because they are the
220 magic characters used in shell scripts for indicating that the name of
221 the program for executing the script follows on the same line.
223 Thus a Guile script often starts like this.
226 #! /usr/local/bin/guile -s
230 More details on Guile scripting can be found in the scripting section
231 (@pxref{Guile Scripting}).
233 @cindex R6RS block comments
234 @cindex SRFI-30 block comments
235 Similarly, Guile (starting from version 2.0) supports nested block
236 comments as specified by R6RS and
237 @url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}:
240 (+ #| this is a #| nested |# block comment |# 2)
244 For backward compatibility, this syntax can be overridden with
245 @code{read-hash-extend} (@pxref{Reader Extensions,
246 @code{read-hash-extend}}).
248 There is one special case where the contents of a comment can actually
249 affect the interpretation of code. When a character encoding
250 declaration, such as @code{coding: utf-8} appears in one of the first
251 few lines of a source file, it indicates to Guile's default reader
252 that this source code file is not ASCII. For details see @ref{Character
253 Encoding of Source Files}.
255 @node Case Sensitivity
256 @subsubsection Case Sensitivity
258 @c FIXME::martin: Review me!
260 Scheme as defined in R5RS is not case sensitive when reading symbols.
261 Guile, on the contrary is case sensitive by default, so the identifiers
268 are the same in R5RS Scheme, but are different in Guile.
270 It is possible to turn off case sensitivity in Guile by setting the
271 reader option @code{case-insensitive}. More on reader options can be
272 found at (@pxref{Reader options}).
275 (read-enable 'case-insensitive)
278 Note that this is seldom a problem, because Scheme programmers tend not
279 to use uppercase letters in their identifiers anyway.
283 @subsubsection Keyword Syntax
286 @node Reader Extensions
287 @subsubsection Reader Extensions
289 @deffn {Scheme Procedure} read-hash-extend chr proc
290 @deffnx {C Function} scm_read_hash_extend (chr, proc)
291 Install the procedure @var{proc} for reading expressions
292 starting with the character sequence @code{#} and @var{chr}.
293 @var{proc} will be called with two arguments: the character
294 @var{chr} and the port to read further data from. The object
295 returned will be the return value of @code{read}.
296 Passing @code{#f} for @var{proc} will remove a previous setting.
302 @subsection Reading Scheme Code
305 @deffn {Scheme Procedure} read [port]
306 @deffnx {C Function} scm_read (port)
307 Read an s-expression from the input port @var{port}, or from
308 the current input port if @var{port} is not specified.
309 Any whitespace before the next token is discarded.
312 The behaviour of Guile's Scheme reader can be modified by manipulating
313 its read options. For more information about options, @xref{User level
314 options interfaces}. If you want to know which reader options are
315 available, @xref{Reader options}.
317 @c FIXME::martin: This is taken from libguile/options.c. Is there
318 @c actually a difference between 'help and 'full?
320 @deffn {Scheme Procedure} read-options [setting]
321 Display the current settings of the read options. If @var{setting} is
322 omitted, only a short form of the current read options is printed.
323 Otherwise, @var{setting} should be one of the following symbols:
326 Display the complete option settings.
328 Like @code{help}, but also print programmer options.
332 @deffn {Scheme Procedure} read-enable option-name
333 @deffnx {Scheme Procedure} read-disable option-name
334 @deffnx {Scheme Procedure} read-set! option-name value
335 Modify the read options. @code{read-enable} should be used with boolean
336 options and switches them on, @code{read-disable} switches them off.
337 @code{read-set!} can be used to set an option to a specific value.
340 @deffn {Scheme Procedure} read-options-interface [setting]
341 @deffnx {C Function} scm_read_options (setting)
342 Option interface for the read options. Instead of using
343 this procedure directly, use the procedures @code{read-enable},
344 @code{read-disable}, @code{read-set!} and @code{read-options}.
349 @subsection Procedures for On the Fly Evaluation
354 @c ARGFIXME environment/environment specifier
355 @deffn {Scheme Procedure} eval exp module_or_state
356 @deffnx {C Function} scm_eval (exp, module_or_state)
357 Evaluate @var{exp}, a list representing a Scheme expression,
358 in the top-level environment specified by @var{module}.
359 While @var{exp} is evaluated (using @code{primitive-eval}),
360 @var{module} is made the current module. The current module
361 is reset to its previous value when @var{eval} returns.
362 XXX - dynamic states.
363 Example: (eval '(+ 1 2) (interaction-environment))
366 @rnindex interaction-environment
367 @deffn {Scheme Procedure} interaction-environment
368 @deffnx {C Function} scm_interaction_environment ()
369 Return a specifier for the environment that contains
370 implementation--defined bindings, typically a superset of those
371 listed in the report. The intent is that this procedure will
372 return the environment in which the implementation would
373 evaluate expressions dynamically typed by the user.
376 @deffn {Scheme Procedure} eval-string string [module]
377 @deffnx {C Function} scm_eval_string (string)
378 @deffnx {C Function} scm_eval_string_in_module (string, module)
379 Evaluate @var{string} as the text representation of a Scheme form or
380 forms, and return whatever value they produce. Evaluation takes place
381 in the given module, or in the current module when no module is given.
382 While the code is evaluated, the given module is made the current one.
383 The current module is restored when this procedure returns.
386 @deftypefn {C Function} SCM scm_c_eval_string (const char *string)
387 @code{scm_eval_string}, but taking a C string instead of an
391 @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
392 @deffnx {C Function} scm_apply_0 (proc, arglst)
393 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
394 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
395 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
396 @deffnx {C Function} scm_apply (proc, arg, rest)
398 Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the
399 elements of the @var{arglst} list.
401 @code{scm_apply} takes parameters corresponding to a Scheme level
402 @code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the
403 last element of the @var{rest} list make up
404 @var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the
405 @var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL}
406 then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
409 @var{arglst} is not modified, but the @var{rest} list passed to
410 @code{scm_apply} is modified.
413 @deffn {C Function} scm_call_0 (proc)
414 @deffnx {C Function} scm_call_1 (proc, arg1)
415 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
416 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
417 @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
418 Call @var{proc} with the given arguments.
421 @deffn {Scheme Procedure} apply:nconc2last lst
422 @deffnx {C Function} scm_nconc2last (lst)
423 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
424 @var{arglst}), with @var{arglst} being a list. This function returns
425 a list comprising @var{arg1} to @var{argN} plus the elements of
426 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
427 is not modified, though the return does share structure with it.
429 This operation collects up the arguments from a list which is
430 @code{apply} style parameters.
433 @deffn {Scheme Procedure} primitive-eval exp
434 @deffnx {C Function} scm_primitive_eval (exp)
435 Evaluate @var{exp} in the top-level environment specified by
441 @subsection Compiling Scheme Code
443 The @code{eval} procedure directly interprets the S-expression
444 representation of Scheme. An alternate strategy for evaluation is to
445 determine ahead of time what computations will be necessary to
446 evaluate the expression, and then use that recipe to produce the
447 desired results. This is known as @dfn{compilation}.
449 While it is possible to compile simple Scheme expressions such as
450 @code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
451 interesting in the context of procedures. Compiling a lambda expression
452 produces a compiled procedure, which is just like a normal procedure
453 except typically much faster, because it can bypass the generic
456 Functions from system modules in a Guile installation are normally
457 compiled already, so they load and run quickly.
459 Note that well-written Scheme programs will not typically call the
460 procedures in this section, for the same reason that it is often bad
461 taste to use @code{eval}. The normal interface to the compiler is the
462 command-line file compiler, which can be invoked from the shell as
463 @code{guile-tools compile @var{foo.scm}}. This interface needs more
466 (Why are calls to @code{eval} and @code{compile} usually in bad taste?
467 Because they are limited, in that they can only really make sense for
468 top-level expressions. Also, most needs for ``compile-time''
469 computation are fulfilled by macros and closures. Of course one good
470 counterexample is the REPL itself, or any code that reads expressions
473 For more information on the compiler itself, see @ref{Compiling to the
474 Virtual Machine}. For information on the virtual machine, see @ref{A
475 Virtual Machine for Guile}.
477 @deffn {Scheme Procedure} compile exp [env=#f] [from=(current-language)] [to=value] [opts=()]
478 Compile the expression @var{exp} in the environment @var{env}. If
479 @var{exp} is a procedure, the result will be a compiled procedure;
480 otherwise @code{compile} is mostly equivalent to @code{eval}.
482 For a discussion of languages and compiler options, @xref{Compiling to
483 the Virtual Machine}.
486 @deffn {Scheme Procedure} compile-file file [to=objcode] [opts='()]
487 Compile the file named @var{file}.
489 Output will be written to a file in the current directory whose name
490 is computed as @code{(compiled-file-name @var{file})}.
493 @deffn {Scheme Procedure} compiled-file-name file
494 Compute an appropriate name for a compiled version of a Scheme file
497 Usually, the result will be the original file name with the
498 @code{.scm} suffix replaced with @code{.go}, but the exact behavior
499 depends on the contents of the @code{%load-extensions} and
500 @code{%load-compiled-extensions} lists.
504 @subsection Loading Scheme Code from File
507 @deffn {Scheme Procedure} load filename [reader]
508 Load @var{filename} and evaluate its contents in the top-level
509 environment. The load paths are not searched.
511 @var{reader} if provided should be either @code{#f}, or a procedure with
512 the signature @code{(lambda (port) @dots{})} which reads the next
513 expression from @var{port}. If @var{reader} is @code{#f} or absent,
514 Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
516 The @var{reader} argument takes effect by setting the value of the
517 @code{current-reader} fluid (see below) before loading the file, and
518 restoring its previous value when loading is complete. The Scheme code
519 inside @var{filename} can itself change the current reader procedure on
520 the fly by setting @code{current-reader} fluid.
522 If the variable @code{%load-hook} is defined, it should be bound to a
523 procedure that will be called before any code is loaded. See
524 documentation for @code{%load-hook} later in this section.
527 @deffn {Scheme Procedure} load-compiled filename
528 Load the compiled file named @var{filename}. The load paths are not
531 Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
532 calling @code{load-compiled} on the resulting file is equivalent to
533 calling @code{load} on the source file.
536 @deffn {Scheme Procedure} load-from-path filename
537 Similar to @code{load}, but searches for @var{filename} in the load
538 paths. Preferentially loads a compiled version of the file, if it is
539 available and up-to-date.
542 @deffn {Scheme Procedure} primitive-load filename
543 @deffnx {C Function} scm_primitive_load (filename)
544 Load the file named @var{filename} and evaluate its contents in
545 the top-level environment. The load paths are not searched;
546 @var{filename} must either be a full pathname or be a pathname
547 relative to the current directory. If the variable
548 @code{%load-hook} is defined, it should be bound to a procedure
549 that will be called before any code is loaded. See the
550 documentation for @code{%load-hook} later in this section.
553 @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
554 @code{scm_primitive_load}, but taking a C string instead of an
558 @deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
559 @deffnx {C Function} scm_primitive_load_path (filename)
560 Search @code{%load-path} for the file named @var{filename} and
561 load it into the top-level environment. If @var{filename} is a
562 relative pathname and is not found in the list of search paths,
563 an error is signalled. Preferentially loads a compiled version of the
564 file, if it is available and up-to-date.
566 By default or if @var{exception-on-not-found} is true, an exception is
567 raised if @var{filename} is not found. If @var{exception-on-not-found}
568 is @code{#f} and @var{filename} is not found, no exception is raised and
569 @code{#f} is returned. For compatibility with Guile 1.8 and earlier,
570 the C function takes only one argument, which can be either a string
571 (the file name) or an argument list.
574 @deffn {Scheme Procedure} %search-load-path filename
575 @deffnx {C Function} scm_sys_search_load_path (filename)
576 Search @code{%load-path} for the file named @var{filename},
577 which must be readable by the current user. If @var{filename}
578 is found in the list of paths to search or is an absolute
579 pathname, return its full pathname. Otherwise, return
580 @code{#f}. Filenames may have any of the optional extensions
581 in the @code{%load-extensions} list; @code{%search-load-path}
582 will try each extension automatically.
585 @defvar current-reader
586 @code{current-reader} holds the read procedure that is currently being
587 used by the above loading procedures to read expressions (from the file
588 that they are loading). @code{current-reader} is a fluid, so it has an
589 independent value in each dynamic root and should be read and set using
590 @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
593 Changing @code{current-reader} is typically useful to introduce local
594 syntactic changes, such that code following the @code{fluid-set!} call
595 is read using the newly installed reader. The @code{current-reader}
596 change should take place at evaluation time when the code is evaluated,
597 or at compilation time when the code is compiled:
601 (eval-when (compile eval)
602 (fluid-set! current-reader my-own-reader))
605 The @code{eval-when} form above ensures that the @code{current-reader}
606 change occurs at the right time.
610 A procedure to be called @code{(%load-hook @var{filename})} whenever a
611 file is loaded, or @code{#f} for no such call. @code{%load-hook} is
612 used by all of the above loading functions (@code{load},
613 @code{load-path}, @code{primitive-load} and
614 @code{primitive-load-path}).
616 For example an application can set this to show what's loaded,
619 (set! %load-hook (lambda (filename)
620 (format #t "Loading ~a ...\n" filename)))
621 (load-from-path "foo.scm")
622 @print{} Loading /usr/local/share/guile/site/foo.scm ...
626 @deffn {Scheme Procedure} current-load-port
627 @deffnx {C Function} scm_current_load_port ()
628 Return the current-load-port.
629 The load port is used internally by @code{primitive-load}.
632 @defvar %load-extensions
633 A list of default file extensions for files containing Scheme code.
634 @code{%search-load-path} tries each of these extensions when looking for
635 a file to load. By default, @code{%load-extensions} is bound to the
636 list @code{("" ".scm")}.
639 @node Character Encoding of Source Files
640 @subsection Character Encoding of Source Files
642 @cindex source file encoding
643 @cindex primitive-load
645 Scheme source code files are usually encoded in ASCII, but, the
646 built-in reader can interpret other character encodings. The
647 procedure @code{primitive-load}, and by extension the functions that
648 call it, such as @code{load}, first scan the top 500 characters of the
649 file for a coding declaration.
651 A coding declaration has the form @code{coding: XXXXXX}, where
652 @code{XXXXXX} is the name of a character encoding in which the source
653 code file has been encoded. The coding declaration must appear in a
654 scheme comment. It can either be a semicolon-initiated comment or a block
657 The name of the character encoding in the coding declaration is
658 typically lower case and containing only letters, numbers, and hyphens,
659 as recognized by @code{set-port-encoding!} (@pxref{Ports,
660 @code{set-port-encoding!}}). Common examples of character encoding
661 names are @code{utf-8} and @code{iso-8859-1},
662 @url{http://www.iana.org/assignments/character-sets, as defined by
663 IANA}. Thus, the coding declaration is mostly compatible with Emacs.
665 However, there are some differences in encoding names recognized by
666 Emacs and encoding names defined by IANA, the latter being essentially a
667 subset of the former. For instance, @code{latin-1} is a valid encoding
668 name for Emacs, but it's not according to the IANA standard, which Guile
669 follows; instead, you should use @code{iso-8859-1}, which is both
670 understood by Emacs and dubbed by IANA (IANA writes it uppercase but
671 Emacs wants it lowercase and Guile is case insensitive.)
673 For source code, only a subset of all possible character encodings can
674 be interpreted by the built-in source code reader. Only those
675 character encodings in which ASCII text appears unmodified can be
676 used. This includes @code{UTF-8} and @code{ISO-8859-1} through
677 @code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
678 and @code{UTF-32} may not be used because they are not compatible with
683 @cindex port encoding
684 @findex set-port-encoding!
685 There might be a scenario in which one would want to read non-ASCII
686 code from a port, such as with the function @code{read}, instead of
687 with @code{load}. If the port's character encoding is the same as the
688 encoding of the code to be read by the port, not other special
689 handling is necessary. The port will automatically do the character
690 encoding conversion. The functions @code{setlocale} or by
691 @code{set-port-encoding!} are used to set port encodings
694 If a port is used to read code of unknown character encoding, it can
695 accomplish this in three steps. First, the character encoding of the
696 port should be set to ISO-8859-1 using @code{set-port-encoding!}.
697 Then, the procedure @code{file-encoding}, described below, is used to
698 scan for a coding declaration when reading from the port. As a side
699 effect, it rewinds the port after its scan is complete. After that,
700 the port's character encoding should be set to the encoding returned
701 by @code{file-encoding}, if any, again by using
702 @code{set-port-encoding!}. Then the code can be read as normal.
704 @deffn {Scheme Procedure} file-encoding port
705 @deffnx {C Function} scm_file_encoding port
706 Scan the port for an Emacs-like character coding declaration near the
707 top of the contents of a port with random-accessible contents
708 (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs,
709 The GNU Emacs Reference Manual}). The coding declaration is of the form
710 @code{coding: XXXXX} and must appear in a Scheme comment. Return a
711 string containing the character encoding of the file if a declaration
712 was found, or @code{#f} otherwise. The port is rewound.
716 @node Delayed Evaluation
717 @subsection Delayed Evaluation
718 @cindex delayed evaluation
721 Promises are a convenient way to defer a calculation until its result
722 is actually needed, and to run such a calculation only once.
724 @deffn syntax delay expr
726 Return a promise object which holds the given @var{expr} expression,
727 ready to be evaluated by a later @code{force}.
730 @deffn {Scheme Procedure} promise? obj
731 @deffnx {C Function} scm_promise_p (obj)
732 Return true if @var{obj} is a promise.
736 @deffn {Scheme Procedure} force p
737 @deffnx {C Function} scm_force (p)
738 Return the value obtained from evaluating the @var{expr} in the given
739 promise @var{p}. If @var{p} has previously been forced then its
740 @var{expr} is not evaluated again, instead the value obtained at that
741 time is simply returned.
743 During a @code{force}, an @var{expr} can call @code{force} again on
744 its own promise, resulting in a recursive evaluation of that
745 @var{expr}. The first evaluation to return gives the value for the
746 promise. Higher evaluations run to completion in the normal way, but
747 their results are ignored, @code{force} always returns the first
752 @node Local Evaluation
753 @subsection Local Evaluation
757 @deffn {Scheme Procedure} local-eval exp [env]
758 @deffnx {C Function} scm_local_eval (exp, env)
759 Evaluate @var{exp} in its environment. If @var{env} is supplied,
760 it is the environment in which to evaluate @var{exp}. Otherwise,
761 @var{exp} must be a memoized code object (in which case, its environment
766 @node Evaluator Behaviour
767 @subsection Evaluator Behaviour
769 @c FIXME::martin: Maybe this node name is bad, but the old name clashed with
770 @c `Evaluator options' under `Options and Config'.
772 The behaviour of Guile's evaluator can be modified by manipulating the
773 evaluator options. For more information about options, @xref{User level
774 options interfaces}. If you want to know which evaluator options are
775 available, @xref{Evaluator options}.
777 @c FIXME::martin: This is taken from libguile/options.c. Is there
778 @c actually a difference between 'help and 'full?
780 @deffn {Scheme Procedure} eval-options [setting]
781 Display the current settings of the evaluator options. If @var{setting}
782 is omitted, only a short form of the current evaluator options is
783 printed. Otherwise, @var{setting} should be one of the following
787 Display the complete option settings.
789 Like @code{help}, but also print programmer options.
793 @deffn {Scheme Procedure} eval-enable option-name
794 @deffnx {Scheme Procedure} eval-disable option-name
795 @deffnx {Scheme Procedure} eval-set! option-name value
796 Modify the evaluator options. @code{eval-enable} should be used with boolean
797 options and switches them on, @code{eval-disable} switches them off.
798 @code{eval-set!} can be used to set an option to a specific value.
801 @deffn {Scheme Procedure} eval-options-interface [setting]
802 @deffnx {C Function} scm_eval_options_interface (setting)
803 Option interface for the evaluation options. Instead of using
804 this procedure directly, use the procedures @code{eval-enable},
805 @code{eval-disable}, @code{eval-set!} and @code{eval-options}.
808 @c FIXME::martin: Why aren't these procedure named like the other options
811 @deffn {Scheme Procedure} traps [setting]
812 Display the current settings of the evaluator traps options. If
813 @var{setting} is omitted, only a short form of the current evaluator
814 traps options is printed. Otherwise, @var{setting} should be one of the
818 Display the complete option settings.
820 Like @code{help}, but also print programmer options.
824 @deffn {Scheme Procedure} trap-enable option-name
825 @deffnx {Scheme Procedure} trap-disable option-name
826 @deffnx {Scheme Procedure} trap-set! option-name value
827 Modify the evaluator options. @code{trap-enable} should be used with boolean
828 options and switches them on, @code{trap-disable} switches them off.
829 @code{trap-set!} can be used to set an option to a specific value.
831 See @ref{Evaluator trap options} for more information on the available
835 @deffn {Scheme Procedure} evaluator-traps-interface [setting]
836 @deffnx {C Function} scm_evaluator_traps (setting)
837 Option interface for the evaluator trap options.
841 @subsection VM Behaviour
843 Like the procedures from the previous section that operate on the
844 evaluator, there are also procedures to modify the behavior of a
847 The most useful thing that a user can do is to add to one of the
848 virtual machine's predefined hooks:
850 @deffn {Scheme Procedure} vm-next-hook vm
851 @deffnx {Scheme Procedure} vm-apply-hook vm
852 @deffnx {Scheme Procedure} vm-boot-hook vm
853 @deffnx {Scheme Procedure} vm-return-hook vm
854 @deffnx {Scheme Procedure} vm-break-hook vm
855 @deffnx {Scheme Procedure} vm-exit-hook vm
856 @deffnx {Scheme Procedure} vm-halt-hook vm
857 @deffnx {Scheme Procedure} vm-enter-hook vm
858 Accessors to a virtual machine's hooks. Usually you pass
859 @code{(the-vm)} as the @var{vm}.
862 @xref{A Virtual Machine for Guile}, for more information on Guile's
866 @c TeX-master: "guile.texi"