Controlling the Flow of Program Execution
*****************************************

Evaluating a Sequence of Expressions
====================================

begin is used for grouping several expression together so that they syntactically are treated as if they were one expression.  This is particularly important when syntactic expressions are used which only allow one expression, but the programmer wants to use more than one expression in that place.  As an example, consider the conditional expression below:

     (if (> x 0)
         (begin (display "greater") (newline)))

If the two calls to display and newline were not embedded in a begin--statement, the call to newline would get misinterpreted as the else--branch of the if--expression.

 -- syntax: begin expr1 expr2 ...
     The expression(s) are evaluated in left--to--right order and the value of the last expression is returned as the value of the begin--expression.  This expression type is used when the expressions before the last one are evaluated for their side effects.

Simple Conditional Evaluation
=============================

Guile provides three syntactic constructs for conditional evaluation. if is the normal if--then--else expression (with an optional else branch), cond is a conditional expression with multiple branches and case branches if an expression has one of a set of constant values.

 -- syntax: if test consequent [alternate]
     All arguments may be arbitrary expressions.  First, TEST is evaluated.  If it returns a true value, the expression CONSEQUENT is evaluated and ALTERNATE is ignoret.  If TEST evaluates to #f, ALTERNATE is evaluated instead.  The value of the evaluated branch (CONSEQUENT or ALTERNATE) is returned as the value of the if expression.

     When ALTERNATE is omitted and the TEST evaluates to #f, the value of the expression is not specified.

 -- syntax: cond clause1 clause2 ...
     Each cond-clause must look like this:

          (TEST EXPRESSION ...)

     where TEST and EXPRESSION are arbitrary expression, or like this

          (TEST => EXPRESSION

     where EXPRESSION must evaluate to a procedure.

     The TESTs of the clauses are evaluated in order and as soon as one of them evaluates to a true values, the corresponding EXPRESSIONs are evaluated in order and the last value is returned as the value of the cond--expression.  For the => clause type, EXPRESSION is evaluated and the resulting procedure is applied to the value of TEST.  The result of this procedure application is then the result of the cond--expression.

     The TEST of the last CLAUSE may be the keyword else. Then, if none of the preceding TESTs is true, the EXPRESSIONs following the else are evaluated to produce the result of the cond--expression.

 -- syntax: case key clause1 clause2 ...
     KEY may be any expression, the CLAUSEs must have the form

          ((DATUM1 ...) EXPR1 EXPR2 ...)

     and the last CLAUSE may have the form

          (else EXPR1 EXPR2 ...)

     All DATUMs must be distinct.  First, KEY is evaluated.  The the result of this evaluation is compared against all DATUMs using eqv?.  When this comparison succeeds, the epression(s) following the DATUM are evaluated from left to right, returning the value of the last expression as the result of the case expression.

     If the KEY matches no DATUM and there is an else--clause, the expressions following the else are evaluated.  If there is no such clause, the result of the expression is unspecified.

Conditional Evaluation of a Sequence of Expressions
===================================================

and and or evaluate all their arguments, similar to begin, but evaluation stops as soon as one of the expressions evaluates to false or true, respectively.

 -- syntax: and expr ...
     Evaluate the EXPRs from left to right and stop evaluation as soon as one expression evaluates to #f; the remaining expressions are not evaluated.  The value of the last evaluated expression is returned. If no expression evaluates to #f, the value of the last expression is returned.

     If used without expressions, #t is returned.

 -- syntax: or expr ...
     Evaluate the EXPRs from left to right and stop evaluation as soon as one expression evaluates to a true value (that is, a value different from #f); the remaining expressions are not evaluated.  The value of the last evaluated expression is returned.  If all expressions evaluate to #f, #f is returned.

     If used without expressions, #f is returned.

Iteration mechanisms
====================

Scheme has only few iteration mechanisms, mainly because iteration in Scheme programs is normally expressed using recursion.  Nevertheless, R5RS defines a construct for programming loops, calling do.  In addition, Guile has an explicit looping syntax called while.

 -- syntax: do ((variable1 init1 step1) ...) (test expr ...) command ...
     The INIT expressions are evaluated and the VARIABLES are bound to their values. Then looping starts with testing the TEST expression.  If TEST evaluates to a true value, the EXPR following the TEST are evaluated and the value of the last EXPR is returned as the value of the do expression.  If TEST evaluates to false, the COMMANDs are evaluated in order, the STEPs are evaluated and stored into the VARIABLES and the next iteration starts.

     Any of the STEP expressions may be omitted, so that the corresponding variable is not changed during looping.

 -- syntax: while cond body ...
     Evaluate all expressions in BODY in order, as long as COND evaluates to a true value.  The COND expression is tested before every iteration, so that the body is not evaluated at all if COND is #f right from the start.

Another very common way of expressing iteration in Scheme programs is the use of the so--called named let.

Named let is a variant of let which creates a procedure and calls it in one step.  Because of the newly created procedure, named let is more powerful than do---it can be used for iteration, but also for arbitrary recursion.

 -- syntax: let variable bindings body
     For the definition of BINDINGS see the documentation about let (see Local Bindings).

     Named let works as follows:

       * A new procedure which accepts as many arguments as are in BINDINGS is created and bound locally (using let) to VARIABLE.  The new procedure's formal argument names are the name of the VARIABLES.

       * The BODY expressions are inserted into the newly created procedure.

       * The procedure is called with the INIT expressions as the formal arguments.

     The next example implements a loop which iterates (by recursion) 1000 times.

          (let lp ((x 1000))
            (if (positive? x)
                (lp (- x 1))
                x))
          =>
          0

Continuations
=============

The ability to explicitly capture continuations using call-with-current-continuation (also often called call/cc for short), and to invoke such continuations later any number of times, and from any other point in a program, provides maybe the most powerful control structure known.  All other control structures, such as loops and coroutines, can be emulated using continuations.

The implementation of continuations in Guile is not as efficient as one might hope, because it is constrained by the fact that Guile is designed to cooperate with programs written in other languages, such as C, which do not know about continuations.  So continuations should be used when there is no other simple way of achieving the desired behaviour, or where the advantages of the elegant continuation mechanism outweigh the need for optimum performance.  If you find yourself using call/cc for escape procedures and your program is running too slow, you might want to use exceptions (see Exceptions) instead.

 -- primitive: call-with-current-continuation proc
     Capture the current continuation and call PROC with the captured continuation as the single argument.  This continuation can then be called with arbitrarily many arguments.  Such a call will work like a goto to the invocation location of call-with-current-continuation, passing the arguments in a way that they are returned by the call to call-with-current-continuation.  Since it is legal to store the captured continuation in a variable or to pass it to other procedures, it is possible that a procedure returns more than once, even if it is called only one time.  This can be confusing at times.

     (define kont #f)
     (call-with-current-continuation
       (lambda (k)
          (set! kont k)
          1))
     =>
     1

     (kont 2)
     =>
     2

Returning and Accepting Multiple Values
=======================================

Scheme allows a procedure to return more than one value to its caller. This is quite different to other languages which only allow single--value returns.  Returning multiple values is different from returning a list (or pair or vector) of values to the caller, because conceptionally not one compound object is returned, but several distinct values.

The primitive procedures for handling multiple values are values and call-with-values.  values is used for returning multiple values from a procedure.  This is done by placing a call to values with zero or more arguments in tail position in a procedure body.  call-with-values combines a procedure returning multiple values with a procedure which accepts these values as parameters.

 -- primitive: values expr ...
     Delivers all of its arguments to its continuation.  Except for continuations created by the 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 call-with-values is unspecified.

 -- primitive: call-with-values producer consumer
     Calls its PRODUCER argument with no values and a continuation that, when passed some values, calls the CONSUMER procedure with those values as arguments.  The continuation for the call to CONSUMER is the continuation of the call to call-with-values.

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

          (call-with-values * -)                             ==>  -1

In addition to the fundamental procedures described above, Guile has a module which exports a syntax called receive, which is much more convenient.  If you want to use it in your programs, you have to load the module (ice-9 receive) with the statement

     (use-modules (ice-9 receive))

 -- library syntax: receive formals expr body ...
     Evaluate the expression EXPR, and bind the result values (zero or more) to the formal arguments in the formal argument list FORMALS. FORMALS must have the same syntax like the formal argument list used in lambda (see Lambda).  After binding the variables, the expressions in BODY ... are evaluated in order.

Exceptions
==========

A common requirement in applications is to want to jump non-locally from the depths of a computation back to, say, the application's main processing loop.  Usually, the place that is the target of the jump is somewhere in the calling stack of procedures that called the procedure that wants to jump back.  For example, typical logic for a key press driven application might look something like this:

     main-loop:
       read the next key press and call dispatch-key

     dispatch-key:
       lookup the key in a keymap and call an appropriate procedure,
       say find-file

     find-file:
       interactively read the required file name, then call
       find-specified-file

     find-specified-file:
       check whether file exists; if not, jump back to main-loop
       ...

The jump back to main-loop could be achieved by returning through the stack one procedure at a time, using the return value of each procedure to indicate the error condition, but Guile (like most modern programming languages) provides an additional mechanism called exception handling that can be used to implement such jumps much more conveniently.

Exception Terminology
---------------------

There are several variations on the terminology for dealing with non-local jumps.  It is useful to be aware of them, and to realize that they all refer to the same basic mechanism.

  * Actually making a non-local jump may be called raising an exception, raising a signal, throwing an exception or doing a long jump.  When the jump indicates an error condition, people may talk about signalling, raising or throwing an error.

  * Handling the jump at its target may be referred to as catching or handling the exception, signal or, where an error condition is involved, error.

Where signal and signalling are used, special care is needed to avoid the risk of confusion with POSIX signals.  (Especially considering that Guile handles POSIX signals by throwing a corresponding kind of exception: REFFIXME.)

This manual prefers to speak of throwing and catching exceptions, since this terminology matches the corresponding Guile primitives.

Catching Exceptions
-------------------

catch is used to set up a target for a possible non-local jump. The arguments of a catch expression are a key, which restricts the set of exceptions to which this catch applies, a thunk that specifies the normal case code --- i.e. what should happen if no exceptions are thrown --- and a handler procedure that says what to do if an exception is thrown.  Note that if the normal case thunk executes normally, which means without throwing any exceptions, the handler procedure is not executed at all.

When an exception is thrown using the throw primitive, the first argument of the throw is a symbol that indicates the type of the exception.  For example, Guile throws an exception using the symbol numerical-overflow to indicate numerical overflow errors such as division by zero:

     (/ 1 0)
     =>
     ABORT: (numerical-overflow)

The KEY argument in a catch expression corresponds to this symbol.  KEY may be a specific symbol, such as numerical-overflow, in which case the catch applies specifically to exceptions of that type; or it may be #t, which means that the catch applies to all exceptions, irrespective of their type.

The second argument of a catch expression should be a thunk (i.e. a procedure that accepts no arguments) that specifies the normal case code.  The catch is active for the execution of this thunk, including any code called directly or indirectly by the thunk's body. Evaluation of the catch expression activates the catch and then calls this thunk.

The third argument of a catch expression is a handler procedure. If an exception is thrown, this procedure is called with exactly the arguments specified by the throw.  Therefore, the handler procedure must be designed to accept a number of arguments that corresponds to the number of arguments in all throw expressions that can be caught by this catch.

 -- primitive: catch key thunk handler
     Invoke THUNK in the dynamic context of HANDLER for exceptions matching KEY.  If thunk throws to the symbol KEY, then HANDLER is invoked this way:

          (handler key args ...)

     KEY is a symbol or #t. THUNK takes no arguments.  If THUNK returns normally, that is the return value of catch. Handler is invoked outside the scope of its own catch. If HANDLER again throws to the same key, a new handler from further up the call chain is invoked. If the key is #t, then a throw to any symbol will match this call to catch.

If the handler procedure needs to match a variety of throw expressions with varying numbers of arguments, you should write it like this:

     (lambda (key . args)
       ...)

The KEY argument is guaranteed always to be present, because a throw without a KEY is not valid.  The number and interpretation of the ARGS varies from one type of exception to another, but should be specified by the documentation for each exception type.

Note that, once the handler procedure is invoked, the catch that led to the handler procedure being called is no longer active.  Therefore, if the handler procedure itself throws an exception, that exception can only be caught by another active catch higher up the call stack, if there is one.

Throwing Exceptions
-------------------

 -- primitive: throw key . args
     Invoke the catch form matching KEY, passing ARGS to the HANDLER.

     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.

Catch Without Unwinding
-----------------------

 -- primitive: lazy-catch key thunk handler
     This behaves exactly like 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.

Capturing the Stack at a Throw
------------------------------

How Guile Implements Exceptions
-------------------------------

It is traditional in Scheme to implement exception systems using call-with-current-continuation.  Continuations (see Continuations) are such a powerful concept that any other control mechanism --- including catch and throw --- can be implemented in terms of them.

Guile does not implement catch and throw like this, though.  Why not?  Because Guile is specifically designed to be easy to integrate with applications written in C.  In a mixed Scheme/C environment, the concept of continuation must logically include ``what happens next'' in the C parts of the application as well as the Scheme parts, and it turns out that the only reasonable way of implementing continuations like this is to save and restore the complete C stack.

So Guile's implementation of call-with-current-continuation is a stack copying one.  This allows it to interact well with ordinary C code, but means that creating and calling a continuation is slowed down by the time that it takes to copy the C stack.

The more targeted mechanism provided by catch and throw does not need to save and restore the C stack because the throw always jumps to a location higher up the stack of the code that executes the throw.  Therefore Guile implements the catch and throw primitives independently of call-with-current-continuation, in a way that takes advantage of this upwards only nature of exceptions.

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.

 -- procedure: error msg args ...
     Raise an error with key misc-error and a message constructed by displaying MSG and writing ARGS.

 -- primitive: scm-error key subr message args data
     Raise an error with key KEY.  SUBR can be a string naming the procedure associated with the error, or #f. MESSAGE is the error message string, possibly containing ~S and ~A escapes.  When an error is reported, these are replaced by formatting the corresponding members of ARGS: ~A (was %s in older versions of Guile) formats using display and ~S (was %S) formats using write.  DATA is a list or #f depending on KEY: if KEY is system-error then it should be a list containing the Unix errno value; If KEY is signal then it should be a list containing the Unix signal number; otherwise it will usually be #f.

 -- primitive: strerror err
     Return the Unix error message corresponding to ERR, which must be an integer value.

 -- syntax: false-if-exception expr
     Returns the result of evaluating its argument; however if an exception occurs then #f is returned instead.

Dynamic Wind
============

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

 -- primitive: dynamic-wind in_guard thunk out_guard
     All three arguments must be 0-argument procedures. IN_GUARD is called, then THUNK, then OUT_GUARD. If, any time during the execution of THUNK, the continuation of the dynamic_wind expression is escaped non-locally, OUT_GUARD is called.  If the continuation of the dynamic-wind is re-entered, IN_GUARD is called.  Thus IN_GUARD and OUT_GUARD may be called any number of times.

          (define x 'normal-binding)
          => 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:
          => a-cont
          x
          => normal-binding
          (a-cont #f)
          ;; Prints:
          special-binding
          ;; Evaluates to:
          => a-cont  ;; the value of the (define a-cont...)
          x
          => normal-binding
          a-cont
          => special-binding