2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @section Reading and Evaluating Scheme Code
11 This chapter describes Guile functions that are concerned with reading,
12 loading and evaluating 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 * Loading:: Loading Scheme code from file.
19 * Delayed Evaluation:: Postponing evaluation until it is needed.
20 * Local Evaluation:: Evaluation in a local environment.
21 * Evaluator Behaviour:: Modifying Guile's evaluator.
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}).
231 @node Case Sensitivity
232 @subsubsection Case Sensitivity
234 @c FIXME::martin: Review me!
236 Scheme as defined in R5RS is not case sensitive when reading symbols.
237 Guile, on the contrary is case sensitive by default, so the identifiers
244 are the same in R5RS Scheme, but are different in Guile.
246 It is possible to turn off case sensitivity in Guile by setting the
247 reader option @code{case-insensitive}. More on reader options can be
248 found at (@pxref{Reader options}).
251 (read-enable 'case-insensitive)
254 Note that this is seldom a problem, because Scheme programmers tend not
255 to use uppercase letters in their identifiers anyway.
259 @subsubsection Keyword Syntax
262 @node Reader Extensions
263 @subsubsection Reader Extensions
265 @deffn {Scheme Procedure} read-hash-extend chr proc
266 @deffnx {C Function} scm_read_hash_extend (chr, proc)
267 Install the procedure @var{proc} for reading expressions
268 starting with the character sequence @code{#} and @var{chr}.
269 @var{proc} will be called with two arguments: the character
270 @var{chr} and the port to read further data from. The object
271 returned will be the return value of @code{read}.
276 @subsection Reading Scheme Code
279 @deffn {Scheme Procedure} read [port]
280 @deffnx {C Function} scm_read (port)
281 Read an s-expression from the input port @var{port}, or from
282 the current input port if @var{port} is not specified.
283 Any whitespace before the next token is discarded.
286 The behaviour of Guile's Scheme reader can be modified by manipulating
287 its read options. For more information about options, @xref{User level
288 options interfaces}. If you want to know which reader options are
289 available, @xref{Reader options}.
291 @c FIXME::martin: This is taken from libguile/options.c. Is there
292 @c actually a difference between 'help and 'full?
294 @deffn {Scheme Procedure} read-options [setting]
295 Display the current settings of the read options. If @var{setting} is
296 omitted, only a short form of the current read options is printed.
297 Otherwise, @var{setting} should be one of the following symbols:
300 Display the complete option settings.
302 Like @code{help}, but also print programmer options.
306 @deffn {Scheme Procedure} read-enable option-name
307 @deffnx {Scheme Procedure} read-disable option-name
308 @deffnx {Scheme Procedure} read-set! option-name value
309 Modify the read options. @code{read-enable} should be used with boolean
310 options and switches them on, @code{read-disable} switches them off.
311 @code{read-set!} can be used to set an option to a specific value.
314 @deffn {Scheme Procedure} read-options-interface [setting]
315 @deffnx {C Function} scm_read_options (setting)
316 Option interface for the read options. Instead of using
317 this procedure directly, use the procedures @code{read-enable},
318 @code{read-disable}, @code{read-set!} and @code{read-options}.
323 @subsection Procedures for On the Fly Evaluation
328 @c ARGFIXME environment/environment specifier
329 @deffn {Scheme Procedure} eval exp module_or_state
330 @deffnx {C Function} scm_eval (exp, module_or_state)
331 Evaluate @var{exp}, a list representing a Scheme expression,
332 in the top-level environment specified by @var{module}.
333 While @var{exp} is evaluated (using @code{primitive-eval}),
334 @var{module} is made the current module. The current module
335 is reset to its previous value when @var{eval} returns.
336 XXX - dynamic states.
337 Example: (eval '(+ 1 2) (interaction-environment))
340 @rnindex interaction-environment
341 @deffn {Scheme Procedure} interaction-environment
342 @deffnx {C Function} scm_interaction_environment ()
343 Return a specifier for the environment that contains
344 implementation--defined bindings, typically a superset of those
345 listed in the report. The intent is that this procedure will
346 return the environment in which the implementation would
347 evaluate expressions dynamically typed by the user.
350 @deffn {Scheme Procedure} eval-string string [module]
351 @deffnx {C Function} scm_eval_string (string)
352 @deffnx {C Function} scm_eval_string_in_module (string, module)
353 Evaluate @var{string} as the text representation of a Scheme form or
354 forms, and return whatever value they produce. Evaluation takes place
355 in the given module, or in the current module when no module is given.
356 While the code is evaluated, the given module is made the current one.
357 The current module is restored when this procedure returns.
360 @deftypefn {C Function} SCM scm_c_eval_string (const char *string)
361 @code{scm_eval_string}, but taking a C string instead of an
365 @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
366 @deffnx {C Function} scm_apply_0 (proc, arglst)
367 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
368 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
369 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
370 @deffnx {C Function} scm_apply (proc, arg, rest)
372 Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the
373 elements of the @var{arglst} list.
375 @code{scm_apply} takes parameters corresponding to a Scheme level
376 @code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the
377 last element of the @var{rest} list make up
378 @var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the
379 @var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL}
380 then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
383 @var{arglst} is not modified, but the @var{rest} list passed to
384 @code{scm_apply} is modified.
387 @deffn {C Function} scm_call_0 (proc)
388 @deffnx {C Function} scm_call_1 (proc, arg1)
389 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
390 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
391 @deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
392 Call @var{proc} with the given arguments.
395 @deffn {Scheme Procedure} apply:nconc2last lst
396 @deffnx {C Function} scm_nconc2last (lst)
397 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
398 @var{arglst}), with @var{arglst} being a list. This function returns
399 a list comprising @var{arg1} to @var{argN} plus the elements of
400 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
401 is not modified, though the return does share structure with it.
403 This operation collects up the arguments from a list which is
404 @code{apply} style parameters.
407 @deffn {Scheme Procedure} primitive-eval exp
408 @deffnx {C Function} scm_primitive_eval (exp)
409 Evaluate @var{exp} in the top-level environment specified by
415 @subsection Loading Scheme Code from File
418 @deffn {Scheme Procedure} load filename [reader]
419 Load @var{filename} and evaluate its contents in the top-level
420 environment. The load paths are not searched.
422 @var{reader} if provided should be either @code{#f}, or a procedure with
423 the signature @code{(lambda (port) @dots{})} which reads the next
424 expression from @var{port}. If @var{reader} is @code{#f} or absent,
425 Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
427 The @var{reader} argument takes effect by setting the value of the
428 @code{current-reader} fluid (see below) before loading the file, and
429 restoring its previous value when loading is complete. The Scheme code
430 inside @var{filename} can itself change the current reader procedure on
431 the fly by setting @code{current-reader} fluid.
433 If the variable @code{%load-hook} is defined, it should be bound to a
434 procedure that will be called before any code is loaded. See
435 documentation for @code{%load-hook} later in this section.
438 @deffn {Scheme Procedure} load-from-path filename
439 Similar to @code{load}, but searches for @var{filename} in the load
443 @deffn {Scheme Procedure} primitive-load filename
444 @deffnx {C Function} scm_primitive_load (filename)
445 Load the file named @var{filename} and evaluate its contents in
446 the top-level environment. The load paths are not searched;
447 @var{filename} must either be a full pathname or be a pathname
448 relative to the current directory. If the variable
449 @code{%load-hook} is defined, it should be bound to a procedure
450 that will be called before any code is loaded. See the
451 documentation for @code{%load-hook} later in this section.
454 @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
455 @code{scm_primitive_load}, but taking a C string instead of an
459 @deffn {Scheme Procedure} primitive-load-path filename
460 @deffnx {C Function} scm_primitive_load_path (filename)
461 Search @code{%load-path} for the file named @var{filename} and
462 load it into the top-level environment. If @var{filename} is a
463 relative pathname and is not found in the list of search paths,
464 an error is signalled.
467 @deffn {Scheme Procedure} %search-load-path filename
468 @deffnx {C Function} scm_sys_search_load_path (filename)
469 Search @code{%load-path} for the file named @var{filename},
470 which must be readable by the current user. If @var{filename}
471 is found in the list of paths to search or is an absolute
472 pathname, return its full pathname. Otherwise, return
473 @code{#f}. Filenames may have any of the optional extensions
474 in the @code{%load-extensions} list; @code{%search-load-path}
475 will try each extension automatically.
478 @defvar current-reader
479 @code{current-reader} holds the read procedure that is currently being
480 used by the above loading procedures to read expressions (from the file
481 that they are loading). @code{current-reader} is a fluid, so it has an
482 independent value in each dynamic root and should be read and set using
483 @code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
488 A procedure to be called @code{(%load-hook @var{filename})} whenever a
489 file is loaded, or @code{#f} for no such call. @code{%load-hook} is
490 used by all of the above loading functions (@code{load},
491 @code{load-path}, @code{primitive-load} and
492 @code{primitive-load-path}).
494 For example an application can set this to show what's loaded,
497 (set! %load-hook (lambda (filename)
498 (format #t "Loading ~a ...\n" filename)))
499 (load-from-path "foo.scm")
500 @print{} Loading /usr/local/share/guile/site/foo.scm ...
504 @deffn {Scheme Procedure} current-load-port
505 @deffnx {C Function} scm_current_load_port ()
506 Return the current-load-port.
507 The load port is used internally by @code{primitive-load}.
510 @defvar %load-extensions
511 A list of default file extensions for files containing Scheme code.
512 @code{%search-load-path} tries each of these extensions when looking for
513 a file to load. By default, @code{%load-extensions} is bound to the
514 list @code{("" ".scm")}.
518 @node Delayed Evaluation
519 @subsection Delayed Evaluation
520 @cindex delayed evaluation
523 Promises are a convenient way to defer a calculation until its result
524 is actually needed, and to run such a calculation only once.
526 @deffn syntax delay expr
528 Return a promise object which holds the given @var{expr} expression,
529 ready to be evaluated by a later @code{force}.
532 @deffn {Scheme Procedure} promise? obj
533 @deffnx {C Function} scm_promise_p (obj)
534 Return true if @var{obj} is a promise.
538 @deffn {Scheme Procedure} force p
539 @deffnx {C Function} scm_force (p)
540 Return the value obtained from evaluating the @var{expr} in the given
541 promise @var{p}. If @var{p} has previously been forced then its
542 @var{expr} is not evaluated again, instead the value obtained at that
543 time is simply returned.
545 During a @code{force}, an @var{expr} can call @code{force} again on
546 its own promise, resulting in a recursive evaluation of that
547 @var{expr}. The first evaluation to return gives the value for the
548 promise. Higher evaluations run to completion in the normal way, but
549 their results are ignored, @code{force} always returns the first
554 @node Local Evaluation
555 @subsection Local Evaluation
559 @deffn {Scheme Procedure} local-eval exp [env]
560 @deffnx {C Function} scm_local_eval (exp, env)
561 Evaluate @var{exp} in its environment. If @var{env} is supplied,
562 it is the environment in which to evaluate @var{exp}. Otherwise,
563 @var{exp} must be a memoized code object (in which case, its environment
568 @node Evaluator Behaviour
569 @subsection Evaluator Behaviour
571 @c FIXME::martin: Maybe this node name is bad, but the old name clashed with
572 @c `Evaluator options' under `Options and Config'.
574 The behaviour of Guile's evaluator can be modified by manipulating the
575 evaluator options. For more information about options, @xref{User level
576 options interfaces}. If you want to know which evaluator options are
577 available, @xref{Evaluator options}.
579 @c FIXME::martin: This is taken from libguile/options.c. Is there
580 @c actually a difference between 'help and 'full?
582 @deffn {Scheme Procedure} eval-options [setting]
583 Display the current settings of the evaluator options. If @var{setting}
584 is omitted, only a short form of the current evaluator options is
585 printed. Otherwise, @var{setting} should be one of the following
589 Display the complete option settings.
591 Like @code{help}, but also print programmer options.
595 @deffn {Scheme Procedure} eval-enable option-name
596 @deffnx {Scheme Procedure} eval-disable option-name
597 @deffnx {Scheme Procedure} eval-set! option-name value
598 Modify the evaluator options. @code{eval-enable} should be used with boolean
599 options and switches them on, @code{eval-disable} switches them off.
600 @code{eval-set!} can be used to set an option to a specific value.
603 @deffn {Scheme Procedure} eval-options-interface [setting]
604 @deffnx {C Function} scm_eval_options_interface (setting)
605 Option interface for the evaluation options. Instead of using
606 this procedure directly, use the procedures @code{eval-enable},
607 @code{eval-disable}, @code{eval-set!} and @code{eval-options}.
610 @c FIXME::martin: Why aren't these procedure named like the other options
613 @deffn {Scheme Procedure} traps [setting]
614 Display the current settings of the evaluator traps options. If
615 @var{setting} is omitted, only a short form of the current evaluator
616 traps options is printed. Otherwise, @var{setting} should be one of the
620 Display the complete option settings.
622 Like @code{help}, but also print programmer options.
626 @deffn {Scheme Procedure} trap-enable option-name
627 @deffnx {Scheme Procedure} trap-disable option-name
628 @deffnx {Scheme Procedure} trap-set! option-name value
629 Modify the evaluator options. @code{trap-enable} should be used with boolean
630 options and switches them on, @code{trap-disable} switches them off.
631 @code{trap-set!} can be used to set an option to a specific value.
633 See @ref{Evaluator trap options} for more information on the available
637 @deffn {Scheme Procedure} evaluator-traps-interface [setting]
638 @deffnx {C Function} scm_evaluator_traps (setting)
639 Option interface for the evaluator trap options.
644 @c TeX-master: "guile.texi"