2 @node Control Mechanisms
3 @chapter Controlling the Flow of Program Execution
6 * begin:: Evaluating a sequence of expressions.
7 * if cond case:: Simple conditional evaluation.
8 * and or:: Conditional evaluation of a sequence.
9 * while do:: Iteration mechanisms.
10 * Continuations:: Continuations.
11 * Multiple Values:: Returning and accepting multiple values.
12 * Exceptions:: Throwing and catching exceptions.
13 * Error Reporting:: Procedures for signaling errors.
14 * Dynamic Wind:: Guarding against non-local entrance/exit.
19 @section Evaluating a Sequence of Expressions
21 @c FIXME::martin: Review me!
23 @c FIXME::martin: Maybe add examples?
27 @cindex expression sequencing
29 @code{begin} is used for grouping several expression together so that
30 they syntactically are treated as if they were one expression. This is
31 particularly important when syntactic expressions are used which only
32 allow one expression, but the programmer wants to use more than one
33 expression in that place. As an example, consider the conditional
38 (begin (display "greater") (newline)))
41 If the two calls to @code{display} and @code{newline} were not embedded
42 in a @code{begin}--statement, the call to @code{newline} would get
43 misinterpreted as the else--branch of the @code{if}--expression.
45 @deffn syntax begin expr1 expr2 @dots{}
46 The expression(s) are evaluated in left--to--right order and the value
47 of the last expression is returned as the value of the
48 @code{begin}--expression. This expression type is used when the
49 expressions before the last one are evaluated for their side effects.
53 @section Simple Conditional Evaluation
55 @c FIXME::martin: Review me!
57 @c FIXME::martin: Maybe add examples?
59 @cindex conditional evaluation
64 Guile provides three syntactic constructs for conditional evaluation.
65 @code{if} is the normal if--then--else expression (with an optional else
66 branch), @code{cond} is a conditional expression with multiple branches
67 and @code{case} branches if an expression has one of a set of constant
70 @deffn syntax if test consequent [alternate]
71 All arguments may be arbitrary expressions. First, @var{test} is
72 evaluated. If it returns a true value, the expression @var{consequent}
73 is evaluated and @var{alternate} is ignoret. If @var{test} evaluates to
74 @code{#f}, @var{alternate} is evaluated instead. The value of the
75 evaluated branch (@var{consequent} or @var{alternate}) is returned as
76 the value of the @code{if} expression.
78 When @var{alternate} is omitted and the @var{test} evaluates to
79 @code{#f}, the value of the expression is not specified.
82 @deffn syntax cond clause1 clause2 @dots{}
83 Each @code{cond}-clause must look like this:
86 (@var{test} @var{expression} @dots{})
89 where @var{test} and @var{expression} are arbitrary expression, or like
93 (@var{test} => @var{expression}
96 where @var{expression} must evaluate to a procedure.
98 The @var{test}s of the clauses are evaluated in order and as soon as one
99 of them evaluates to a true values, the corresponding @var{expression}s
100 are evaluated in order and the last value is returned as the value of
101 the @code{cond}--expression. For the @code{=>} clause type,
102 @var{expression} is evaluated and the resulting procedure is applied to
103 the value of @var{test}. The result of this procedure application is
104 then the result of the @code{cond}--expression.
106 The @var{test} of the last @var{clause} may be the keyword @code{else}.
107 Then, if none of the preceding @var{test}s is true, the @var{expression}s following the @code{else} are evaluated to produce the result of the @code{cond}--expression.
110 @deffn syntax case key clause1 clause2 @dots{}
111 @var{key} may be any expression, the @var{clause}s must have the form
114 ((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
117 and the last @var{clause} may have the form
120 (else @var{expr1} @var{expr2} @dots{})
123 All @var{datum}s must be distinct. First, @var{key} is evaluated. The
124 the result of this evaluation is compared against all @var{datum}s using
125 @code{eqv?}. When this comparison succeeds, the epression(s) following
126 the @var{datum} are evaluated from left to right, returning the value of
127 the last expression as the result of the @code{case} expression.
129 If the @var{key} matches no @var{datum} and there is an
130 @code{else}--clause, the expressions following the @code{else} are
131 evaluated. If there is no such clause, the result of the expression is
137 @section Conditional Evaluation of a Sequence of Expressions
139 @c FIXME::martin: Review me!
141 @c FIXME::martin: Maybe add examples?
143 @code{and} and @code{or} evaluate all their arguments, similar to
144 @code{begin}, but evaluation stops as soon as one of the expressions
145 evaluates to false or true, respectively.
147 @deffn syntax and expr @dots{}
148 Evaluate the @var{expr}s from left to right and stop evaluation as soon
149 as one expression evaluates to @code{#f}; the remaining expressions are
150 not evaluated. The value of the last evaluated expression is returned.
151 If no expression evaluates to @code{#f}, the value of the last
152 expression is returned.
154 If used without expressions, @code{#t} is returned.
157 @deffn syntax or expr @dots{}
158 Evaluate the @var{expr}s from left to right and stop evaluation as soon
159 as one expression evaluates to a true value (that is, a value different
160 from @code{#f}); the remaining expressions are not evaluated. The value
161 of the last evaluated expression is returned. If all expressions
162 evaluate to @code{#f}, @code{#f} is returned.
164 If used without expressions, @code{#f} is returned.
169 @section Iteration mechanisms
171 @c FIXME::martin: Review me!
173 @c FIXME::martin: Maybe add examples?
178 Scheme has only few iteration mechanisms, mainly because iteration in
179 Scheme programs is normally expressed using recursion. Nevertheless,
180 R5RS defines a construct for programming loops, calling @code{do}. In
181 addition, Guile has an explicit looping syntax called @code{while}.
183 @deffn syntax do ((variable1 init1 step1) @dots{}) (test expr @dots{}) command @dots{}
184 The @var{init} expressions are evaluated and the @var{variables} are
185 bound to their values. Then looping starts with testing the @var{test}
186 expression. If @var{test} evaluates to a true value, the @var{expr}
187 following the @var{test} are evaluated and the value of the last
188 @var{expr} is returned as the value of the @code{do} expression. If
189 @var{test} evaluates to false, the @var{command}s are evaluated in
190 order, the @var{step}s are evaluated and stored into the @var{variables}
191 and the next iteration starts.
193 Any of the @var{step} expressions may be omitted, so that the
194 corresponding variable is not changed during looping.
197 @deffn syntax while cond body @dots{}
198 Evaluate all expressions in @var{body} in order, as long as @var{cond}
199 evaluates to a true value. The @var{cond} expression is tested before
200 every iteration, so that the body is not evaluated at all if @var{cond}
201 is @code{#f} right from the start.
206 @section Continuations
208 @rnindex call-with-current-continuation
209 @c FIXME::martin: Document me!
210 @deffn primitive call-with-current-continuation
213 @node Multiple Values
214 @section Returning and Accepting Multiple Values
216 @c FIXME::martin: Review me!
217 @cindex multiple values
220 Scheme allows a procedure to return more than one value to its caller.
221 This is quite different to other languages which only allow
222 single--value returns. Returning multiple values is different from
223 returning a list (or pair or vector) of values to the caller, because
224 conceptionally not @emph{one} compound object is returned, but several
227 The primitive procedures for handling multiple values are @code{values}
228 and @code{call-with-values}. @code{values} is used for returning
229 multiple values from a procedure. This is done by placing a call to
230 @code{values} with zero or more arguments in tail position in a
231 procedure body. @code{call-with-values} combines a procedure returning
232 multiple values with a procedure which accepts these values as
236 @deffn primitive values expr @dots{}
237 Delivers all of its arguments to its continuation. Except for
238 continuations created by the @code{call-with-values} procedure,
239 all continuations take exactly one value. The effect of
240 passing no value or more than one value to continuations that
241 were not created by @code{call-with-values} is unspecified.
244 @rnindex call-with-values
245 @deffn primitive call-with-values producer consumer
246 Calls its @var{producer} argument with no values and a
247 continuation that, when passed some values, calls the
248 @var{consumer} procedure with those values as arguments. The
249 continuation for the call to @var{consumer} is the continuation
250 of the call to @code{call-with-values}.
253 (call-with-values (lambda () (values 4 5))
259 (call-with-values * -) ==> -1
263 In addition to the fundamental procedures described above, Guile has a
264 module which exports a syntax called @code{receive}, which is much more
265 convenient. If you want to use it in your programs, you have to load
266 the module @code{(ice-9 receive)} with the statement
269 (use-modules (ice-9 receive))
272 @deffn {library syntax} receive formals expr body @dots{}
273 Evaluate the expression @var{expr}, and bind the result values (zero or
274 more) to the formal arguments in the formal argument list @var{formals}.
275 @var{formals} must have the same syntax like the formal argument list
276 used in @code{lambda} (@pxref{Lambda}). After binding the variables,
277 the expressions in @var{body} @dots{} are evaluated in order.
283 @cindex error handling
284 @cindex exception handling
286 It is traditional in Scheme to implement exception systems using
287 @code{call-with-current-continuation}. Guile does not do this, for
288 performance reasons. The implementation of
289 @code{call-with-current-continuation} is a stack copying implementation.
290 This allows it to interact well with ordinary C code. Unfortunately, a
291 stack-copying implementation can be slow -- creating a new continuation
292 involves a block copy of the stack.
294 Instead of using @code{call-with-current-continuation}, the exception
295 primitives documented here are implemented as built-ins that take
296 advantage of the @emph{upward only} nature of exceptions.
298 @deffn primitive catch key thunk handler
299 Invoke @var{thunk} in the dynamic context of @var{handler} for
300 exceptions matching @var{key}. If thunk throws to the symbol
301 @var{key}, then @var{handler} is invoked this way:
303 (handler key args ...)
305 @var{key} is a symbol or @code{#t}.
306 @var{thunk} takes no arguments. If @var{thunk} returns
307 normally, that is the return value of @code{catch}.
308 Handler is invoked outside the scope of its own @code{catch}.
309 If @var{handler} again throws to the same key, a new handler
310 from further up the call chain is invoked.
311 If the key is @code{#t}, then a throw to @emph{any} symbol will
312 match this call to @code{catch}.
315 @deffn primitive throw key . args
316 Invoke the catch form matching @var{key}, passing @var{args} to the
319 @var{key} is a symbol. It will match catches of the same symbol or of
322 If there is no handler at all, an error is signaled.
325 @deffn primitive lazy-catch key thunk handler
326 This behaves exactly like @code{catch}, except that it does
327 not unwind the stack (this is the major difference), and if
328 handler returns, its value is returned from the throw.
332 @node Error Reporting
333 @section Procedures for Signaling Errors
335 Guile provides a set of convenience procedures for signaling error
336 conditions that are implemented on top of the exception primitives just
339 @c begin (scm-doc-string "boot-9.scm" "error")
340 @deffn procedure error msg args @dots{}
341 Raise an error with key @code{misc-error} and a message constructed by
342 displaying @var{msg} and writing @var{args}.
346 @deffn primitive scm-error key subr message args data
347 Raise an error with key @var{key}. @var{subr} can be a string
348 naming the procedure associated with the error, or @code{#f}.
349 @var{message} is the error message string, possibly containing
350 @code{~S} and @code{~A} escapes. When an error is reported,
351 these are replaced by formatting the corresponding members of
352 @var{args}: @code{~A} (was @code{%s} in older versions of
353 Guile) formats using @code{display} and @code{~S} (was
354 @code{%S}) formats using @code{write}. @var{data} is a list or
355 @code{#f} depending on @var{key}: if @var{key} is
356 @code{system-error} then it should be a list containing the
357 Unix @code{errno} value; If @var{key} is @code{signal} then it
358 should be a list containing the Unix signal number; otherwise
359 it will usually be @code{#f}.
362 @deffn primitive strerror err
363 Return the Unix error message corresponding to @var{err}, which
364 must be an integer value.
367 @c begin (scm-doc-string "boot-9.scm" "false-if-exception")
368 @deffn syntax false-if-exception expr
369 Returns the result of evaluating its argument; however
370 if an exception occurs then @code{#f} is returned instead.
376 @section Dynamic Wind
378 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
381 @rnindex dynamic-wind
382 @deffn primitive dynamic-wind in_guard thunk out_guard
383 All three arguments must be 0-argument procedures.
384 @var{in_guard} is called, then @var{thunk}, then
386 If, any time during the execution of @var{thunk}, the
387 continuation of the @code{dynamic_wind} expression is escaped
388 non-locally, @var{out_guard} is called. If the continuation of
389 the dynamic-wind is re-entered, @var{in_guard} is called. Thus
390 @var{in_guard} and @var{out_guard} may be called any number of
393 (define x 'normal-binding)
395 (define a-cont (call-with-current-continuation
401 (lambda () (set! x 'special-binding))
404 (lambda () (display x) (newline)
405 (call-with-current-continuation escape)
406 (display x) (newline)
410 (lambda () (set! x old-x)))))))
416 @result{} normal-binding
421 @result{} a-cont ;; the value of the (define a-cont...)
423 @result{} normal-binding
425 @result{} special-binding
429 @c TeX-master: "guile.texi"