2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @chapter 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 @section Scheme Syntax: Standard and Guile Extensions
38 @node Expression Syntax
39 @subsection Expression Syntax
45 @c FIXME::martin: Review me!
47 Comments in Scheme source files are written by starting them with a
48 semicolon character (@code{;}). The comment then reaches up to the end
49 of the line. Comments can begin at any column, and the may be inserted
50 on the same line as Scheme code.
55 (define x 1) ; Comment after expression
59 ;;; Comment at left margin.
63 It is common to use a single semicolon for comments following
64 expressions on a line, to use two semicolons for comments which are
65 indented like code, and three semicolons for comments which start at
66 column 0, even if they are inside an indented code block. This
67 convention is used when indenting code in Emacs' Scheme mode.
71 @subsection Block Comments
73 @c FIXME::martin: Review me!
75 @cindex multiline comments
76 In addition to the standard line comments defined by R5RS, Guile has
77 another comment type for multiline comments, called @dfn{block
78 comments}. This type of comment begins with the character sequence
79 @code{#!} and ends with the characters @code{!#}, which must appear on a
80 line of their own. These comments are compatible with the block
81 comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
82 (scsh)}). The characters @code{#!} were chosen because they are the
83 magic characters used in shell scripts for indicating that the name of
84 the program for executing the script follows on the same line.
86 Thus a Guile script often starts like this.
89 #! /usr/local/bin/guile -s
93 More details on Guile scripting can be found in the scripting section
94 (@pxref{Guile Scripting}).
97 @node Case Sensitivity
98 @subsection Case Sensitivity
100 @c FIXME::martin: Review me!
102 Scheme as defined in R5RS is not case sensitive when reading symbols.
103 Guile, on the contrary is case sensitive by default, so the identifiers
110 are the same in R5RS Scheme, but are different in Guile.
112 It is possible to turn off case sensitivity in Guile by setting the
113 reader option @code{case-insensitive}. More on reader options can be
114 found at (@pxref{Reader options}).
117 (read-enable 'case-insensitive)
120 Note that this is seldom a problem, because Scheme programmers tend not
121 to use uppercase letters in their identifiers anyway.
125 @subsection Keyword Syntax
128 @node Reader Extensions
129 @subsection Reader Extensions
131 @deffn {Scheme Procedure} read-hash-extend chr proc
132 @deffnx {C Function} scm_read_hash_extend (chr, proc)
133 Install the procedure @var{proc} for reading expressions
134 starting with the character sequence @code{#} and @var{chr}.
135 @var{proc} will be called with two arguments: the character
136 @var{chr} and the port to read further data from. The object
137 returned will be the return value of @code{read}.
142 @section Reading Scheme Code
145 @deffn {Scheme Procedure} read [port]
146 @deffnx {C Function} scm_read (port)
147 Read an s-expression from the input port @var{port}, or from
148 the current input port if @var{port} is not specified.
149 Any whitespace before the next token is discarded.
152 The behaviour of Guile's Scheme reader can be modified by manipulating
153 its read options. For more information about options, @xref{User level
154 options interfaces}. If you want to know which reader options are
155 available, @xref{Reader options}.
157 @c FIXME::martin: This is taken from libguile/options.c. Is there
158 @c actually a difference between 'help and 'full?
160 @deffn {Scheme Procedure} read-options [setting]
161 Display the current settings of the read options. If @var{setting} is
162 omitted, only a short form of the current read options is printed.
163 Otherwise, @var{setting} should be one of the following symbols:
166 Display the complete option settings.
168 Like @code{help}, but also print programmer options.
172 @deffn {Scheme Procedure} read-enable option-name
173 @deffnx {Scheme Procedure} read-disable option-name
174 @deffnx {Scheme Procedure} read-set! option-name value
175 Modify the read options. @code{read-enable} should be used with boolean
176 options and switches them on, @code{read-disable} switches them off.
177 @code{read-set!} can be used to set an option to a specific value.
180 @deffn {Scheme Procedure} read-options-interface [setting]
181 @deffnx {C Function} scm_read_options (setting)
182 Option interface for the read options. Instead of using
183 this procedure directly, use the procedures @code{read-enable},
184 @code{read-disable}, @code{read-set!} and @code{read-options}.
189 @section Procedures for On the Fly Evaluation
194 @c ARGFIXME environment/environment specifier
195 @deffn {Scheme Procedure} eval exp module
196 @deffnx {C Function} scm_eval (exp, module)
197 Evaluate @var{exp}, a list representing a Scheme expression,
198 in the top-level environment specified by @var{module}.
199 While @var{exp} is evaluated (using @code{primitive-eval}),
200 @var{module} is made the current module. The current module
201 is reset to its previous value when @var{eval} returns.
204 @rnindex interaction-environment
205 @deffn {Scheme Procedure} interaction-environment
206 @deffnx {C Function} scm_interaction_environment ()
207 Return a specifier for the environment that contains
208 implementation--defined bindings, typically a superset of those
209 listed in the report. The intent is that this procedure will
210 return the environment in which the implementation would
211 evaluate expressions dynamically typed by the user.
214 @deffn {Scheme Procedure} eval-string string [module]
215 @deffnx {C Function} scm_eval_string (string)
216 @deffnx {C Function} scm_eval_string_in_module (string, module)
217 Evaluate @var{string} as the text representation of a Scheme form or
218 forms, and return whatever value they produce. Evaluation takes place
219 in the given module, or in the current module when no module is given.
220 While the code is evaluated, the given module is made the current one.
221 The current module is restored when this procedure returns.
224 @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
225 @deffnx {C Function} scm_apply_0 (proc, arglst)
226 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
227 @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
228 @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
229 @deffnx {C Function} scm_apply (proc, arg, rest)
231 Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the
232 elements of the @var{arglst} list.
234 @code{scm_apply} takes parameters corresponding to a Scheme level
235 @code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the
236 last element of the @var{rest} list make up
237 @var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the
238 @var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL}
239 then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the
242 @var{arglst} is not modified, but the @var{rest} list passed to
243 @code{scm_apply} is modified.
246 @deffn {C Function} scm_call_0 (proc)
247 @deffnx {C Function} scm_call_1 (proc, arg1)
248 @deffnx {C Function} scm_call_2 (proc, arg1, arg2)
249 @deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
250 Call @var{proc} with the given arguments.
253 @deffn {Scheme Procedure} apply:nconc2last lst
254 @deffnx {C Function} scm_nconc2last (lst)
255 @var{lst} should be a list (@var{arg1} @dots{} @var{argN}
256 @var{arglst}), with @var{arglst} being a list. This function returns
257 a list comprising @var{arg1} to @var{argN} plus the elements of
258 @var{arglst}. @var{lst} is modified to form the return. @var{arglst}
259 is not modified, though the return does share structure with it.
261 This operation collects up the arguments from a list which is
262 @code{apply} style parameters.
265 @deffn {Scheme Procedure} primitive-eval exp
266 @deffnx {C Function} scm_primitive_eval (exp)
267 Evaluate @var{exp} in the top-level environment specified by
273 @section Loading Scheme Code from File
276 @deffn {Scheme Procedure} load filename
277 Load @var{filename} and evaluate its contents in the top-level
278 environment. The load paths are not searched. If the variable
279 @code{%load-hook} is defined, it should be bound to a procedure that
280 will be called before any code is loaded. See documentation for
281 @code{%load-hook} later in this section.
284 @deffn {Scheme Procedure} load-from-path filename
285 Similar to @code{load}, but searches for @var{filename} in the load
289 @deffn {Scheme Procedure} primitive-load filename
290 @deffnx {C Function} scm_primitive_load (filename)
291 Load the file named @var{filename} and evaluate its contents in
292 the top-level environment. The load paths are not searched;
293 @var{filename} must either be a full pathname or be a pathname
294 relative to the current directory. If the variable
295 @code{%load-hook} is defined, it should be bound to a procedure
296 that will be called before any code is loaded. See the
297 documentation for @code{%load-hook} later in this section.
300 @deffn {Scheme Procedure} primitive-load-path filename
301 @deffnx {C Function} scm_primitive_load_path (filename)
302 Search @var{%load-path} for the file named @var{filename} and
303 load it into the top-level environment. If @var{filename} is a
304 relative pathname and is not found in the list of search paths,
305 an error is signalled.
308 @deffn {Scheme Procedure} %search-load-path filename
309 @deffnx {C Function} scm_sys_search_load_path (filename)
310 Search @var{%load-path} for the file named @var{filename},
311 which must be readable by the current user. If @var{filename}
312 is found in the list of paths to search or is an absolute
313 pathname, return its full pathname. Otherwise, return
314 @code{#f}. Filenames may have any of the optional extensions
315 in the @code{%load-extensions} list; @code{%search-load-path}
316 will try each extension automatically.
320 A procedure to be run whenever @code{primitive-load} is called. If this
321 procedure is defined, it will be called with the filename argument that
322 was passed to @code{primitive-load}.
325 (define %load-hook (lambda (file)
328 (write-line "...."))) @result{} undefined
329 (load-from-path "foo.scm")
330 @print{} Loading /usr/local/share/guile/site/foo.scm....
335 @deffn {Scheme Procedure} current-load-port
336 @deffnx {C Function} scm_current_load_port ()
337 Return the current-load-port.
338 The load port is used internally by @code{primitive-load}.
341 @defvar %load-extensions
342 A list of default file extensions for files containing Scheme code.
343 @code{%search-load-path} tries each of these extensions when looking for
344 a file to load. By default, @code{%load-extensions} is bound to the
345 list @code{("" ".scm")}.
349 @node Delayed Evaluation
350 @section Delayed Evaluation
351 @cindex delayed evaluation
354 Promises are a convenient way to defer a calculation until its result
355 is actually needed, and to run such a calculation only once.
357 @deffn syntax delay expr
359 Return a promise object which holds the given @var{expr} expression,
360 ready to be evaluated by a later @code{force}.
363 @deffn {Scheme Procedure} promise? obj
364 @deffnx {C Function} scm_promise_p (obj)
365 Return true if @var{obj} is a promise.
369 @deffn {Scheme Procedure} force p
370 @deffnx {C Function} scm_force (p)
371 Return the value obtained from evaluating the @var{expr} in the given
372 promise @var{p}. If @var{p} has previously been forced then its
373 @var{expr} is not evaluated again, instead the value obtained at that
374 time is simply returned.
376 During a @code{force}, an @var{expr} can call @code{force} again on
377 its own promise, resulting in a recursive evaluation of that
378 @var{expr}. The first evaluation to return gives the value for the
379 promise. Higher evaluations run to completion in the normal way, but
380 their results are ignored, @code{force} always returns the first
385 @node Local Evaluation
386 @section Local Evaluation
390 @deffn {Scheme Procedure} local-eval exp [env]
391 @deffnx {C Function} scm_local_eval (exp, env)
392 Evaluate @var{exp} in its environment. If @var{env} is supplied,
393 it is the environment in which to evaluate @var{exp}. Otherwise,
394 @var{exp} must be a memoized code object (in which case, its environment
399 @node Evaluator Behaviour
400 @section Evaluator Behaviour
402 @c FIXME::martin: Maybe this node name is bad, but the old name clashed with
403 @c `Evaluator options' under `Options and Config'.
405 The behaviour of Guile's evaluator can be modified by manipulating the
406 evaluator options. For more information about options, @xref{User level
407 options interfaces}. If you want to know which evaluator options are
408 available, @xref{Evaluator options}.
410 @c FIXME::martin: This is taken from libguile/options.c. Is there
411 @c actually a difference between 'help and 'full?
413 @deffn {Scheme Procedure} eval-options [setting]
414 Display the current settings of the evaluator options. If @var{setting}
415 is omitted, only a short form of the current evaluator options is
416 printed. Otherwise, @var{setting} should be one of the following
420 Display the complete option settings.
422 Like @code{help}, but also print programmer options.
426 @deffn {Scheme Procedure} eval-enable option-name
427 @deffnx {Scheme Procedure} eval-disable option-name
428 @deffnx {Scheme Procedure} eval-set! option-name value
429 Modify the evaluator options. @code{eval-enable} should be used with boolean
430 options and switches them on, @code{eval-disable} switches them off.
431 @code{eval-set!} can be used to set an option to a specific value.
434 @deffn {Scheme Procedure} eval-options-interface [setting]
435 @deffnx {C Function} scm_eval_options_interface (setting)
436 Option interface for the evaluation options. Instead of using
437 this procedure directly, use the procedures @code{eval-enable},
438 @code{eval-disable}, @code{eval-set!} and @code{eval-options}.
441 @c FIXME::martin: Why aren't these procedure named like the other options
444 @deffn {Scheme Procedure} traps [setting]
445 Display the current settings of the evaluator traps options. If
446 @var{setting} is omitted, only a short form of the current evaluator
447 traps options is printed. Otherwise, @var{setting} should be one of the
451 Display the complete option settings.
453 Like @code{help}, but also print programmer options.
457 @deffn {Scheme Procedure} trap-enable option-name
458 @deffnx {Scheme Procedure} trap-disable option-name
459 @deffnx {Scheme Procedure} trap-set! option-name value
460 Modify the evaluator options. @code{trap-enable} should be used with boolean
461 options and switches them on, @code{trap-disable} switches them off.
462 @code{trap-set!} can be used to set an option to a specific value.
465 @deffn {Scheme Procedure} evaluator-traps-interface [setting]
466 @deffnx {C Function} scm_evaluator_traps (setting)
467 Option interface for the evaluator trap options.
472 @c TeX-master: "guile.texi"