2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Control Mechanisms
8 @section Controlling the Flow of Program Execution
10 See @ref{Control Flow} for a discussion of how the more general control
11 flow of Scheme affects C code.
14 * begin:: Evaluating a sequence of expressions.
15 * if cond case:: Simple conditional evaluation.
16 * and or:: Conditional evaluation of a sequence.
17 * while do:: Iteration mechanisms.
18 * Prompts:: Composable, delimited continuations.
19 * Continuations:: Non-composable continuations.
20 * Multiple Values:: Returning and accepting multiple values.
21 * Exceptions:: Throwing and catching exceptions.
22 * Error Reporting:: Procedures for signaling errors.
23 * Dynamic Wind:: Dealing with non-local entrance/exit.
24 * Handling Errors:: How to handle errors in C code.
25 * Continuation Barriers:: Protection from non-local control flow.
29 @subsection Evaluating a Sequence of Expressions
33 @cindex expression sequencing
35 The @code{begin} syntax is used for grouping several expressions
36 together so that they are treated as if they were one expression.
37 This is particularly important when syntactic expressions are used
38 which only allow one expression, but the programmer wants to use more
39 than one expression in that place. As an example, consider the
40 conditional expression below:
44 (begin (display "greater") (newline)))
47 If the two calls to @code{display} and @code{newline} were not embedded
48 in a @code{begin}-statement, the call to @code{newline} would get
49 misinterpreted as the else-branch of the @code{if}-expression.
51 @deffn syntax begin expr1 expr2 @dots{}
52 The expression(s) are evaluated in left-to-right order and the value
53 of the last expression is returned as the value of the
54 @code{begin}-expression. This expression type is used when the
55 expressions before the last one are evaluated for their side effects.
57 Guile also allows the expression @code{(begin)}, a @code{begin} with no
58 sub-expressions. Such an expression returns the `unspecified' value.
62 @subsection Simple Conditional Evaluation
64 @cindex conditional evaluation
69 Guile provides three syntactic constructs for conditional evaluation.
70 @code{if} is the normal if-then-else expression (with an optional else
71 branch), @code{cond} is a conditional expression with multiple branches
72 and @code{case} branches if an expression has one of a set of constant
75 @deffn syntax if test consequent [alternate]
76 All arguments may be arbitrary expressions. First, @var{test} is
77 evaluated. If it returns a true value, the expression @var{consequent}
78 is evaluated and @var{alternate} is ignored. If @var{test} evaluates to
79 @code{#f}, @var{alternate} is evaluated instead. The value of the
80 evaluated branch (@var{consequent} or @var{alternate}) is returned as
81 the value of the @code{if} expression.
83 When @var{alternate} is omitted and the @var{test} evaluates to
84 @code{#f}, the value of the expression is not specified.
87 @deffn syntax cond clause1 clause2 @dots{}
88 Each @code{cond}-clause must look like this:
91 (@var{test} @var{expression} @dots{})
94 where @var{test} and @var{expression} are arbitrary expression, or like
98 (@var{test} => @var{expression})
101 where @var{expression} must evaluate to a procedure.
103 The @var{test}s of the clauses are evaluated in order and as soon as one
104 of them evaluates to a true values, the corresponding @var{expression}s
105 are evaluated in order and the last value is returned as the value of
106 the @code{cond}-expression. For the @code{=>} clause type,
107 @var{expression} is evaluated and the resulting procedure is applied to
108 the value of @var{test}. The result of this procedure application is
109 then the result of the @code{cond}-expression.
112 @cindex general cond clause
113 @cindex multiple values and cond
114 One additional @code{cond}-clause is available as an extension to
118 (@var{test} @var{guard} => @var{expression})
121 where @var{guard} and @var{expression} must evaluate to procedures.
122 For this clause type, @var{test} may return multiple values, and
123 @code{cond} ignores its boolean state; instead, @code{cond} evaluates
124 @var{guard} and applies the resulting procedure to the value(s) of
125 @var{test}, as if @var{guard} were the @var{consumer} argument of
126 @code{call-with-values}. Iff the result of that procedure call is a
127 true value, it evaluates @var{expression} and applies the resulting
128 procedure to the value(s) of @var{test}, in the same manner as the
129 @var{guard} was called.
131 The @var{test} of the last @var{clause} may be the symbol @code{else}.
132 Then, if none of the preceding @var{test}s is true, the
133 @var{expression}s following the @code{else} are evaluated to produce the
134 result of the @code{cond}-expression.
137 @deffn syntax case key clause1 clause2 @dots{}
138 @var{key} may be any expression, the @var{clause}s must have the form
141 ((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
144 and the last @var{clause} may have the form
147 (else @var{expr1} @var{expr2} @dots{})
150 All @var{datum}s must be distinct. First, @var{key} is evaluated. The
151 result of this evaluation is compared against all @var{datum} values using
152 @code{eqv?}. When this comparison succeeds, the expression(s) following
153 the @var{datum} are evaluated from left to right, returning the value of
154 the last expression as the result of the @code{case} expression.
156 If the @var{key} matches no @var{datum} and there is an
157 @code{else}-clause, the expressions following the @code{else} are
158 evaluated. If there is no such clause, the result of the expression is
164 @subsection Conditional Evaluation of a Sequence of Expressions
166 @code{and} and @code{or} evaluate all their arguments in order, similar
167 to @code{begin}, but evaluation stops as soon as one of the expressions
168 evaluates to false or true, respectively.
170 @deffn syntax and expr @dots{}
171 Evaluate the @var{expr}s from left to right and stop evaluation as soon
172 as one expression evaluates to @code{#f}; the remaining expressions are
173 not evaluated. The value of the last evaluated expression is returned.
174 If no expression evaluates to @code{#f}, the value of the last
175 expression is returned.
177 If used without expressions, @code{#t} is returned.
180 @deffn syntax or expr @dots{}
181 Evaluate the @var{expr}s from left to right and stop evaluation as soon
182 as one expression evaluates to a true value (that is, a value different
183 from @code{#f}); the remaining expressions are not evaluated. The value
184 of the last evaluated expression is returned. If all expressions
185 evaluate to @code{#f}, @code{#f} is returned.
187 If used without expressions, @code{#f} is returned.
192 @subsection Iteration mechanisms
198 Scheme has only few iteration mechanisms, mainly because iteration in
199 Scheme programs is normally expressed using recursion. Nevertheless,
200 R5RS defines a construct for programming loops, calling @code{do}. In
201 addition, Guile has an explicit looping syntax called @code{while}.
203 @deffn syntax do ((variable init [step]) @dots{}) (test [expr @dots{}]) body @dots{}
204 Bind @var{variable}s and evaluate @var{body} until @var{test} is true.
205 The return value is the last @var{expr} after @var{test}, if given. A
206 simple example will illustrate the basic form,
216 Or with two variables and a final return value,
223 (format #t "3**~s is ~s\n" i p))
233 The @var{variable} bindings are established like a @code{let}, in that
234 the expressions are all evaluated and then all bindings made. When
235 iterating, the optional @var{step} expressions are evaluated with the
236 previous bindings in scope, then new bindings all made.
238 The @var{test} expression is a termination condition. Looping stops
239 when the @var{test} is true. It's evaluated before running the
240 @var{body} each time, so if it's true the first time then @var{body}
243 The optional @var{expr}s after the @var{test} are evaluated at the end
244 of looping, with the final @var{variable} bindings available. The
245 last @var{expr} gives the return value, or if there are no @var{expr}s
246 the return value is unspecified.
248 Each iteration establishes bindings to fresh locations for the
249 @var{variable}s, like a new @code{let} for each iteration. This is
250 done for @var{variable}s without @var{step} expressions too. The
251 following illustrates this, showing how a new @code{i} is captured by
252 the @code{lambda} in each iteration (@pxref{About Closure,, The
253 Concept of Closure}).
259 (set! lst (cons (lambda () i) lst)))
260 (map (lambda (proc) (proc)) lst)
266 @deffn syntax while cond body @dots{}
267 Run a loop executing the @var{body} forms while @var{cond} is true.
268 @var{cond} is tested at the start of each iteration, so if it's
269 @code{#f} the first time then @var{body} is not executed at all.
271 Within @code{while}, two extra bindings are provided, they can be used
272 from both @var{cond} and @var{body}.
274 @deffn {Scheme Procedure} break break-arg...
275 Break out of the @code{while} form.
278 @deffn {Scheme Procedure} continue
279 Abandon the current iteration, go back to the start and test
280 @var{cond} again, etc.
283 If the loop terminates normally, by the @var{cond} evaluating to
284 @code{#f}, then the @code{while} expression as a whole evaluates to
285 @code{#f}. If it terminates by a call to @code{break} with some number
286 of arguments, those arguments are returned from the @code{while}
287 expression, as multiple values. Otherwise if it terminates by a call to
288 @code{break} with no arguments, then return value is @code{#t}.
291 (while #f (error "not reached")) @result{} #f
292 (while #t (break)) @result{} #t
293 (while #t (break 1 2 3)) @result{} 1 2 3
296 Each @code{while} form gets its own @code{break} and @code{continue}
297 procedures, operating on that @code{while}. This means when loops are
298 nested the outer @code{break} can be used to escape all the way out.
303 (let ((outer-break break))
310 Note that each @code{break} and @code{continue} procedure can only be
311 used within the dynamic extent of its @code{while}. Outside the
312 @code{while} their behaviour is unspecified.
316 Another very common way of expressing iteration in Scheme programs is
317 the use of the so-called @dfn{named let}.
319 Named let is a variant of @code{let} which creates a procedure and calls
320 it in one step. Because of the newly created procedure, named let is
321 more powerful than @code{do}--it can be used for iteration, but also
322 for arbitrary recursion.
324 @deffn syntax let variable bindings body
325 For the definition of @var{bindings} see the documentation about
326 @code{let} (@pxref{Local Bindings}).
328 Named @code{let} works as follows:
332 A new procedure which accepts as many arguments as are in @var{bindings}
333 is created and bound locally (using @code{let}) to @var{variable}. The
334 new procedure's formal argument names are the name of the
338 The @var{body} expressions are inserted into the newly created procedure.
341 The procedure is called with the @var{init} expressions as the formal
345 The next example implements a loop which iterates (by recursion) 1000
362 @cindex delimited continuations
363 @cindex composable continuations
364 @cindex non-local exit
366 Prompts are control-flow barriers between different parts of a program. In the
367 same way that a user sees a shell prompt (e.g., the Bash prompt) as a barrier
368 between the operating system and her programs, Scheme prompts allow the Scheme
369 programmer to treat parts of programs as if they were running in different
372 We use this roundabout explanation because, unless you're a functional
373 programming junkie, you probably haven't heard the term, ``delimited, composable
374 continuation''. That's OK; it's a relatively recent topic, but a very useful
378 * Prompt Primitives:: Call-with-prompt and abort-to-prompt.
379 * Shift and Reset:: The zoo of delimited control operators.
382 @node Prompt Primitives
383 @subsubsection Prompt Primitives
385 Guile's primitive delimited control operators are
386 @code{call-with-prompt} and @code{abort-to-prompt}.
388 @deffn {Scheme Procedure} call-with-prompt tag thunk handler
389 Set up a prompt, and call @var{thunk} within that prompt.
391 During the dynamic extent of the call to @var{thunk}, a prompt named @var{tag}
392 will be present in the dynamic context, such that if a user calls
393 @code{abort-to-prompt} (see below) with that tag, control rewinds back to the
394 prompt, and the @var{handler} is run.
396 @var{handler} must be a procedure. The first argument to @var{handler} will be
397 the state of the computation begun when @var{thunk} was called, and ending with
398 the call to @code{abort-to-prompt}. The remaining arguments to @var{handler} are
399 those passed to @code{abort-to-prompt}.
402 @deffn {Scheme Procedure} make-prompt-tag [stem]
403 Make a new prompt tag. Currently prompt tags are generated symbols.
404 This may change in some future Guile version.
407 @deffn {Scheme Procedure} default-prompt-tag
408 Return the default prompt tag. Having a distinguished default prompt
409 tag allows some useful prompt and abort idioms, discussed in the next
413 @deffn {Scheme Procedure} abort-to-prompt tag val ...
414 Unwind the dynamic and control context to the nearest prompt named @var{tag},
415 also passing the given values.
418 C programmers may recognize @code{call-with-prompt} and @code{abort-to-prompt}
419 as a fancy kind of @code{setjmp} and @code{longjmp}, respectively. Prompts are
420 indeed quite useful as non-local escape mechanisms. Guile's @code{catch} and
421 @code{throw} are implemented in terms of prompts. Prompts are more convenient
422 than @code{longjmp}, in that one has the opportunity to pass multiple values to
425 Also unlike @code{longjmp}, the prompt handler is given the full state of the
426 process that was aborted, as the first argument to the prompt's handler. That
427 state is the @dfn{continuation} of the computation wrapped by the prompt. It is
428 a @dfn{delimited continuation}, because it is not the whole continuation of the
429 program; rather, just the computation initiated by the call to
430 @code{call-with-prompt}.
432 The continuation is a procedure, and may be reinstated simply by invoking it,
433 with any number of values. Here's where things get interesting, and complicated
434 as well. Besides being described as delimited, continuations reified by prompts
435 are also @dfn{composable}, because invoking a prompt-saved continuation composes
436 that continuation with the current one.
438 Imagine you have saved a continuation via call-with-prompt:
447 (+ 34 (abort-to-prompt 'foo)))
452 The resulting continuation is the addition of 34. It's as if you had written:
460 So, if we call @code{cont} with one numeric value, we get that number,
470 The last example illustrates what we mean when we say, "composes with the
471 current continuation". We mean that there is a current continuation -- some
472 remaining things to compute, like @code{(lambda (x) (* x 2))} -- and that
473 calling the saved continuation doesn't wipe out the current continuation, it
474 composes the saved continuation with the current one.
476 We're belaboring the point here because traditional Scheme continuations, as
477 discussed in the next section, aren't composable, and are actually less
478 expressive than continuations captured by prompts. But there's a place for them
481 Before moving on, we should mention that if the handler of a prompt is a
482 @code{lambda} expression, and the first argument isn't referenced, an abort to
483 that prompt will not cause a continuation to be reified. This can be an
484 important efficiency consideration to keep in mind.
486 @node Shift and Reset
487 @subsubsection Shift, Reset, and All That
489 There is a whole zoo of delimited control operators, and as it does not
490 seem to be a bounded set, Guile implements support for them in a
494 (use-modules (ice-9 control))
497 Firstly, we have a helpful abbreviation for the @code{call-with-prompt}
500 @deffn {Scheme Syntax} % expr
501 @deffnx {Scheme Syntax} % expr handler
502 @deffnx {Scheme Syntax} % tag expr handler
503 Evaluate @var{expr} in a prompt, optionally specifying a tag and a
504 handler. If no tag is given, the default prompt tag is used.
506 If no handler is given, a default handler is installed. The default
507 handler accepts a procedure of one argument, which will called on the
508 captured continuation, within a prompt.
510 Sometimes it's easier just to show code, as in this case:
513 (define (default-prompt-handler k proc)
514 (% (default-prompt-tag)
516 default-prompt-handler))
519 The @code{%} symbol is chosen because it looks like a prompt.
522 Likewise there is an abbreviation for @code{abort-to-prompt}, which
523 assumes the default prompt tag:
525 @deffn {Scheme Procedure} abort val...
526 Abort to the default prompt tag, passing @var{val...} to the handler.
529 As mentioned before, @code{(ice-9 control)} also provides other
530 delimited control operators. This section is a bit technical, and
531 first-time users of delimited continuations should probably come back to
532 it after some practice with @code{%}.
534 Still here? So, when one implements a delimited control operator like
535 @code{call-with-prompt}, one needs to make two decisions. Firstly, does
536 the handler run within or outside the prompt? Having the handler run
537 within the prompt allows an abort inside the handler to return to the
538 same prompt handler, which is often useful. However it prevents tail
539 calls from the handler, so it is less general.
541 Similarly, does invoking a captured continuation reinstate a prompt?
542 Again we have the tradeoff of convenience versus proper tail calls.
544 These decisions are captured in the Felleisen @dfn{F} operator. If
545 neither the continuations nor the handlers implicitly add a prompt, the
546 operator is known as @dfn{--F--}. This is the case for Guile's
547 @code{call-with-prompt} and @code{abort-to-prompt}.
549 If both continuation and handler implicitly add prompts, then the
550 operator is @dfn{+F+}. @code{shift} and @code{reset} are such
553 @deffn {Scheme Syntax} reset body...
554 Establish a prompt, and evaluate @var{body...} within that prompt.
556 The prompt handler is designed to work with @code{shift}, described
560 @deffn {Scheme Syntax} shift cont body...
561 Abort to the nearest @code{reset}, and evaluate @var{body...} in a
562 context in which the captured continuation is bound to @var{cont}.
564 As mentioned above, both the @var{body...} expression and invocations of
565 @var{cont} implicitly establish a prompt.
568 Interested readers are invited to explore Oleg Kiselyov's wonderful web
569 site at @uref{http://okmij.org/ftp/}, for more information on these
574 @subsection Continuations
575 @cindex continuations
577 A ``continuation'' is the code that will execute when a given function
578 or expression returns. For example, consider
583 (display (bar)) (newline)
587 The continuation from the call to @code{bar} comprises a
588 @code{display} of the value returned, a @code{newline} and an
589 @code{exit}. This can be expressed as a function of one argument.
593 (display r) (newline)
597 In Scheme, continuations are represented as special procedures just
598 like this. The special property is that when a continuation is called
599 it abandons the current program location and jumps directly to that
600 represented by the continuation.
602 A continuation is like a dynamic label, capturing at run-time a point
603 in program execution, including all the nested calls that have lead to
604 it (or rather the code that will execute when those calls return).
606 Continuations are created with the following functions.
608 @deffn {Scheme Procedure} call-with-current-continuation proc
609 @deffnx {Scheme Procedure} call/cc proc
610 @rnindex call-with-current-continuation
611 Capture the current continuation and call @code{(@var{proc}
612 @var{cont})} with it. The return value is the value returned by
613 @var{proc}, or when @code{(@var{cont} @var{value})} is later invoked,
614 the return is the @var{value} passed.
616 Normally @var{cont} should be called with one argument, but when the
617 location resumed is expecting multiple values (@pxref{Multiple
618 Values}) then they should be passed as multiple arguments, for
619 instance @code{(@var{cont} @var{x} @var{y} @var{z})}.
621 @var{cont} may only be used from the same side of a continuation
622 barrier as it was created (@pxref{Continuation Barriers}), and in a
623 multi-threaded program only from the thread in which it was created.
625 The call to @var{proc} is not part of the continuation captured, it runs
626 only when the continuation is created. Often a program will want to
627 store @var{cont} somewhere for later use; this can be done in
630 The @code{call} in the name @code{call-with-current-continuation}
631 refers to the way a call to @var{proc} gives the newly created
632 continuation. It's not related to the way a call is used later to
633 invoke that continuation.
635 @code{call/cc} is an alias for @code{call-with-current-continuation}.
636 This is in common use since the latter is rather long.
641 Here is a simple example,
645 (format #t "the return is ~a\n"
649 @result{} the return is 1
652 @result{} the return is 2
655 @code{call/cc} captures a continuation in which the value returned is
656 going to be displayed by @code{format}. The @code{lambda} stores this
657 in @code{kont} and gives an initial return @code{1} which is
658 displayed. The later invocation of @code{kont} resumes the captured
659 point, but this time returning @code{2}, which is displayed.
661 When Guile is run interactively, a call to @code{format} like this has
662 an implicit return back to the read-eval-print loop. @code{call/cc}
663 captures that like any other return, which is why interactively
664 @code{kont} will come back to read more input.
667 C programmers may note that @code{call/cc} is like @code{setjmp} in
668 the way it records at runtime a point in program execution. A call to
669 a continuation is like a @code{longjmp} in that it abandons the
670 present location and goes to the recorded one. Like @code{longjmp},
671 the value passed to the continuation is the value returned by
672 @code{call/cc} on resuming there. However @code{longjmp} can only go
673 up the program stack, but the continuation mechanism can go anywhere.
675 When a continuation is invoked, @code{call/cc} and subsequent code
676 effectively ``returns'' a second time. It can be confusing to imagine
677 a function returning more times than it was called. It may help
678 instead to think of it being stealthily re-entered and then program
679 flow going on as normal.
681 @code{dynamic-wind} (@pxref{Dynamic Wind}) can be used to ensure setup
682 and cleanup code is run when a program locus is resumed or abandoned
683 through the continuation mechanism.
686 Continuations are a powerful mechanism, and can be used to implement
687 almost any sort of control structure, such as loops, coroutines, or
690 However the implementation of continuations in Guile is not as
691 efficient as one might hope, because Guile is designed to cooperate
692 with programs written in other languages, such as C, which do not know
693 about continuations. Basically continuations are captured by a block
694 copy of the stack, and resumed by copying back.
696 For this reason, continuations captured by @code{call/cc} should be used only
697 when there is no other simple way to achieve the desired result, or when the
698 elegance of the continuation mechanism outweighs the need for performance.
700 Escapes upwards from loops or nested functions are generally best
701 handled with prompts (@pxref{Prompts}). Coroutines can be
702 efficiently implemented with cooperating threads (a thread holds a
703 full program stack but doesn't copy it around the way continuations
707 @node Multiple Values
708 @subsection Returning and Accepting Multiple Values
710 @cindex multiple values
713 Scheme allows a procedure to return more than one value to its caller.
714 This is quite different to other languages which only allow
715 single-value returns. Returning multiple values is different from
716 returning a list (or pair or vector) of values to the caller, because
717 conceptually not @emph{one} compound object is returned, but several
720 The primitive procedures for handling multiple values are @code{values}
721 and @code{call-with-values}. @code{values} is used for returning
722 multiple values from a procedure. This is done by placing a call to
723 @code{values} with zero or more arguments in tail position in a
724 procedure body. @code{call-with-values} combines a procedure returning
725 multiple values with a procedure which accepts these values as
729 @deffn {Scheme Procedure} values arg1 @dots{} argN
730 @deffnx {C Function} scm_values (args)
731 Delivers all of its arguments to its continuation. Except for
732 continuations created by the @code{call-with-values} procedure,
733 all continuations take exactly one value. The effect of
734 passing no value or more than one value to continuations that
735 were not created by @code{call-with-values} is unspecified.
737 For @code{scm_values}, @var{args} is a list of arguments and the
738 return is a multiple-values object which the caller can return. In
739 the current implementation that object shares structure with
740 @var{args}, so @var{args} should not be modified subsequently.
743 @rnindex call-with-values
744 @deffn {Scheme Procedure} call-with-values producer consumer
745 Calls its @var{producer} argument with no values and a
746 continuation that, when passed some values, calls the
747 @var{consumer} procedure with those values as arguments. The
748 continuation for the call to @var{consumer} is the continuation
749 of the call to @code{call-with-values}.
752 (call-with-values (lambda () (values 4 5))
758 (call-with-values * -)
763 In addition to the fundamental procedures described above, Guile has a
764 module which exports a syntax called @code{receive}, which is much
765 more convenient. This is in the @code{(ice-9 receive)} and is the
766 same as specified by SRFI-8 (@pxref{SRFI-8}).
769 (use-modules (ice-9 receive))
772 @deffn {library syntax} receive formals expr body @dots{}
773 Evaluate the expression @var{expr}, and bind the result values (zero
774 or more) to the formal arguments in @var{formals}. @var{formals} is a
775 list of symbols, like the argument list in a @code{lambda}
776 (@pxref{Lambda}). After binding the variables, the expressions in
777 @var{body} @dots{} are evaluated in order, the return value is the
778 result from the last expression.
780 For example getting results from @code{partition} in SRFI-1
784 (receive (odds evens)
785 (partition odd? '(7 4 2 8 3))
789 @print{} (7 3) and (4 2 8)
796 @subsection Exceptions
797 @cindex error handling
798 @cindex exception handling
800 A common requirement in applications is to want to jump
801 @dfn{non-locally} from the depths of a computation back to, say, the
802 application's main processing loop. Usually, the place that is the
803 target of the jump is somewhere in the calling stack of procedures that
804 called the procedure that wants to jump back. For example, typical
805 logic for a key press driven application might look something like this:
809 read the next key press and call dispatch-key
812 lookup the key in a keymap and call an appropriate procedure,
816 interactively read the required file name, then call
820 check whether file exists; if not, jump back to main-loop
824 The jump back to @code{main-loop} could be achieved by returning through
825 the stack one procedure at a time, using the return value of each
826 procedure to indicate the error condition, but Guile (like most modern
827 programming languages) provides an additional mechanism called
828 @dfn{exception handling} that can be used to implement such jumps much
832 * Exception Terminology:: Different ways to say the same thing.
833 * Catch:: Setting up to catch exceptions.
834 * Throw Handlers:: Handling exceptions before unwinding the stack.
835 * Throw:: Throwing an exception.
836 * Exception Implementation:: How Guile implements exceptions.
840 @node Exception Terminology
841 @subsubsection Exception Terminology
843 There are several variations on the terminology for dealing with
844 non-local jumps. It is useful to be aware of them, and to realize
845 that they all refer to the same basic mechanism.
849 Actually making a non-local jump may be called @dfn{raising an
850 exception}, @dfn{raising a signal}, @dfn{throwing an exception} or
851 @dfn{doing a long jump}. When the jump indicates an error condition,
852 people may talk about @dfn{signalling}, @dfn{raising} or @dfn{throwing}
856 Handling the jump at its target may be referred to as @dfn{catching} or
857 @dfn{handling} the @dfn{exception}, @dfn{signal} or, where an error
858 condition is involved, @dfn{error}.
861 Where @dfn{signal} and @dfn{signalling} are used, special care is needed
862 to avoid the risk of confusion with POSIX signals.
864 This manual prefers to speak of throwing and catching exceptions, since
865 this terminology matches the corresponding Guile primitives.
869 @subsubsection Catching Exceptions
871 @code{catch} is used to set up a target for a possible non-local jump.
872 The arguments of a @code{catch} expression are a @dfn{key}, which
873 restricts the set of exceptions to which this @code{catch} applies, a
874 thunk that specifies the code to execute and one or two @dfn{handler}
875 procedures that say what to do if an exception is thrown while executing
876 the code. If the execution thunk executes @dfn{normally}, which means
877 without throwing any exceptions, the handler procedures are not called
880 When an exception is thrown using the @code{throw} function, the first
881 argument of the @code{throw} is a symbol that indicates the type of the
882 exception. For example, Guile throws an exception using the symbol
883 @code{numerical-overflow} to indicate numerical overflow errors such as
889 ABORT: (numerical-overflow)
892 The @var{key} argument in a @code{catch} expression corresponds to this
893 symbol. @var{key} may be a specific symbol, such as
894 @code{numerical-overflow}, in which case the @code{catch} applies
895 specifically to exceptions of that type; or it may be @code{#t}, which
896 means that the @code{catch} applies to all exceptions, irrespective of
899 The second argument of a @code{catch} expression should be a thunk
900 (i.e.@: a procedure that accepts no arguments) that specifies the normal
901 case code. The @code{catch} is active for the execution of this thunk,
902 including any code called directly or indirectly by the thunk's body.
903 Evaluation of the @code{catch} expression activates the catch and then
906 The third argument of a @code{catch} expression is a handler procedure.
907 If an exception is thrown, this procedure is called with exactly the
908 arguments specified by the @code{throw}. Therefore, the handler
909 procedure must be designed to accept a number of arguments that
910 corresponds to the number of arguments in all @code{throw} expressions
911 that can be caught by this @code{catch}.
913 The fourth, optional argument of a @code{catch} expression is another
914 handler procedure, called the @dfn{pre-unwind} handler. It differs from
915 the third argument in that if an exception is thrown, it is called,
916 @emph{before} the third argument handler, in exactly the dynamic context
917 of the @code{throw} expression that threw the exception. This means
918 that it is useful for capturing or displaying the stack at the point of
919 the @code{throw}, or for examining other aspects of the dynamic context,
920 such as fluid values, before the context is unwound back to that of the
921 prevailing @code{catch}.
923 @deffn {Scheme Procedure} catch key thunk handler [pre-unwind-handler]
924 @deffnx {C Function} scm_catch_with_pre_unwind_handler (key, thunk, handler, pre_unwind_handler)
925 @deffnx {C Function} scm_catch (key, thunk, handler)
926 Invoke @var{thunk} in the dynamic context of @var{handler} for
927 exceptions matching @var{key}. If thunk throws to the symbol
928 @var{key}, then @var{handler} is invoked this way:
930 (handler key args ...)
933 @var{key} is a symbol or @code{#t}.
935 @var{thunk} takes no arguments. If @var{thunk} returns
936 normally, that is the return value of @code{catch}.
938 Handler is invoked outside the scope of its own @code{catch}.
939 If @var{handler} again throws to the same key, a new handler
940 from further up the call chain is invoked.
942 If the key is @code{#t}, then a throw to @emph{any} symbol will
943 match this call to @code{catch}.
945 If a @var{pre-unwind-handler} is given and @var{thunk} throws
946 an exception that matches @var{key}, Guile calls the
947 @var{pre-unwind-handler} before unwinding the dynamic state and
948 invoking the main @var{handler}. @var{pre-unwind-handler} should
949 be a procedure with the same signature as @var{handler}, that
950 is @code{(lambda (key . args))}. It is typically used to save
951 the stack at the point where the exception occurred, but can also
952 query other parts of the dynamic state at that point, such as
955 A @var{pre-unwind-handler} can exit either normally or non-locally.
956 If it exits normally, Guile unwinds the stack and dynamic context
957 and then calls the normal (third argument) handler. If it exits
958 non-locally, that exit determines the continuation.
961 If a handler procedure needs to match a variety of @code{throw}
962 expressions with varying numbers of arguments, you should write it like
971 The @var{key} argument is guaranteed always to be present, because a
972 @code{throw} without a @var{key} is not valid. The number and
973 interpretation of the @var{args} varies from one type of exception to
974 another, but should be specified by the documentation for each exception
977 Note that, once the normal (post-unwind) handler procedure is invoked,
978 the catch that led to the handler procedure being called is no longer
979 active. Therefore, if the handler procedure itself throws an exception,
980 that exception can only be caught by another active catch higher up the
981 call stack, if there is one.
984 @deftypefn {C Function} SCM scm_c_catch (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data, scm_t_catch_handler pre_unwind_handler, void *pre_unwind_handler_data)
985 @deftypefnx {C Function} SCM scm_internal_catch (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)
986 The above @code{scm_catch_with_pre_unwind_handler} and @code{scm_catch}
987 take Scheme procedures as body and handler arguments.
988 @code{scm_c_catch} and @code{scm_internal_catch} are equivalents taking
991 @var{body} is called as @code{@var{body} (@var{body_data})} with a catch
992 on exceptions of the given @var{tag} type. If an exception is caught,
993 @var{pre_unwind_handler} and @var{handler} are called as
994 @code{@var{handler} (@var{handler_data}, @var{key}, @var{args})}.
995 @var{key} and @var{args} are the @code{SCM} key and argument list from
998 @tpindex scm_t_catch_body
999 @tpindex scm_t_catch_handler
1000 @var{body} and @var{handler} should have the following prototypes.
1001 @code{scm_t_catch_body} and @code{scm_t_catch_handler} are pointer
1005 SCM body (void *data);
1006 SCM handler (void *data, SCM key, SCM args);
1009 The @var{body_data} and @var{handler_data} parameters are passed to
1010 the respective calls so an application can communicate extra
1011 information to those functions.
1013 If the data consists of an @code{SCM} object, care should be taken
1014 that it isn't garbage collected while still required. If the
1015 @code{SCM} is a local C variable, one way to protect it is to pass a
1016 pointer to that variable as the data parameter, since the C compiler
1017 will then know the value must be held on the stack. Another way is to
1018 use @code{scm_remember_upto_here_1} (@pxref{Remembering During
1023 @node Throw Handlers
1024 @subsubsection Throw Handlers
1026 It's sometimes useful to be able to intercept an exception that is being
1027 thrown before the stack is unwound. This could be to clean up some
1028 related state, to print a backtrace, or to pass information about the
1029 exception to a debugger, for example. The @code{with-throw-handler}
1030 procedure provides a way to do this.
1032 @deffn {Scheme Procedure} with-throw-handler key thunk handler
1033 @deffnx {C Function} scm_with_throw_handler (key, thunk, handler)
1034 Add @var{handler} to the dynamic context as a throw handler
1035 for key @var{key}, then invoke @var{thunk}.
1037 This behaves exactly like @code{catch}, except that it does not unwind
1038 the stack before invoking @var{handler}. If the @var{handler} procedure
1039 returns normally, Guile rethrows the same exception again to the next
1040 innermost catch or throw handler. @var{handler} may exit nonlocally, of
1041 course, via an explicit throw or via invoking a continuation.
1044 Typically @var{handler} is used to display a backtrace of the stack at
1045 the point where the corresponding @code{throw} occurred, or to save off
1046 this information for possible display later.
1048 Not unwinding the stack means that throwing an exception that is handled
1049 via a throw handler is equivalent to calling the throw handler handler
1050 inline instead of each @code{throw}, and then omitting the surrounding
1051 @code{with-throw-handler}. In other words,
1054 (with-throw-handler 'key
1055 (lambda () @dots{} (throw 'key args @dots{}) @dots{})
1060 is mostly equivalent to
1063 ((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
1066 In particular, the dynamic context when @var{handler} is invoked is that
1067 of the site where @code{throw} is called. The examples are not quite
1068 equivalent, because the body of a @code{with-throw-handler} is not in
1069 tail position with respect to the @code{with-throw-handler}, and if
1070 @var{handler} exits normally, Guile arranges to rethrow the error, but
1071 hopefully the intention is clear. (For an introduction to what is meant
1072 by dynamic context, @xref{Dynamic Wind}.)
1074 @deftypefn {C Function} SCM scm_c_with_throw_handler (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data, int lazy_catch_p)
1075 The above @code{scm_with_throw_handler} takes Scheme procedures as body
1076 (thunk) and handler arguments. @code{scm_c_with_throw_handler} is an
1077 equivalent taking C functions. See @code{scm_c_catch} (@pxref{Catch})
1078 for a description of the parameters, the behaviour however of course
1079 follows @code{with-throw-handler}.
1082 If @var{thunk} throws an exception, Guile handles that exception by
1083 invoking the innermost @code{catch} or throw handler whose key matches
1084 that of the exception. When the innermost thing is a throw handler,
1085 Guile calls the specified handler procedure using @code{(apply
1086 @var{handler} key args)}. The handler procedure may either return
1087 normally or exit non-locally. If it returns normally, Guile passes the
1088 exception on to the next innermost @code{catch} or throw handler. If it
1089 exits non-locally, that exit determines the continuation.
1091 The behaviour of a throw handler is very similar to that of a
1092 @code{catch} expression's optional pre-unwind handler. In particular, a
1093 throw handler's handler procedure is invoked in the exact dynamic
1094 context of the @code{throw} expression, just as a pre-unwind handler is.
1095 @code{with-throw-handler} may be seen as a half-@code{catch}: it does
1096 everything that a @code{catch} would do until the point where
1097 @code{catch} would start unwinding the stack and dynamic context, but
1098 then it rethrows to the next innermost @code{catch} or throw handler
1101 Note also that since the dynamic context is not unwound, if a
1102 @code{with-throw-handler} handler throws to a key that does not match
1103 the @code{with-throw-handler} expression's @var{key}, the new throw may
1104 be handled by a @code{catch} or throw handler that is @emph{closer} to
1105 the throw than the first @code{with-throw-handler}.
1107 Here is an example to illustrate this behavior:
1112 (with-throw-handler 'b
1118 (lambda (key . args)
1124 This code will call @code{inner-handler} and then continue with the
1125 continuation of the inner @code{catch}.
1129 @subsubsection Throwing Exceptions
1131 The @code{throw} primitive is used to throw an exception. One argument,
1132 the @var{key}, is mandatory, and must be a symbol; it indicates the type
1133 of exception that is being thrown. Following the @var{key},
1134 @code{throw} accepts any number of additional arguments, whose meaning
1135 depends on the exception type. The documentation for each possible type
1136 of exception should specify the additional arguments that are expected
1137 for that kind of exception.
1139 @deffn {Scheme Procedure} throw key . args
1140 @deffnx {C Function} scm_throw (key, args)
1141 Invoke the catch form matching @var{key}, passing @var{args} to the
1144 @var{key} is a symbol. It will match catches of the same symbol or of
1147 If there is no handler at all, Guile prints an error and then exits.
1150 When an exception is thrown, it will be caught by the innermost
1151 @code{catch} or throw handler that applies to the type of the thrown
1152 exception; in other words, whose @var{key} is either @code{#t} or the
1153 same symbol as that used in the @code{throw} expression. Once Guile has
1154 identified the appropriate @code{catch} or throw handler, it handles the
1155 exception by applying the relevant handler procedure(s) to the arguments
1156 of the @code{throw}.
1158 If there is no appropriate @code{catch} or throw handler for a thrown
1159 exception, Guile prints an error to the current error port indicating an
1160 uncaught exception, and then exits. In practice, it is quite difficult
1161 to observe this behaviour, because Guile when used interactively
1162 installs a top level @code{catch} handler that will catch all exceptions
1163 and print an appropriate error message @emph{without} exiting. For
1164 example, this is what happens if you try to throw an unhandled exception
1165 in the standard Guile REPL; note that Guile's command loop continues
1166 after the error message:
1169 guile> (throw 'badex)
1170 <unnamed port>:3:1: In procedure gsubr-apply @dots{}
1171 <unnamed port>:3:1: unhandled-exception: badex
1176 The default uncaught exception behaviour can be observed by evaluating a
1177 @code{throw} expression from the shell command line:
1180 $ guile -c "(begin (throw 'badex) (display \"here\\n\"))"
1181 guile: uncaught throw to badex: ()
1186 That Guile exits immediately following the uncaught exception
1187 is shown by the absence of any output from the @code{display}
1188 expression, because Guile never gets to the point of evaluating that
1192 @node Exception Implementation
1193 @subsubsection How Guile Implements Exceptions
1195 It is traditional in Scheme to implement exception systems using
1196 @code{call-with-current-continuation}. Continuations
1197 (@pxref{Continuations}) are such a powerful concept that any other
1198 control mechanism --- including @code{catch} and @code{throw} --- can be
1199 implemented in terms of them.
1201 Guile does not implement @code{catch} and @code{throw} like this,
1202 though. Why not? Because Guile is specifically designed to be easy to
1203 integrate with applications written in C. In a mixed Scheme/C
1204 environment, the concept of @dfn{continuation} must logically include
1205 ``what happens next'' in the C parts of the application as well as the
1206 Scheme parts, and it turns out that the only reasonable way of
1207 implementing continuations like this is to save and restore the complete
1210 So Guile's implementation of @code{call-with-current-continuation} is a
1211 stack copying one. This allows it to interact well with ordinary C
1212 code, but means that creating and calling a continuation is slowed down
1213 by the time that it takes to copy the C stack.
1215 The more targeted mechanism provided by @code{catch} and @code{throw}
1216 does not need to save and restore the C stack because the @code{throw}
1217 always jumps to a location higher up the stack of the code that executes
1218 the @code{throw}. Therefore Guile implements the @code{catch} and
1219 @code{throw} primitives independently of
1220 @code{call-with-current-continuation}, in a way that takes advantage of
1221 this @emph{upwards only} nature of exceptions.
1224 @node Error Reporting
1225 @subsection Procedures for Signaling Errors
1227 Guile provides a set of convenience procedures for signaling error
1228 conditions that are implemented on top of the exception primitives just
1231 @deffn {Scheme Procedure} error msg args @dots{}
1232 Raise an error with key @code{misc-error} and a message constructed by
1233 displaying @var{msg} and writing @var{args}.
1236 @deffn {Scheme Procedure} scm-error key subr message args data
1237 @deffnx {C Function} scm_error_scm (key, subr, message, args, data)
1238 Raise an error with key @var{key}. @var{subr} can be a string
1239 naming the procedure associated with the error, or @code{#f}.
1240 @var{message} is the error message string, possibly containing
1241 @code{~S} and @code{~A} escapes. When an error is reported,
1242 these are replaced by formatting the corresponding members of
1243 @var{args}: @code{~A} (was @code{%s} in older versions of
1244 Guile) formats using @code{display} and @code{~S} (was
1245 @code{%S}) formats using @code{write}. @var{data} is a list or
1246 @code{#f} depending on @var{key}: if @var{key} is
1247 @code{system-error} then it should be a list containing the
1248 Unix @code{errno} value; If @var{key} is @code{signal} then it
1249 should be a list containing the Unix signal number; If
1250 @var{key} is @code{out-of-range} or @code{wrong-type-arg},
1251 it is a list containing the bad value; otherwise
1252 it will usually be @code{#f}.
1255 @deffn {Scheme Procedure} strerror err
1256 @deffnx {C Function} scm_strerror (err)
1257 Return the Unix error message corresponding to @var{err}, an integer
1260 When @code{setlocale} has been called (@pxref{Locales}), the message
1261 is in the language and charset of @code{LC_MESSAGES}. (This is done
1265 @c begin (scm-doc-string "boot-9.scm" "false-if-exception")
1266 @deffn syntax false-if-exception expr
1267 Returns the result of evaluating its argument; however
1268 if an exception occurs then @code{#f} is returned instead.
1274 @subsection Dynamic Wind
1276 For Scheme code, the fundamental procedure to react to non-local entry
1277 and exits of dynamic contexts is @code{dynamic-wind}. C code could
1278 use @code{scm_internal_dynamic_wind}, but since C does not allow the
1279 convenient construction of anonymous procedures that close over
1280 lexical variables, this will be, well, inconvenient.
1282 Therefore, Guile offers the functions @code{scm_dynwind_begin} and
1283 @code{scm_dynwind_end} to delimit a dynamic extent. Within this
1284 dynamic extent, which is called a @dfn{dynwind context}, you can
1285 perform various @dfn{dynwind actions} that control what happens when
1286 the dynwind context is entered or left. For example, you can register
1287 a cleanup routine with @code{scm_dynwind_unwind_handler} that is
1288 executed when the context is left. There are several other more
1289 specialized dynwind actions as well, for example to temporarily block
1290 the execution of asyncs or to temporarily change the current output
1291 port. They are described elsewhere in this manual.
1293 Here is an example that shows how to prevent memory leaks.
1297 /* Suppose there is a function called FOO in some library that you
1298 would like to make available to Scheme code (or to C code that
1299 follows the Scheme conventions).
1301 FOO takes two C strings and returns a new string. When an error has
1302 occurred in FOO, it returns NULL.
1305 char *foo (char *s1, char *s2);
1307 /* SCM_FOO interfaces the C function FOO to the Scheme way of life.
1308 It takes care to free up all temporary strings in the case of
1313 scm_foo (SCM s1, SCM s2)
1315 char *c_s1, *c_s2, *c_res;
1317 scm_dynwind_begin (0);
1319 c_s1 = scm_to_locale_string (s1);
1321 /* Call 'free (c_s1)' when the dynwind context is left.
1323 scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY);
1325 c_s2 = scm_to_locale_string (s2);
1327 /* Same as above, but more concisely.
1329 scm_dynwind_free (c_s2);
1331 c_res = foo (c_s1, c_s2);
1333 scm_memory_error ("foo");
1337 return scm_take_locale_string (res);
1341 @rnindex dynamic-wind
1342 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
1343 @deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
1344 All three arguments must be 0-argument procedures.
1345 @var{in_guard} is called, then @var{thunk}, then
1348 If, any time during the execution of @var{thunk}, the
1349 dynamic extent of the @code{dynamic-wind} expression is escaped
1350 non-locally, @var{out_guard} is called. If the dynamic extent of
1351 the dynamic-wind is re-entered, @var{in_guard} is called. Thus
1352 @var{in_guard} and @var{out_guard} may be called any number of
1356 (define x 'normal-binding)
1359 (call-with-current-continuation
1365 (lambda () (set! x 'special-binding))
1369 (lambda () (display x) (newline)
1370 (call-with-current-continuation escape)
1371 (display x) (newline)
1376 (lambda () (set! x old-x)))))))
1382 @result{} normal-binding
1387 @result{} a-cont ;; the value of the (define a-cont...)
1389 @result{} normal-binding
1391 @result{} special-binding
1395 @deftp {C Type} scm_t_dynwind_flags
1396 This is an enumeration of several flags that modify the behavior of
1397 @code{scm_dynwind_begin}. The flags are listed in the following
1401 @item SCM_F_DYNWIND_REWINDABLE
1402 The dynamic context is @dfn{rewindable}. This means that it can be
1403 reentered non-locally (via the invocation of a continuation). The
1404 default is that a dynwind context can not be reentered non-locally.
1409 @deftypefn {C Function} void scm_dynwind_begin (scm_t_dynwind_flags flags)
1410 The function @code{scm_dynwind_begin} starts a new dynamic context and
1411 makes it the `current' one.
1413 The @var{flags} argument determines the default behavior of the
1414 context. Normally, use 0. This will result in a context that can not
1415 be reentered with a captured continuation. When you are prepared to
1416 handle reentries, include @code{SCM_F_DYNWIND_REWINDABLE} in
1419 Being prepared for reentry means that the effects of unwind handlers
1420 can be undone on reentry. In the example above, we want to prevent a
1421 memory leak on non-local exit and thus register an unwind handler that
1422 frees the memory. But once the memory is freed, we can not get it
1423 back on reentry. Thus reentry can not be allowed.
1425 The consequence is that continuations become less useful when
1426 non-reentrant contexts are captured, but you don't need to worry
1427 about that too much.
1429 The context is ended either implicitly when a non-local exit happens,
1430 or explicitly with @code{scm_dynwind_end}. You must make sure that a
1431 dynwind context is indeed ended properly. If you fail to call
1432 @code{scm_dynwind_end} for each @code{scm_dynwind_begin}, the behavior
1436 @deftypefn {C Function} void scm_dynwind_end ()
1437 End the current dynamic context explicitly and make the previous one
1441 @deftp {C Type} scm_t_wind_flags
1442 This is an enumeration of several flags that modify the behavior of
1443 @code{scm_dynwind_unwind_handler} and
1444 @code{scm_dynwind_rewind_handler}. The flags are listed in the
1448 @item SCM_F_WIND_EXPLICITLY
1449 @vindex SCM_F_WIND_EXPLICITLY
1450 The registered action is also carried out when the dynwind context is
1451 entered or left locally.
1455 @deftypefn {C Function} void scm_dynwind_unwind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
1456 @deftypefnx {C Function} void scm_dynwind_unwind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
1457 Arranges for @var{func} to be called with @var{data} as its arguments
1458 when the current context ends implicitly. If @var{flags} contains
1459 @code{SCM_F_WIND_EXPLICITLY}, @var{func} is also called when the
1460 context ends explicitly with @code{scm_dynwind_end}.
1462 The function @code{scm_dynwind_unwind_handler_with_scm} takes care that
1463 @var{data} is protected from garbage collection.
1466 @deftypefn {C Function} void scm_dynwind_rewind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
1467 @deftypefnx {C Function} void scm_dynwind_rewind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
1468 Arrange for @var{func} to be called with @var{data} as its argument when
1469 the current context is restarted by rewinding the stack. When @var{flags}
1470 contains @code{SCM_F_WIND_EXPLICITLY}, @var{func} is called immediately
1473 The function @code{scm_dynwind_rewind_handler_with_scm} takes care that
1474 @var{data} is protected from garbage collection.
1477 @deftypefn {C Function} void scm_dynwind_free (void *mem)
1478 Arrange for @var{mem} to be freed automatically whenever the current
1479 context is exited, whether normally or non-locally.
1480 @code{scm_dynwind_free (mem)} is an equivalent shorthand for
1481 @code{scm_dynwind_unwind_handler (free, mem, SCM_F_WIND_EXPLICITLY)}.
1485 @node Handling Errors
1486 @subsection How to Handle Errors
1488 Error handling is based on @code{catch} and @code{throw}. Errors are
1489 always thrown with a @var{key} and four arguments:
1493 @var{key}: a symbol which indicates the type of error. The symbols used
1494 by libguile are listed below.
1497 @var{subr}: the name of the procedure from which the error is thrown, or
1501 @var{message}: a string (possibly language and system dependent)
1502 describing the error. The tokens @code{~A} and @code{~S} can be
1503 embedded within the message: they will be replaced with members of the
1504 @var{args} list when the message is printed. @code{~A} indicates an
1505 argument printed using @code{display}, while @code{~S} indicates an
1506 argument printed using @code{write}. @var{message} can also be
1507 @code{#f}, to allow it to be derived from the @var{key} by the error
1508 handler (may be useful if the @var{key} is to be thrown from both C and
1512 @var{args}: a list of arguments to be used to expand @code{~A} and
1513 @code{~S} tokens in @var{message}. Can also be @code{#f} if no
1514 arguments are required.
1517 @var{rest}: a list of any additional objects required. e.g., when the
1518 key is @code{'system-error}, this contains the C errno value. Can also
1519 be @code{#f} if no additional objects are required.
1522 In addition to @code{catch} and @code{throw}, the following Scheme
1523 facilities are available:
1525 @deffn {Scheme Procedure} display-error frame port subr message args rest
1526 @deffnx {C Function} scm_display_error (frame, port, subr, message, args, rest)
1527 Display an error message to the output port @var{port}.
1528 @var{frame} is the frame in which the error occurred, @var{subr} is
1529 the name of the procedure in which the error occurred and
1530 @var{message} is the actual error message, which may contain
1531 formatting instructions. These will format the arguments in
1532 the list @var{args} accordingly. @var{rest} is currently
1536 The following are the error keys defined by libguile and the situations
1537 in which they are used:
1541 @cindex @code{error-signal}
1542 @code{error-signal}: thrown after receiving an unhandled fatal signal
1543 such as SIGSEGV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw
1544 contains the coded signal number (at present this is not the same as the
1545 usual Unix signal number).
1548 @cindex @code{system-error}
1549 @code{system-error}: thrown after the operating system indicates an
1550 error condition. The @var{rest} argument in the throw contains the
1554 @cindex @code{numerical-overflow}
1555 @code{numerical-overflow}: numerical overflow.
1558 @cindex @code{out-of-range}
1559 @code{out-of-range}: the arguments to a procedure do not fall within the
1563 @cindex @code{wrong-type-arg}
1564 @code{wrong-type-arg}: an argument to a procedure has the wrong type.
1567 @cindex @code{wrong-number-of-args}
1568 @code{wrong-number-of-args}: a procedure was called with the wrong number
1572 @cindex @code{memory-allocation-error}
1573 @code{memory-allocation-error}: memory allocation error.
1576 @cindex @code{stack-overflow}
1577 @code{stack-overflow}: stack overflow error.
1580 @cindex @code{regular-expression-syntax}
1581 @code{regular-expression-syntax}: errors generated by the regular
1585 @cindex @code{misc-error}
1586 @code{misc-error}: other errors.
1590 @subsubsection C Support
1592 In the following C functions, @var{SUBR} and @var{MESSAGE} parameters
1593 can be @code{NULL} to give the effect of @code{#f} described above.
1595 @deftypefn {C Function} SCM scm_error (SCM @var{key}, char *@var{subr}, char *@var{message}, SCM @var{args}, SCM @var{rest})
1596 Throw an error, as per @code{scm-error} (@pxref{Error Reporting}).
1599 @deftypefn {C Function} void scm_syserror (char *@var{subr})
1600 @deftypefnx {C Function} void scm_syserror_msg (char *@var{subr}, char *@var{message}, SCM @var{args})
1601 Throw an error with key @code{system-error} and supply @code{errno} in
1602 the @var{rest} argument. For @code{scm_syserror} the message is
1603 generated using @code{strerror}.
1605 Care should be taken that any code in between the failing operation
1606 and the call to these routines doesn't change @code{errno}.
1609 @deftypefn {C Function} void scm_num_overflow (char *@var{subr})
1610 @deftypefnx {C Function} void scm_out_of_range (char *@var{subr}, SCM @var{bad_value})
1611 @deftypefnx {C Function} void scm_wrong_num_args (SCM @var{proc})
1612 @deftypefnx {C Function} void scm_wrong_type_arg (char *@var{subr}, int @var{argnum}, SCM @var{bad_value})
1613 @deftypefnx {C Function} void scm_wrong_type_arg_msg (char *@var{subr}, int @var{argnum}, SCM @var{bad_value}, const char *@var{expected})
1614 @deftypefnx {C Function} void scm_memory_error (char *@var{subr})
1615 Throw an error with the various keys described above.
1616 @deftypefnx {C Function} void scm_misc_error (const char *@var{subr}, const char *@var{message}, SCM @var{args})
1618 In @code{scm_wrong_num_args}, @var{proc} should be a Scheme symbol
1619 which is the name of the procedure incorrectly invoked. The other
1620 routines take the name of the invoked procedure as a C string.
1622 In @code{scm_wrong_type_arg_msg}, @var{expected} is a C string
1623 describing the type of argument that was expected.
1625 In @code{scm_misc_error}, @var{message} is the error message string,
1626 possibly containing @code{simple-format} escapes (@pxref{Writing}), and
1627 the corresponding arguments in the @var{args} list.
1631 @subsubsection Signalling Type Errors
1633 Every function visible at the Scheme level should aggressively check the
1634 types of its arguments, to avoid misinterpreting a value, and perhaps
1635 causing a segmentation fault. Guile provides some macros to make this
1638 @deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
1639 @deftypefnx Macro void SCM_ASSERT_TYPE (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr}, const char *@var{expected})
1640 If @var{test} is zero, signal a ``wrong type argument'' error,
1641 attributed to the subroutine named @var{subr}, operating on the value
1642 @var{obj}, which is the @var{position}'th argument of @var{subr}.
1644 In @code{SCM_ASSERT_TYPE}, @var{expected} is a C string describing the
1645 type of argument that was expected.
1648 @deftypefn Macro int SCM_ARG1
1649 @deftypefnx Macro int SCM_ARG2
1650 @deftypefnx Macro int SCM_ARG3
1651 @deftypefnx Macro int SCM_ARG4
1652 @deftypefnx Macro int SCM_ARG5
1653 @deftypefnx Macro int SCM_ARG6
1654 @deftypefnx Macro int SCM_ARG7
1655 One of the above values can be used for @var{position} to indicate the
1656 number of the argument of @var{subr} which is being checked.
1657 Alternatively, a positive integer number can be used, which allows to
1658 check arguments after the seventh. However, for parameter numbers up to
1659 seven it is preferable to use @code{SCM_ARGN} instead of the
1660 corresponding raw number, since it will make the code easier to
1664 @deftypefn Macro int SCM_ARGn
1665 Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
1666 leave it unspecified which argument's type is incorrect. Again,
1667 @code{SCM_ARGn} should be preferred over a raw zero constant.
1670 The @code{SCM_ASRTGO} macro provides another strategy for handling
1673 @deftypefn Macro void SCM_ASRTGO (int @var{test}, label)
1674 If @var{test} is zero, use @code{goto} to jump to the given @var{label}.
1675 @var{label} must appear within the current function.
1678 @node Continuation Barriers
1679 @subsection Continuation Barriers
1681 The non-local flow of control caused by continuations might sometimes
1682 not be wanted. You can use @code{with-continuation-barrier} to erect
1683 fences that continuations can not pass.
1685 @deffn {Scheme Procedure} with-continuation-barrier proc
1686 @deffnx {C Function} scm_with_continuation_barrier (proc)
1687 Call @var{proc} and return its result. Do not allow the invocation of
1688 continuations that would leave or enter the dynamic extent of the call
1689 to @code{with-continuation-barrier}. Such an attempt causes an error
1692 Throws (such as errors) that are not caught from within @var{proc} are
1693 caught by @code{with-continuation-barrier}. In that case, a short
1694 message is printed to the current error port and @code{#f} is returned.
1696 Thus, @code{with-continuation-barrier} returns exactly once.
1699 @deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
1700 Like @code{scm_with_continuation_barrier} but call @var{func} on
1701 @var{data}. When an error is caught, @code{NULL} is returned.
1706 @c TeX-master: "guile.texi"