guile/doc/scheme-control.texi

@page
@node Control Mechanisms
@chapter Controlling the Flow of Program Execution

@menu
* begin::                       Evaluating a sequence of expressions.
* if cond case::                Simple conditional evaluation.
* and or::                      Conditional evaluation of a sequence.
* while do::                    Iteration mechanisms.
* Continuations::               Continuations.
* Multiple Values::             Returning and accepting multiple values.
* Exceptions::                  Throwing and catching exceptions.
* Error Reporting::             Procedures for signaling errors.
* Dynamic Wind::                Guarding against non-local entrance/exit.
@end menu


@node begin
@section Evaluating a Sequence of Expressions


@node if cond case
@section Simple Conditional Evaluation


@node and or
@section Conditional Evaluation of a Sequence of Expressions


@node while do
@section Iteration mechanisms


@node Continuations
@section Continuations

@r5index call-with-current-continuation
@c FIXME::martin: Document me!
@deffn primitive call-with-current-continuation
@end deffn

@node Multiple Values
@section Returning and Accepting Multiple Values

@r5index values
@deffn primitive values . args
Delivers all of its arguments to its continuation.  Except for
continuations created by the @code{call-with-values} procedure,
all continuations take exactly one value.  The effect of
passing no value or more than one value to continuations that
were not created by @code{call-with-values} is unspecified.
@end deffn

@r5index call-with-values
@deffn primitive call-with-values producer consumer
Calls its @var{producer} argument with no values and a
continuation that, when passed some values, calls the
@var{consumer} procedure with those values as arguments.  The
continuation for the call to @var{consumer} is the continuation
of the call to @code{call-with-values}.

@example
(call-with-values (lambda () (values 4 5))
                  (lambda (a b) b))
                                             ==>  5

@end example
@example
(call-with-values * -)                             ==>  -1
@end example
@end deffn


@node Exceptions
@section Exceptions
@cindex error handling
@cindex exception handling

It is traditional in Scheme to implement exception systems using
@code{call-with-current-continuation}.  Guile does not do this, for
performance reasons.  The implementation of
@code{call-with-current-continuation} is a stack copying implementation.
This allows it to interact well with ordinary C code.  Unfortunately, a
stack-copying implementation can be slow -- creating a new continuation
involves a block copy of the stack.

Instead of using @code{call-with-current-continuation}, the exception
primitives documented here are implemented as built-ins that take
advantage of the @emph{upward only} nature of exceptions.

@c ARGFIXME tag/key
@c docstring begin (texi-doc-string "guile" "catch")
@deffn primitive catch tag thunk handler
Invoke @var{thunk} in the dynamic context of @var{handler} for
exceptions matching @var{key}.  If thunk throws to the symbol @var{key},
then @var{handler} is invoked this way:

@example
(handler key args ...)
@end example

@var{key} is a symbol or #t.

@var{thunk} takes no arguments.  If @var{thunk} returns normally, that
is the return value of @code{catch}.

Handler is invoked outside the scope of its own @code{catch}.  If
@var{handler} again throws to the same key, a new handler from further
up the call chain is invoked.

If the key is @code{#t}, then a throw to @emph{any} symbol will match
this call to @code{catch}.
@end deffn

@c docstring begin (texi-doc-string "guile" "throw")
@deffn primitive throw key . args
Invoke the catch form matching @var{key}, passing @var{args} to the
@var{handler}.

@var{key} is a symbol.  It will match catches of the same symbol or of
#t.

If there is no handler at all, an error is signaled.
@end deffn

@c docstring begin (texi-doc-string "guile" "lazy-catch")
@deffn primitive lazy-catch tag thunk handler
This behaves exactly like @code{catch}, except that it does
not unwind the stack (this is the major difference), and if
handler returns, its value is returned from the throw.
@end deffn


@node Error Reporting
@section Procedures for Signaling Errors

Guile provides a set of convenience procedures for signaling error
conditions that are implemented on top of the exception primitives just
described.

@c begin (scm-doc-string "boot-9.scm" "error")
@deffn procedure error msg args @dots{}
Raise an error with key @code{misc-error} and a message constructed by
displaying @var{msg} and writing @var{args}.
@end deffn
@c end

@c ARGFIXME rest/data
@c docstring begin (texi-doc-string "guile" "scm-error")
@deffn primitive scm-error key subr message args rest
Raise an error with key @var{key}.  @var{subr} can be a string naming
the procedure associated with the error, or @code{#f}.  @var{message}
is the error message string, possibly containing @code{~S} and @code{~A}
escapes.  When an error is reported, these are replaced by formating the
corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display}
and @code{~S} (was @code{%S}) formats using @code{write}.  @var{data} is a
list or @code{#f} depending on @var{key}: if @var{key} is
@code{system-error} then it should be a list
containing the Unix @code{errno} value;  If @var{key} is @code{signal} then
it should be a list containing the Unix signal number; otherwise it
will usually be @code{#f}.
@end deffn

@c docstring begin (texi-doc-string "guile" "strerror")
@deffn primitive strerror err
Returns the Unix error message corresponding to @var{err}, an integer.
@end deffn

@c begin (scm-doc-string "boot-9.scm" "false-if-exception")
@deffn syntax false-if-exception expr
Returns the result of evaluating its argument; however
if an exception occurs then @code{#f} is returned instead.
@end deffn
@c end


@node Dynamic Wind
@section Dynamic Wind

[FIXME: this is pasted in from Tom Lord's original guile.texi and should
be reviewed]

@r5index dynamic-wind
@c ARGFIXME in-guard/thunk1 thunk/thunk2 out-guard/thunk3
@c docstring begin (texi-doc-string "guile" "dynamic-wind")
@deffn primitive dynamic-wind thunk1 thunk2 thunk3
All three arguments must be 0-argument procedures.

@var{in-guard} is called, then @var{thunk}, then @var{out-guard}.

If, any time during the execution of @var{thunk}, the continuation
of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard}
is called.   If the continuation of the dynamic-wind is re-entered,
@var{in-guard} is called.   Thus @var{in-guard} and @var{out-guard} may
be called any number of times.

@example
(define x 'normal-binding)
@result{} x

(define a-cont  (call-with-current-continuation
		  (lambda (escape)
		     (let ((old-x x))
		       (dynamic-wind
			  ;; in-guard:
			  ;;
			  (lambda () (set! x 'special-binding))

			  ;; thunk
			  ;;
		 	  (lambda () (display x) (newline)
				     (call-with-current-continuation escape)
				     (display x) (newline)
				     x)

			  ;; out-guard:
			  ;;
			  (lambda () (set! x old-x)))))))

;; Prints:
special-binding
;; Evaluates to:
@result{} a-cont

x
@result{} normal-binding

(a-cont #f)
;; Prints:
special-binding
;; Evaluates to:
@result{} a-cont  ;; the value of the (define a-cont...)

x
@result{} normal-binding

a-cont
@result{} special-binding
@end example
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: