Controlling the Flow of Program Execution
=========================================

See Control Flow for a discussion of how the more general control flow of Scheme affects C code.

Sequencing and Splicing
-----------------------

As an expression, the begin syntax is used to evaluate a sequence of sub-expressions in order.  Consider the conditional expression below:

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

If the test is true, we want to display ``greater'' to the current output port, then display a newline.  We use begin to form a compound expression out of this sequence of sub-expressions.

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

The begin syntax has another role in definition context (see Internal Definitions).  A begin form in a definition context splices its subforms into its place.  For example, consider the following procedure:

     (define (make-seal)
       (define-sealant seal open)
       (values seal open))

Let us assume the existence of a define-sealant macro that expands out to some definitions wrapped in a begin, like so:

     (define (make-seal)
       (begin
         (define seal-tag
           (list 'seal))
         (define (seal x)
           (cons seal-tag x))
         (define (sealed? x)
           (and (pair? x) (eq? (car x) seal-tag)))
         (define (open x)
           (if (sealed? x)
               (cdr x)
               (error "Expected a sealed value:" x))))
       (values seal open))

Here, because the begin is in definition context, its subforms are spliced into the place of the begin.  This allows the definitions created by the macro to be visible to the following expression, the values form.

It is a fine point, but splicing and sequencing are different.  It can make sense to splice zero forms, because it can make sense to have zero internal definitions before the expressions in a procedure or lexical binding form.  However it does not make sense to have a sequence of zero expressions, because in that case it would not be clear what the value of the sequence would be, because in a sequence of zero expressions, there can be no last value.  Sequencing zero expressions is an error.

It would be more elegant in some ways to eliminate splicing from the Scheme language, and without macros (see Macros), that would be a good idea.  But it is useful to be able to write macros that expand out to multiple definitions, as in define-sealant above, so Scheme abuses the begin form for these two tasks.

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 ignored.  If TEST evaluates to #f, ALTERNATE is evaluated instead.  The values of the evaluated branch (CONSEQUENT or ALTERNATE) are returned as the values of the if expression.

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

When you go to write an if without an alternate (a one-armed if), part of what you are expressing is that you don't care about the return value (or values) of the expression.  As such, you are more interested in the effect of evaluating the consequent expression.  (By convention, we use the word statement to refer to an expression that is evaluated for effect, not for value).

In such a case, it is considered more clear to express these intentions with the special forms when and unless.  As an added bonus, these forms take a body like in a let expression, which can contain internal definitions and multiple statements to evaluate (see Local Bindings).

 -- Scheme Syntax: when test body
 -- Scheme Syntax: unless test body
     The actual definitions of these forms may be their most clear documentation:

          (define-syntax-rule (when test stmt stmt* ...)
            (if test (let () stmt stmt* ...)))

          (define-syntax-rule (unless test stmt stmt* ...)
            (if (not test) (let () stmt stmt* ...)))

     That is to say, when evaluates its consequent statements in order if TEST is true.  unless is the opposite: it evaluates the statements if TEST is false.

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

          (TEST BODY)

     where TEST is an 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 value, the corresponding BODY is evaluated to produce the result 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.

     One additional cond-clause is available as an extension to standard Scheme:

          (TEST GUARD => EXPRESSION)

     where GUARD and EXPRESSION must evaluate to procedures. For this clause type, TEST may return multiple values, and cond ignores its boolean state; instead, cond evaluates GUARD and applies the resulting procedure to the value(s) of TEST, as if GUARD were the CONSUMER argument of call-with-values.  If the result of that procedure call is a true value, it evaluates EXPRESSION and applies the resulting procedure to the value(s) of TEST, in the same manner as the GUARD was called.

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

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

          ((DATUM1 ...) BODY)

     or

          ((DATUM1 ...) => EXPRESSION)

     and the last CLAUSE may have the form

          (else BODY)

     or

          (else => EXPRESSION)

     All DATUMs must be distinct.  First, KEY is evaluated.  The result of this evaluation is compared against all DATUM values using eqv?.  When this comparison succeeds, the BODY following the DATUM is evaluated to produce the result of the case expression.

     If the KEY matches no DATUM and there is an else-clause, the BODY following the else is evaluated to produce the result of the case expression.  If there is no such clause, the result of the expression is unspecified.

     For the => clause types, EXPRESSION is evaluated and the resulting procedure is applied to the value of KEY.  The result of this procedure application is then the result of the case-expression.

Conditional Evaluation of a Sequence of Expressions
---------------------------------------------------

and and or evaluate all their arguments in order, 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 ((variable init [step]) ...) (test expr ...) body ...
     Bind VARIABLEs and evaluate BODY until TEST is true. The return value is the last EXPR after TEST, if given.  A simple example will illustrate the basic form,

          (do ((i 1 (1+ i)))
              ((> i 4))
            (display i))
          -| 1234

     Or with two variables and a final return value,

          (do ((i 1 (1+ i))
               (p 3 (* 3 p)))
              ((> i 4)
               p)
            (format #t "3**~s is ~s\n" i p))
          -|
          3**1 is 3
          3**2 is 9
          3**3 is 27
          3**4 is 81
          =>
          243

     The VARIABLE bindings are established like a let, in that the expressions are all evaluated and then all bindings made.  When iterating, the optional STEP expressions are evaluated with the previous bindings in scope, then new bindings all made.

     The TEST expression is a termination condition.  Looping stops when the TEST is true.  It's evaluated before running the BODY each time, so if it's true the first time then BODY is not run at all.

     The optional EXPRs after the TEST are evaluated at the end of looping, with the final VARIABLE bindings available.  The last EXPR gives the return value, or if there are no EXPRs the return value is unspecified.

     Each iteration establishes bindings to fresh locations for the VARIABLEs, like a new let for each iteration.  This is done for VARIABLEs without STEP expressions too.  The following illustrates this, showing how a new i is captured by the lambda in each iteration (see The Concept of Closure).

          (define lst '())
          (do ((i 1 (1+ i)))
              ((> i 4))
            (set! lst (cons (lambda () i) lst)))
          (map (lambda (proc) (proc)) lst)
          =>
          (4 3 2 1)

 -- syntax: while cond body ...
     Run a loop executing the BODY forms while COND is true. COND is tested at the start of each iteration, so if it's #f the first time then BODY is not executed at all.

     Within while, two extra bindings are provided, they can be used from both COND and BODY.

      -- Scheme Procedure: break break-arg ...
          Break out of the while form.

      -- Scheme Procedure: continue
          Abandon the current iteration, go back to the start and test COND again, etc.

     If the loop terminates normally, by the COND evaluating to #f, then the while expression as a whole evaluates to #f.  If it terminates by a call to break with some number of arguments, those arguments are returned from the while expression, as multiple values.  Otherwise if it terminates by a call to break with no arguments, then return value is #t.

          (while #f (error "not reached")) => #f
          (while #t (break)) => #t
          (while #t (break 1 2 3)) => 1 2 3

     Each while form gets its own break and continue procedures, operating on that while.  This means when loops are nested the outer break can be used to escape all the way out. For example,

          (while (test1)
            (let ((outer-break break))
              (while (test2)
                (if (something)
                  (outer-break #f))
                ...)))

     Note that each break and continue procedure can only be used within the dynamic extent of its while.  Outside the while their behaviour is unspecified.

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

Prompts
-------

Prompts are control-flow barriers between different parts of a program. In the same way that a user sees a shell prompt (e.g., the Bash prompt) as a barrier between the operating system and her programs, Scheme prompts allow the Scheme programmer to treat parts of programs as if they were running in different operating systems.

We use this roundabout explanation because, unless you're a functional programming junkie, you probably haven't heard the term, ``delimited, composable continuation''. That's OK; it's a relatively recent topic, but a very useful one to know about.

Prompt Primitives
.................

Guile's primitive delimited control operators are call-with-prompt and abort-to-prompt.

 -- Scheme Procedure: call-with-prompt tag thunk handler
     Set up a prompt, and call THUNK within that prompt.

     During the dynamic extent of the call to THUNK, a prompt named TAG will be present in the dynamic context, such that if a user calls abort-to-prompt (see below) with that tag, control rewinds back to the prompt, and the HANDLER is run.

     HANDLER must be a procedure. The first argument to HANDLER will be the state of the computation begun when THUNK was called, and ending with the call to abort-to-prompt. The remaining arguments to HANDLER are those passed to abort-to-prompt.

 -- Scheme Procedure: make-prompt-tag [stem]
     Make a new prompt tag.  A prompt tag is simply a unique object. Currently, a prompt tag is a fresh pair.  This may change in some future Guile version.

 -- Scheme Procedure: default-prompt-tag
     Return the default prompt tag.  Having a distinguished default prompt tag allows some useful prompt and abort idioms, discussed in the next section.  Note that default-prompt-tag is actually a parameter, and so may be dynamically rebound using parameterize. See Parameters.

 -- Scheme Procedure: abort-to-prompt tag val1 val2 ...
     Unwind the dynamic and control context to the nearest prompt named TAG, also passing the given values.

C programmers may recognize call-with-prompt and abort-to-prompt as a fancy kind of setjmp and longjmp, respectively. Prompts are indeed quite useful as non-local escape mechanisms. Guile's with-exception-handler and raise-exception are implemented in terms of prompts. Prompts are more convenient than longjmp, in that one has the opportunity to pass multiple values to the jump target.

Also unlike longjmp, the prompt handler is given the full state of the process that was aborted, as the first argument to the prompt's handler. That state is the continuation of the computation wrapped by the prompt. It is a delimited continuation, because it is not the whole continuation of the program; rather, just the computation initiated by the call to call-with-prompt.

The continuation is a procedure, and may be reinstated simply by invoking it, with any number of values. Here's where things get interesting, and complicated as well. Besides being described as delimited, continuations reified by prompts are also composable, because invoking a prompt-saved continuation composes that continuation with the current one.

Imagine you have saved a continuation via call-with-prompt:

     (define cont
       (call-with-prompt
        ;; tag
        'foo
        ;; thunk
        (lambda ()
          (+ 34 (abort-to-prompt 'foo)))
        ;; handler
        (lambda (k) k)))

The resulting continuation is the addition of 34. It's as if you had written:

     (define cont
       (lambda (x)
         (+ 34 x)))

So, if we call cont with one numeric value, we get that number, incremented by 34:

     (cont 8)
     => 42
     (* 2 (cont 8))
     => 84

The last example illustrates what we mean when we say, "composes with the current continuation". We mean that there is a current continuation -- some remaining things to compute, like (lambda (x) (* x 2)) -- and that calling the saved continuation doesn't wipe out the current continuation, it composes the saved continuation with the current one.

We're belaboring the point here because traditional Scheme continuations, as discussed in the next section, aren't composable, and are actually less expressive than continuations captured by prompts. But there's a place for them both.

Before moving on, we should mention that if the handler of a prompt is a lambda expression, and the first argument isn't referenced, an abort to that prompt will not cause a continuation to be reified.  This can be an important efficiency consideration to keep in mind.

One example where this optimization matters is escape continuations.  Escape continuations are delimited continuations whose only use is to make a non-local exit---i.e., to escape from the current continuation.  A common use of escape continuations is when handling an exception (see Exceptions).

The constructs below are syntactic sugar atop prompts to simplify the use of escape continuations.

 -- Scheme Procedure: call-with-escape-continuation proc
 -- Scheme Procedure: call/ec proc
     Call PROC with an escape continuation.

     In the example below, the RETURN continuation is used to escape the continuation of the call to fold.

          (use-modules (ice-9 control)
                       (srfi srfi-1))

          (define (prefix x lst)
            ;; Return all the elements before the first occurrence
            ;; of X in LST.
            (call/ec
              (lambda (return)
                (fold (lambda (element prefix)
                        (if (equal? element x)
                            (return (reverse prefix))  ; escape `fold'
                            (cons element prefix)))
                      '()
                      lst))))

          (prefix 'a '(0 1 2 a 3 4 5))
          => (0 1 2)

 -- Scheme Syntax: let-escape-continuation k body ...
 -- Scheme Syntax: let/ec k body ...
     Bind K within BODY to an escape continuation.

     This is equivalent to (call/ec (lambda (K) BODY ...)).

Additionally there is another helper primitive exported by (ice-9 control), so load up that module for suspendable-continuation?:

     (use-modules (ice-9 control))

 -- Scheme Procedure: suspendable-continuation? tag
     Return #t if a call to abort-to-prompt with the prompt tag TAG would produce a delimited continuation that could be resumed later.

     Almost all continuations have this property.  The exception is where some code between the call-with-prompt and the abort-to-prompt recursed through C for some reason, the abort-to-prompt will succeed but any attempt to resume the continuation (by calling it) would fail.  This is because composing a saved continuation with the current continuation involves relocating the stack frames that were saved from the old stack onto a (possibly) new position on the new stack, and Guile can only do this for stack frames that it created for Scheme code, not stack frames created by the C compiler.  It's a bit gnarly but if you stick with Scheme, you won't have any problem.

     If no prompt is found with the given tag, this procedure just returns #f.

Shift, Reset, and All That
..........................

There is a whole zoo of delimited control operators, and as it does not seem to be a bounded set, Guile implements support for them in a separate module:

     (use-modules (ice-9 control))

Firstly, we have a helpful abbreviation for the call-with-prompt operator.

 -- Scheme Syntax: % expr
 -- Scheme Syntax: % expr handler
 -- Scheme Syntax: % tag expr handler
     Evaluate EXPR in a prompt, optionally specifying a tag and a handler.  If no tag is given, the default prompt tag is used.

     If no handler is given, a default handler is installed.  The default handler accepts a procedure of one argument, which will be called on the captured continuation, within a prompt.

     Sometimes it's easier just to show code, as in this case:

          (define (default-prompt-handler k proc)
            (% (default-prompt-tag)
               (proc k)
               default-prompt-handler))

     The % symbol is chosen because it looks like a prompt.

Likewise there is an abbreviation for abort-to-prompt, which assumes the default prompt tag:

 -- Scheme Procedure: abort val1 val2 ...
     Abort to the default prompt tag, passing VAL1 VAL2 ... to the handler.

As mentioned before, (ice-9 control) also provides other delimited control operators.  This section is a bit technical, and first-time users of delimited continuations should probably come back to it after some practice with %.

Still here?  So, when one implements a delimited control operator like call-with-prompt, one needs to make two decisions.  Firstly, does the handler run within or outside the prompt?  Having the handler run within the prompt allows an abort inside the handler to return to the same prompt handler, which is often useful.  However it prevents tail calls from the handler, so it is less general.

Similarly, does invoking a captured continuation reinstate a prompt? Again we have the tradeoff of convenience versus proper tail calls.

These decisions are captured in the Felleisen F operator.  If neither the continuations nor the handlers implicitly add a prompt, the operator is known as --F--.  This is the case for Guile's call-with-prompt and abort-to-prompt.

If both continuation and handler implicitly add prompts, then the operator is +F+.  shift and reset are such operators.

 -- Scheme Syntax: reset body1 body2 ...
     Establish a prompt, and evaluate BODY1 BODY2 ... within that prompt.

     The prompt handler is designed to work with shift, described below.

 -- Scheme Syntax: shift cont body1 body2 ...
     Abort to the nearest reset, and evaluate BODY1 BODY2 ... in a context in which the captured continuation is bound to CONT.

     As mentioned above, taken together, the BODY1 BODY2 ... expressions and the invocations of CONT implicitly establish a prompt.

Interested readers are invited to explore Oleg Kiselyov's wonderful web site at http://okmij.org/ftp/, for more information on these operators.

Continuations
-------------

A ``continuation'' is the code that will execute when a given function or expression returns.  For example, consider

     (define (foo)
       (display "hello\n")
       (display (bar)) (newline)
       (exit))

The continuation from the call to bar comprises a display of the value returned, a newline and an exit.  This can be expressed as a function of one argument.

     (lambda (r)
       (display r) (newline)
       (exit))

In Scheme, continuations are represented as special procedures just like this.  The special property is that when a continuation is called it abandons the current program location and jumps directly to that represented by the continuation.

A continuation is like a dynamic label, capturing at run-time a point in program execution, including all the nested calls that have lead to it (or rather the code that will execute when those calls return).

Continuations are created with the following functions.

 -- Scheme Procedure: call-with-current-continuation proc
 -- Scheme Procedure: call/cc proc
     Capture the current continuation and call (PROC CONT) with it.  The return value is the value returned by PROC, or when (CONT VALUE) is later invoked, the return is the VALUE passed.

     Normally CONT should be called with one argument, but when the location resumed is expecting multiple values (see Multiple Values) then they should be passed as multiple arguments, for instance (CONT X Y Z).

     CONT may only be used from the same side of a continuation barrier as it was created (see Continuation Barriers), and in a multi-threaded program only from the thread in which it was created.

     The call to PROC is not part of the continuation captured, it runs only when the continuation is created.  Often a program will want to store CONT somewhere for later use; this can be done in PROC.

     The call in the name call-with-current-continuation refers to the way a call to PROC gives the newly created continuation.  It's not related to the way a call is used later to invoke that continuation.

     call/cc is an alias for call-with-current-continuation. This is in common use since the latter is rather long.

Here is a simple example,

     (define kont #f)
     (format #t "the return is ~a\n"
             (call/cc (lambda (k)
                        (set! kont k)
                        1)))
     => the return is 1

     (kont 2)
     => the return is 2

call/cc captures a continuation in which the value returned is going to be displayed by format.  The lambda stores this in kont and gives an initial return 1 which is displayed.  The later invocation of kont resumes the captured point, but this time returning 2, which is displayed.

When Guile is run interactively, a call to format like this has an implicit return back to the read-eval-print loop.  call/cc captures that like any other return, which is why interactively kont will come back to read more input.

C programmers may note that call/cc is like setjmp in the way it records at runtime a point in program execution.  A call to a continuation is like a longjmp in that it abandons the present location and goes to the recorded one.  Like longjmp, the value passed to the continuation is the value returned by call/cc on resuming there.  However longjmp can only go up the program stack, but the continuation mechanism can go anywhere.

When a continuation is invoked, call/cc and subsequent code effectively ``returns'' a second time.  It can be confusing to imagine a function returning more times than it was called.  It may help instead to think of it being stealthily re-entered and then program flow going on as normal.

dynamic-wind (see Dynamic Wind) can be used to ensure setup and cleanup code is run when a program locus is resumed or abandoned through the continuation mechanism.

Continuations are a powerful mechanism, and can be used to implement almost any sort of control structure, such as loops, coroutines, or exception handlers.

However the implementation of continuations in Guile is not as efficient as one might hope, because Guile is designed to cooperate with programs written in other languages, such as C, which do not know about continuations.  Basically continuations are captured by a block copy of the stack, and resumed by copying back.

For this reason, continuations captured by call/cc should be used only when there is no other simple way to achieve the desired result, or when the elegance of the continuation mechanism outweighs the need for performance.

Escapes upwards from loops or nested functions are generally best handled with prompts (see Prompts).  Coroutines can be efficiently implemented with cooperating threads (a thread holds a full program stack but doesn't copy it around the way continuations do).

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 conceptually 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.

 -- Scheme Procedure: values arg ...
 -- C Function: scm_values (args)
     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.

     For scm_values, ARGS is a list of arguments and the return is a multiple-values object which the caller can return.  In the current implementation that object shares structure with ARGS, so ARGS should not be modified subsequently.

 -- C Function: SCM scm_c_values (SCM *base, size_t n)
     scm_c_values is an alternative to scm_values.  It creates a new values object, and copies into it the N values starting from BASE.

     Currently this creates a list and passes it to scm_values, but we expect that in the future we will be able to use a more efficient representation.

 -- C Function: size_t scm_c_nvalues (SCM obj)
     If OBJ is a multiple-values object, returns the number of values it contains.  Otherwise returns 1.

 -- C Function: SCM scm_c_value_ref (SCM obj, size_t idx)
     Returns the value at the position specified by IDX in OBJ.  Note that OBJ will ordinarily be a multiple-values object, but it need not be.  Any other object represents a single value (itself), and is handled appropriately.

 -- Scheme Procedure: 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.  This is in the (ice-9 receive) and is the same as specified by SRFI-8 (see SRFI-8).

     (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 FORMALS.  FORMALS is a list of symbols, like the argument list in a lambda (see Lambda).  After binding the variables, the BODY is evaluated to produce the result of the receive expression.

     For example getting results from partition in SRFI-1 (see SRFI-1),

          (receive (odds evens)
              (partition odd? '(7 4 2 8 3))
            (display odds)
            (display " and ")
            (display evens))
          -| (7 3) and (4 2 8)

Exceptions
----------

What happens when things go wrong?  Guile's exception facility exists to help answer this question, allowing programs to describe the problem and to handle the situation in a flexible way.

When a program runs into a problem, such as division by zero, it will raise an exception.  Sometimes exceptions get raised by Guile on a program's behalf.  Sometimes a program will want to raise exceptions of its own.  Raising an exception stops the current computation and instead invokes the current exception handler, passing it an exception object describing the unexpected situation.

Usually an exception handler will unwind the computation back to some kind of safe point.  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, raise an exception
       ...

In this case, main-loop can install an exception handler that would cause any exception raised inside dispatch-key to print a warning and jump back to the main loop.

The following subsections go into more detail about exception objects, raising exceptions, and handling exceptions.  It also presents a historical interface that was used in Guile's first 25 years and which won't be going away any time soon.

Exception Objects
.................

When Guile encounters an exceptional situation, it raises an exception, where the exception is an object that describes the exceptional situation.  Exception objects are structured data, built on the record facility (see Records).

 -- Exception Type: &exception
     The base exception type.  All exception objects are composed of instances of subtypes of &exception.

 -- Scheme Procedure: exception-type? obj
     Return true if OBJ is an exception type.

Exception types exist in a hierarchy.  New exception types can be defined using make-exception-type.

 -- Scheme Procedure: make-exception-type id parent field-names
     Return a new exception type named ID, inheriting from PARENT, and with the fields whose names are listed in FIELD-NAMES.  FIELD-NAMES must be a list of symbols and must not contain names already used by PARENT or one of its supertypes.

Exception type objects are record type objects, and as such, one can use record-constructor on an exception type to get its constructor. The constructor will take as many arguments as the exception has fields (including supertypes).  See Records.

However, record-predicate and record-accessor aren't usually what you want to use as exception type predicates and field accessors.  The reason is, instances of exception types can be composed into compound exceptions.  Exception accessors should pick out the specific component of a compound exception, and then access the field on that specific component.

 -- Scheme Procedure: make-exception exceptions ...
     Return an exception object composed of EXCEPTIONS.

 -- Scheme Procedure: exception? obj
     Return true if OBJ is an exception object.

 -- Scheme Procedure: exception-predicate type
     Return a procedure that will return true if its argument is a simple exception that is an instance of TYPE, or a compound exception composed of such an instance.

 -- Scheme Procedure: exception-accessor rtd proc
     Return a procedure that will tail-call PROC on an instance of the exception type RTD, or on the component of a compound exception that is an instance of RTD.

Compound exceptions are useful to separately express the different aspects of a situation.  For example, compound exceptions allow a programmer to say that ``this situation is a programming error, and also here's a useful message to show to the user, and here are some relevant objects that can give more information about the error''.  This error could be composed of instances of the &programming-error, &message, and &irritants exception types.

The subtyping relationship in exceptions is useful to let different-but-similar situations to be treated the same; for example there are many varieties of programming errors (for example, divide-by-zero or type mismatches), but perhaps there are common ways that the user would like to handle them all, and that common way might be different than how one might handle an error originating outside the program (for example, a file-not-found error).

The standard exception hierarchy in Guile takes its cues from R6RS, though the names of some of the types are different.  See rnrs exceptions, for more details.

To have access to Guile's exception type hierarchy, import the (ice-9 exceptions) module:

     (use-modules (ice-9 exceptions))

The following diagram gives an overview of the standard exception type hierarchy.

     &exception
     |- &warning
     |- &message
     |- &irritants
     |- &origin
     \- &error
        |- &external-error
        \- &programming-error
           |- &assertion-failure
           |- &non-continuable
           |- &implementation-restriction
           |- &lexical
           |- &syntax
           \- &undefined-variable

 -- Exception Type: &warning
     An exception type denoting warnings.  These are usually raised using #:continuable? #t; see the raise-exception documentation for more.

 -- Scheme Procedure: make-warning
 -- Scheme Procedure: warning? obj
     Constructor and predicate for &warning exception objects.

 -- Exception Type: &message message
     An exception type that provides a message to display to the user. Usually used as a component of a compound exception.

 -- Scheme Procedure: make-exception-with-message message
 -- Scheme Procedure: exception-with-message? obj
 -- Scheme Procedure: exception-message exn
     Constructor, predicate, and accessor for &message exception objects.

 -- Exception Type: &irritants irritants
     An exception type that provides a list of objects that were unexpected in some way.  Usually used as a component of a compound exception.

 -- Scheme Procedure: make-exception-with-irritants irritants
 -- Scheme Procedure: exception-with-irritants? obj
 -- Scheme Procedure: exception-irritants exn
     Constructor, predicate, and accessor for &irritants exception objects.

 -- Exception Type: &origin origin
     An exception type that indicates the origin of an exception, typically expressed as a procedure name, as a symbol.  Usually used as a component of a compound exception.

 -- Scheme Procedure: make-exception-with-origin origin
 -- Scheme Procedure: exception-with-origin? obj
 -- Scheme Procedure: exception-origin exn
     Constructor, predicate, and accessor for &origin exception objects.

 -- Exception Type: &error
     An exception type denoting errors: situations that are not just exceptional, but wrong.

 -- Scheme Procedure: make-error
 -- Scheme Procedure: error? obj
     Constructor and predicate for &error exception objects.

 -- Exception Type: &external-error
     An exception type denoting errors that proceed from the interaction of the program with the world, for example a ``file not found'' error.

 -- Scheme Procedure: make-external-error
 -- Scheme Procedure: external-error? obj
     Constructor and predicate for &external-error exception objects.

 -- Exception Type: &programming-error
     An exception type denoting errors that proceed from inside a program: type mismatches and so on.

 -- Scheme Procedure: make-programming-error
 -- Scheme Procedure: programming-error? obj
     Constructor and predicate for &programming-error exception objects.

 -- Exception Type: &non-continuable
     An exception type denoting errors that proceed from inside a program: type mismatches and so on.

 -- Scheme Procedure: make-non-continuable-error
 -- Scheme Procedure: non-continuable-error? obj
     Constructor and predicate for &non-continuable exception objects.

 -- Exception Type: &lexical
     An exception type denoting lexical errors, for example unbalanced parentheses.

 -- Scheme Procedure: make-lexical-error
 -- Scheme Procedure: lexical-error? obj
     Constructor and predicate for &lexical exception objects.

 -- Exception Type: &syntax form subform
     An exception type denoting syntax errors, for example a cond expression with invalid syntax.  The FORM field indicates the form containing the error, and SUBFORM indicates the unexpected subcomponent, or #f if unavailable.

 -- Scheme Procedure: make-syntax-error form subform
 -- Scheme Procedure: syntax-error? obj
 -- Scheme Procedure: syntax-error-form exn
 -- Scheme Procedure: syntax-error-subform exn
     Constructor, predicate, and accessors for &syntax exception objects.

 -- Exception Type: &undefined-variable
     An exception type denoting undefined variables.

 -- Scheme Procedure: make-undefine-variable-error
 -- Scheme Procedure: undefined-variable-error? obj
     Constructor and predicate for &undefined-variable exception objects.

Incidentally, the (ice-9 exceptions) module also includes a define-exception-type macro that can be used to conveniently add new exception types to the hierarchy.

 -- Syntax: define-exception-type name parent
     constructor predicate
     (field accessor) ...
     Define NAME to be a new exception type, inheriting from PARENT.  Define CONSTRUCTOR and PREDICATE to be the exception constructor and predicate, respectively, and define an ACCESSOR for each FIELD.

Raising and Handling Exceptions
...............................

An exception object describes an exceptional situation.  To bring that description to the attention of the user or to handle the situation programmatically, the first step is to raise the exception.

 -- Scheme Procedure: raise-exception obj [#:continuable?=#f]
     Raise an exception by invoking the current exception handler on OBJ. The handler is called with a continuation whose dynamic environment is that of the call to raise, except that the current exception handler is the one that was in place when the handler being called was installed.

     If CONTINUABLE? is true, the handler is invoked in tail position relative to the raise-exception call.  Otherwise if the handler returns, a non-continuable exception of type &non-continuable is raised in the same dynamic environment as the handler.

As the above description notes, Guile has a notion of a current exception handler.  At the REPL, this exception handler may enter a recursive debugger; in a standalone program, it may simply print a representation of the error and exit.

To establish an exception handler within the dynamic extent of a call, use with-exception-handler.

 -- Scheme Procedure: with-exception-handler handler thunk
     [#:unwind?=#f] [#:unwind-for-type=#t]
     Establish HANDLER, a procedure of one argument, as the current exception handler during the dynamic extent of invoking THUNK.

     If raise-exception is called during the dynamic extent of invoking THUNK, HANDLER will be invoked on the argument of raise-exception.

There are two kinds of exception handlers: unwinding and non-unwinding.

By default, exception handlers are non-unwinding.  Unless with-exception-handler was invoked with #:unwind? #t, exception handlers are invoked within the continuation of the error, without unwinding the stack.  The dynamic environment of the handler call will be that of the raise-exception call, with the difference that the current exception handler will be ``unwound'' to the \"outer\" handler (the one that was in place when the corresponding with-exception-handler was called).

However, it's often the case that one would like to handle an exception by unwinding the computation to an earlier state and running the error handler there.  After all, unless the raise-exception call is continuable, the exception handler needs to abort the continuation.  To support this use case, if with-exception-handler was invoked with #:unwind? #t is true, raise-exception will first unwind the stack by invoking an escape continuation (see call/ec), and then invoke the handler with the continuation of the with-exception-handler call.

Finally, one more wrinkle: for unwinding exception handlers, it can be useful to Guile if it can determine whether an exception handler would indeed handle a particular exception or not.  This is especially the case for exceptions raised in resource-exhaustion scenarios like stack-overflow or out-of-memory, where you want to immediately shrink resource use before recovering.  See Stack Overflow.  For this purpose, the #:unwind-for-type keyword argument allows users to specify the kind of exception handled by an exception handler; if #t, all exceptions will be handled; if an exception type object, only exceptions of that type will be handled; otherwise if a symbol, only that exceptions with the given exception-kind will be handled.

Throw and Catch
...............

Guile only adopted with-exception-handler and raise-exception as its primary exception-handling facility in 2019.  Before then, exception handling was fundamentally based on three other primitives with a somewhat more complex interface:  catch, with-throw-handler, and throw.

 -- Scheme Procedure: catch key thunk handler [pre-unwind-handler]
 -- C Function: scm_catch_with_pre_unwind_handler (key, thunk, handler, pre_unwind_handler)
 -- C Function: scm_catch (key, thunk, handler)
     Establish an exception handler during the dynamic extent of the call to THUNK.  KEY is either #t, indicating that all exceptions should be handled, or a symbol, restricting the exceptions handled to those having the KEY as their exception-kind.

     If THUNK executes normally, meaning without throwing any exceptions, the handler procedures are not called at all and the result of the thunk call is the result of the catch.  Otherwise if an exception is thrown that matches KEY, HANDLER is called with the continuation of the catch call.

Given the discussion from the previous section, it is most precise and concise to specify what catch does by expressing it in terms of with-exception-handler.  Calling catch with the three arguments is the same as:

     (define (catch key thunk handler)
       (with-exception-handler
        (lambda (exn)
          (apply handler (exception-kind exn) (exception-args exn)))
        thunk
        #:unwind? #t
        #:unwind-for-type key))

By invoking with-exception-handler with #:unwind? #t, catch sets up an escape continuation that will be invoked in an exceptional situation before the handler is called.

If catch is called with four arguments, then the use of THUNK should be replaced with:

        (lambda ()
          (with-throw-handler key thunk pre-unwind-handler))

As can be seen above, if a pre-unwind-handler is passed to catch, it's like calling with-throw-handler inside the body thunk.

with-throw-handler is the second of the older primitives, and is used to be able to intercept an exception that is being thrown before the stack is unwound.  This could be to clean up some related state, to print a backtrace, or to pass information about the exception to a debugger, for example.

 -- Scheme Procedure: with-throw-handler key thunk handler
 -- C Function: scm_with_throw_handler (key, thunk, handler)
     Add HANDLER to the dynamic context as a throw handler for key KEY, then invoke THUNK.

It's not possible to exactly express with-throw-handler in terms of with-exception-handler, but we can get close.

     (define (with-throw-handler key thunk handler)
       (with-exception-handler
        (lambda (exn)
          (when (or (eq? key #t) (eq? key (exception-kind exn)))
            (apply handler (exception-kind exn) (exception-args exn)))
          (raise-exception exn))
        thunk))

As you can see, unlike in the case of catch, the handler for with-throw-handler is invoked within the continuation of raise-exception, before unwinding the stack.  If the throw handler returns normally, the exception will be re-raised, to be handled by the next exception handler.

The special wrinkle of with-throw-handler that can't be shown above is that if invoking the handler causes a raise-exception instead of completing normally, the exception is thrown in the original dynamic environment of the raise-exception.  Any inner exception handler will get another shot at handling the exception. Here is an example to illustrate this behavior:

     (catch 'a
       (lambda ()
         (with-throw-handler 'b
           (lambda ()
             (catch 'a
               (lambda ()
                 (throw 'b))
               inner-handler))
           (lambda (key . args)
             (throw 'a))))
       outer-handler)

This code will call inner-handler and then continue with the continuation of the inner catch.

Finally, we get to throw, which is the older equivalent to raise-exception.

 -- Scheme Procedure: throw key arg ...
 -- C Function: scm_throw (key, args)
     Raise an exception with kind KEY and arguments ARGS. KEY is a symbol, denoting the ``kind'' of the exception.

Again, we can specify what throw does by expressing it in terms of raise-exception.

     (define (throw key . args)
       (raise-exception (make-exception-from-throw key args)))

At this point, we should mention the primitive that manage the relationship between structured exception objects throw.

 -- Scheme Procedure: make-exception-from-throw key args
     Create an exception object for the given KEY and ARGS passed to throw.  This may be a specific type of exception, for example &programming-error; Guile maintains a set of custom transformers for the various KEY values that have been used historically.

 -- Scheme Procedure: exception-kind exn
     If EXN is an exception created via make-exception-from-throw, return the corresponding KEY for the exception.  Otherwise, unless EXN is an exception of a type with a known mapping to throw, return the symbol %exception.

 -- Scheme Procedure: exception-args exn
     If EXN is an exception created via make-exception-from-throw, return the corresponding ARGS for the exception.  Otherwise, unless EXN is an exception of a type with a known mapping to throw, return (list EXN).

Exceptions and C
................

There are some specific versions of Guile's original catch and with-throw-handler exception-handling primitives that are still widely used in C code.

 -- 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)
 -- C Function: SCM scm_internal_catch (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)
     The above scm_catch_with_pre_unwind_handler and scm_catch take Scheme procedures as body and handler arguments. scm_c_catch and scm_internal_catch are equivalents taking C functions.

     BODY is called as BODY (BODY_DATA) with a catch on exceptions of the given TAG type.  If an exception is caught, PRE_UNWIND_HANDLER and HANDLER are called as HANDLER (HANDLER_DATA, KEY, ARGS). KEY and ARGS are the SCM key and argument list from the throw.

     BODY and HANDLER should have the following prototypes. scm_t_catch_body and scm_t_catch_handler are pointer typedefs for these.

          SCM body (void *data);
          SCM handler (void *data, SCM key, SCM args);

     The BODY_DATA and HANDLER_DATA parameters are passed to the respective calls so an application can communicate extra information to those functions.

     If the data consists of an SCM object, care should be taken that it isn't garbage collected while still required.  If the SCM is a local C variable, one way to protect it is to pass a pointer to that variable as the data parameter, since the C compiler will then know the value must be held on the stack.  Another way is to use scm_remember_upto_here_1 (see Foreign Object Memory Management).

 -- 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)
     The above scm_with_throw_handler takes Scheme procedures as body (thunk) and handler arguments.  scm_c_with_throw_handler is an equivalent taking C functions.  See scm_c_catch (see Exceptions and C) for a description of the parameters, the behaviour however of course follows with-throw-handler.

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.

 -- Scheme Procedure: error msg arg ...
     Raise an error with key misc-error and a message constructed by displaying MSG and writing ARG ....

 -- Scheme Procedure: scm-error key subr message args data
 -- C Function: scm_error_scm (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; If KEY is out-of-range, wrong-type-arg, or keyword-argument-error, it is a list containing the bad value; otherwise it will usually be #f.

 -- Scheme Procedure: strerror err
 -- C Function: scm_strerror (err)
     Return the Unix error message corresponding to ERR, an integer errno value.

     When setlocale has been called (see Locales), the message is in the language and charset of LC_MESSAGES.  (This is done by the C library.)

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

Dynamic Wind
------------

For Scheme code, the fundamental procedure to react to non-local entry and exits of dynamic contexts is dynamic-wind.  C code could use scm_internal_dynamic_wind, but since C does not allow the convenient construction of anonymous procedures that close over lexical variables, this will be, well, inconvenient.

Therefore, Guile offers the functions scm_dynwind_begin and scm_dynwind_end to delimit a dynamic extent.  Within this dynamic extent, which is called a dynwind context, you can perform various dynwind actions that control what happens when the dynwind context is entered or left.  For example, you can register a cleanup routine with scm_dynwind_unwind_handler that is executed when the context is left.  There are several other more specialized dynwind actions as well, for example to temporarily block the execution of asyncs or to temporarily change the current output port.  They are described elsewhere in this manual.

Here is an example that shows how to prevent memory leaks.

     /* Suppose there is a function called FOO in some library that you
        would like to make available to Scheme code (or to C code that
        follows the Scheme conventions).

        FOO takes two C strings and returns a new string.  When an error has
        occurred in FOO, it returns NULL.
     */

     char *foo (char *s1, char *s2);

     /* SCM_FOO interfaces the C function FOO to the Scheme way of life.
        It takes care to free up all temporary strings in the case of
        non-local exits.
      */

     SCM
     scm_foo (SCM s1, SCM s2)
     {
       char *c_s1, *c_s2, *c_res;

       scm_dynwind_begin (0);

       c_s1 = scm_to_locale_string (s1);

       /* Call 'free (c_s1)' when the dynwind context is left.
       */
       scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY);

       c_s2 = scm_to_locale_string (s2);

       /* Same as above, but more concisely.
       */
       scm_dynwind_free (c_s2);

       c_res = foo (c_s1, c_s2);
       if (c_res == NULL)
         scm_report_out_of_memory ();

       scm_dynwind_end ();

       return scm_take_locale_string (res);
     }

 -- Scheme Procedure: dynamic-wind in_guard thunk out_guard
 -- C Function: scm_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 dynamic extent of the dynamic-wind expression is escaped non-locally, OUT_GUARD is called.  If the dynamic extent 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

 -- C Type: scm_t_dynwind_flags
     This is an enumeration of several flags that modify the behavior of scm_dynwind_begin.  The flags are listed in the following table.

     SCM_F_DYNWIND_REWINDABLE
          The dynamic context is rewindable.  This means that it can be reentered non-locally (via the invocation of a continuation).  The default is that a dynwind context can not be reentered non-locally.

 -- C Function: void scm_dynwind_begin (scm_t_dynwind_flags flags)
     The function scm_dynwind_begin starts a new dynamic context and makes it the `current' one.

     The FLAGS argument determines the default behavior of the context.  Normally, use 0.  This will result in a context that can not be reentered with a captured continuation.  When you are prepared to handle reentries, include SCM_F_DYNWIND_REWINDABLE in FLAGS.

     Being prepared for reentry means that the effects of unwind handlers can be undone on reentry.  In the example above, we want to prevent a memory leak on non-local exit and thus register an unwind handler that frees the memory.  But once the memory is freed, we can not get it back on reentry.  Thus reentry can not be allowed.

     The consequence is that continuations become less useful when non-reentrant contexts are captured, but you don't need to worry about that too much.

     The context is ended either implicitly when a non-local exit happens, or explicitly with scm_dynwind_end.  You must make sure that a dynwind context is indeed ended properly.  If you fail to call scm_dynwind_end for each scm_dynwind_begin, the behavior is undefined.

 -- C Function: void scm_dynwind_end ()
     End the current dynamic context explicitly and make the previous one current.

 -- C Type: scm_t_wind_flags
     This is an enumeration of several flags that modify the behavior of scm_dynwind_unwind_handler and scm_dynwind_rewind_handler.  The flags are listed in the following table.

     SCM_F_WIND_EXPLICITLY
          The registered action is also carried out when the dynwind context is entered or left locally.

 -- C Function: void scm_dynwind_unwind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
 -- C Function: void scm_dynwind_unwind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
     Arranges for FUNC to be called with DATA as its arguments when the current context ends implicitly.  If FLAGS contains SCM_F_WIND_EXPLICITLY, FUNC is also called when the context ends explicitly with scm_dynwind_end.

     The function scm_dynwind_unwind_handler_with_scm takes care that DATA is protected from garbage collection.

 -- C Function: void scm_dynwind_rewind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
 -- C Function: void scm_dynwind_rewind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
     Arrange for FUNC to be called with DATA as its argument when the current context is restarted by rewinding the stack.  When FLAGS contains SCM_F_WIND_EXPLICITLY, FUNC is called immediately as well.

     The function scm_dynwind_rewind_handler_with_scm takes care that DATA is protected from garbage collection.

 -- C Function: void scm_dynwind_free (void *mem)
     Arrange for MEM to be freed automatically whenever the current context is exited, whether normally or non-locally. scm_dynwind_free (mem) is an equivalent shorthand for scm_dynwind_unwind_handler (free, mem, SCM_F_WIND_EXPLICITLY).

Fluids and Dynamic States
-------------------------

A fluid is a variable whose value is associated with the dynamic extent of a function call.  In the same way that an operating system runs a process with a given set of current input and output ports (or file descriptors), in Guile you can arrange to call a function while binding a fluid to a particular value.  That association between fluid and value will exist during the dynamic extent of the function call.

Fluids are therefore a building block for implementing dynamically scoped variables.  Dynamically scoped variables are useful when you want to set a variable to a value during some dynamic extent in the execution of your program and have them revert to their original value when the control flow is outside of this dynamic extent.  See the description of with-fluids below for details.  This association between fluids, values, and dynamic extents is robust to multiple entries (as when a captured continuation is invoked more than once) and early exits (for example, when throwing exceptions).

Guile uses fluids to implement parameters (see Parameters).  Usually you just want to use parameters directly.  However it can be useful to know what a fluid is and how it works, so that's what this section is about.

The current set of fluid-value associations can be captured in a dynamic state object.  A dynamic extent is simply that: a snapshot of the current fluid-value associations.  Guile users can capture the current dynamic state with current-dynamic-state and restore it later via with-dynamic-state or similar procedures. This facility is especially useful when implementing lightweight thread-like abstractions.

New fluids are created with make-fluid and fluid? is used for testing whether an object is actually a fluid.  The values stored in a fluid can be accessed with fluid-ref and fluid-set!.

See Thread Local Variables, for further notes on fluids, threads, parameters, and dynamic states.

 -- Scheme Procedure: make-fluid [dflt]
 -- C Function: scm_make_fluid ()
 -- C Function: scm_make_fluid_with_default (dflt)
     Return a newly created fluid, whose initial value is DFLT, or #f if DFLT is not given. Fluids are objects that can hold one value per dynamic state.  That is, modifications to this value are only visible to code that executes with the same dynamic state as the modifying code.  When a new dynamic state is constructed, it inherits the values from its parent.  Because each thread normally executes with its own dynamic state, you can use fluids for thread local storage.

 -- Scheme Procedure: make-unbound-fluid
 -- C Function: scm_make_unbound_fluid ()
     Return a new fluid that is initially unbound (instead of being implicitly bound to some definite value).

 -- Scheme Procedure: fluid? obj
 -- C Function: scm_fluid_p (obj)
     Return #t if OBJ is a fluid; otherwise, return #f.

 -- Scheme Procedure: fluid-ref fluid
 -- C Function: scm_fluid_ref (fluid)
     Return the value associated with FLUID in the current dynamic root.  If FLUID has not been set, then return its default value. Calling fluid-ref on an unbound fluid produces a runtime error.

 -- Scheme Procedure: fluid-set! fluid value
 -- C Function: scm_fluid_set_x (fluid, value)
     Set the value associated with FLUID in the current dynamic root.

 -- Scheme Procedure: fluid-ref* fluid depth
 -- C Function: scm_fluid_ref_star (fluid, depth)
     Return the DEPTHth oldest value associated with FLUID in the current thread.  If DEPTH equals or exceeds the number of values that have been assigned to FLUID, return the default value of the fluid.  (fluid-ref* f 0) is equivalent to (fluid-ref f).

     fluid-ref* is useful when you want to maintain a stack-like structure in a fluid, such as the stack of current exception handlers. Using fluid-ref* instead of an explicit stack allows any partial continuation captured by call-with-prompt to only capture the bindings made within the limits of the prompt instead of the entire continuation.  See Prompts, for more on delimited continuations.

 -- Scheme Procedure: fluid-unset! fluid
 -- C Function: scm_fluid_unset_x (fluid)
     Disassociate the given fluid from any value, making it unbound.

 -- Scheme Procedure: fluid-bound? fluid
 -- C Function: scm_fluid_bound_p (fluid)
     Returns #t if the given fluid is bound to a value, otherwise #f.

with-fluids* temporarily changes the values of one or more fluids, so that the given procedure and each procedure called by it access the given values.  After the procedure returns, the old values are restored.

 -- Scheme Procedure: with-fluid* fluid value thunk
 -- C Function: scm_with_fluid (fluid, value, thunk)
     Set FLUID to VALUE temporarily, and call THUNK. THUNK must be a procedure with no argument.

 -- Scheme Procedure: with-fluids* fluids values thunk
 -- C Function: scm_with_fluids (fluids, values, thunk)
     Set FLUIDS to VALUES temporary, and call THUNK. FLUIDS must be a list of fluids and VALUES must be the same number of their values to be applied.  Each substitution is done in the order given.  THUNK must be a procedure with no argument. It is called inside a dynamic-wind and the fluids are set/restored when control enter or leaves the established dynamic extent.

 -- Scheme Macro: with-fluids ((fluid value) ...) body
     Execute BODY (see Local Bindings) while each FLUID is set to the corresponding VALUE.  Both FLUID and VALUE are evaluated and FLUID must yield a fluid.  The body is executed inside a dynamic-wind and the fluids are set/restored when control enter or leaves the established dynamic extent.

 -- C Function: SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
 -- C Function: SCM scm_c_with_fluid (SCM fluid, SCM val, SCM (*cproc)(void *), void *data)
     The function scm_c_with_fluids is like scm_with_fluids except that it takes a C function to call instead of a Scheme thunk.

     The function scm_c_with_fluid is similar but only allows one fluid to be set instead of a list.

 -- C Function: void scm_dynwind_fluid (SCM fluid, SCM val)
     This function must be used inside a pair of calls to scm_dynwind_begin and scm_dynwind_end (see Dynamic Wind).  During the dynwind context, the fluid FLUID is set to VAL.

     More precisely, the value of the fluid is swapped with a `backup' value whenever the dynwind context is entered or left.  The backup value is initialized with the VAL argument.

 -- Scheme Procedure: dynamic-state? obj
 -- C Function: scm_dynamic_state_p (obj)
     Return #t if OBJ is a dynamic state object; return #f otherwise.

 -- C Procedure: int scm_is_dynamic_state (SCM obj)
     Return non-zero if OBJ is a dynamic state object; return zero otherwise.

 -- Scheme Procedure: current-dynamic-state
 -- C Function: scm_current_dynamic_state ()
     Return a snapshot of the current fluid-value associations as a fresh dynamic state object.

 -- Scheme Procedure: set-current-dynamic-state state
 -- C Function: scm_set_current_dynamic_state (state)
     Restore the saved fluid-value associations from STATE, replacing the current fluid-value associations.  Return the current fluid-value associatoins as a dynamic state object, as in current-dynamic-state.

 -- Scheme Procedure: with-dynamic-state state proc
 -- C Function: scm_with_dynamic_state (state, proc)
     Call PROC while the fluid bindings from STATE have been made current, saving the current fluid bindings.  When control leaves the invocation of PROC, restore the saved bindings, saving instead the fluid bindings from inside the call.  If control later re-enters PROC, restore those saved bindings, saving the current bindings, and so on.

 -- C Procedure: void scm_dynwind_current_dynamic_state (SCM state)
     Set the current dynamic state to STATE for the current dynwind context.  Like with-dynamic-state, but in terms of Guile's ``dynwind'' C API.

 -- C Procedure: void * scm_c_with_dynamic_state (SCM state, void *(*func)(void *), void *data)
     Like scm_with_dynamic_state, but call FUNC with DATA.

Parameters
----------

Parameters are Guile's facility for dynamically bound variables.

On the most basic level, a parameter object is a procedure.  Calling it with no arguments returns its value.  Calling it with one argument sets the value.

     (define my-param (make-parameter 123))
     (my-param) => 123
     (my-param 456)
     (my-param) => 456

The parameterize special form establishes new locations for parameters, those new locations having effect within the dynamic extent of the parameterize body.  Leaving restores the previous locations.  Re-entering (through a saved continuation) will again use the new locations.

     (parameterize ((my-param 789))
       (my-param)) => 789
     (my-param) => 456

Parameters are like dynamically bound variables in other Lisp dialects. They allow an application to establish parameter settings (as the name suggests) just for the execution of a particular bit of code, restoring when done.  Examples of such parameters might be case-sensitivity for a search, or a prompt for user input.

Global variables are not as good as parameter objects for this sort of thing.  Changes to them are visible to all threads, but in Guile parameter object locations are per-thread, thereby truly limiting the effect of parameterize to just its dynamic execution.

Passing arguments to functions is thread-safe, but that soon becomes tedious when there's more than a few or when they need to pass down through several layers of calls before reaching the point they should affect.  Introducing a new setting to existing code is often easier with a parameter object than adding arguments.

 -- Scheme Procedure: make-parameter init [converter]
     Return a new parameter object, with initial value INIT.

     If a CONVERTER is given, then a call (CONVERTER val) is made for each value set, its return is the value stored. Such a call is made for the INIT initial value too.

     A CONVERTER allows values to be validated, or put into a canonical form.  For example,

          (define my-param (make-parameter 123
                             (lambda (val)
                               (if (not (number? val))
                                   (error "must be a number"))
                               (inexact->exact val))))
          (my-param 0.75)
          (my-param) => 3/4

 -- library syntax: parameterize ((param value) ...) body1 body2 ...
     Establish a new dynamic scope with the given PARAMs bound to new locations and set to the given VALUEs.  BODY1 BODY2 ... is evaluated in that environment.  The value returned is that of last body form.

     Each PARAM is an expression which is evaluated to get the parameter object.  Often this will just be the name of a variable holding the object, but it can be anything that evaluates to a parameter.

     The PARAM expressions and VALUE expressions are all evaluated before establishing the new dynamic bindings, and they're evaluated in an unspecified order.

     For example,

          (define prompt (make-parameter "Type something: "))
          (define (get-input)
            (display (prompt))
            ...)

          (parameterize ((prompt "Type a number: "))
            (get-input)
            ...)

Parameter objects are implemented using fluids (see Fluids and Dynamic States), so each dynamic state has its own parameter locations.  That includes the separate locations when outside any parameterize form.  When a parameter is created it gets a separate initial location in each dynamic state, all initialized to the given INIT value.

New code should probably just use parameters instead of fluids, because the interface is better.  But for migrating old code or otherwise providing interoperability, Guile provides the fluid->parameter procedure:

 -- Scheme Procedure: fluid->parameter fluid [conv]
     Make a parameter that wraps a fluid.

     The value of the parameter will be the same as the value of the fluid. If the parameter is rebound in some dynamic extent, perhaps via parameterize, the new value will be run through the optional CONV procedure, as with any parameter.  Note that unlike make-parameter, CONV is not applied to the initial value.

As alluded to above, because each thread usually has a separate dynamic state, each thread has its own locations behind parameter objects, and changes in one thread are not visible to any other.  When a new dynamic state or thread is created, the values of parameters in the originating context are copied, into new locations.

Guile's parameters conform to SRFI-39 (see SRFI-39).

How to Handle Errors
--------------------

Guile is currently in a transition from its historical catch and throw error handling and signaling operators to the new structured exception facility; see Exceptions.  However in the meantime, here is some documentation on errors and the older catch and throw interface.

Errors are always thrown with a KEY and four arguments:

  * KEY: a symbol which indicates the type of error.  The symbols used by libguile are listed below.

  * SUBR: the name of the procedure from which the error is thrown, or #f.

  * MESSAGE: a string (possibly language and system dependent) describing the error.  The tokens ~A and ~S can be embedded within the message: they will be replaced with members of the ARGS list when the message is printed.  ~A indicates an argument printed using display, while ~S indicates an argument printed using write.  MESSAGE can also be #f, to allow it to be derived from the KEY by the error handler (may be useful if the KEY is to be thrown from both C and Scheme).

  * ARGS: a list of arguments to be used to expand ~A and ~S tokens in MESSAGE.  Can also be #f if no arguments are required.

  * REST: a list of any additional objects required. e.g., when the key is 'system-error, this contains the C errno value.  Can also be #f if no additional objects are required.

In addition to catch and throw, the following Scheme facilities are available:

 -- Scheme Procedure: display-error frame port subr message args rest
 -- C Function: scm_display_error (frame, port, subr, message, args, rest)
     Display an error message to the output port PORT. FRAME is the frame in which the error occurred, SUBR is the name of the procedure in which the error occurred and MESSAGE is the actual error message, which may contain formatting instructions. These will format the arguments in the list ARGS accordingly.  REST is currently ignored.

The following are the error keys defined by libguile and the situations in which they are used:

  * error-signal: thrown after receiving an unhandled fatal signal such as SIGSEGV, SIGBUS, SIGFPE etc.  The REST argument in the throw contains the coded signal number (at present this is not the same as the usual Unix signal number).

  * system-error: thrown after the operating system indicates an error condition.  The REST argument in the throw contains the errno value.

  * numerical-overflow: numerical overflow.

  * out-of-range: the arguments to a procedure do not fall within the accepted domain.

  * wrong-type-arg: an argument to a procedure has the wrong type.

  * wrong-number-of-args: a procedure was called with the wrong number of arguments.

  * memory-allocation-error: memory allocation error.

  * stack-overflow: stack overflow error.

  * regular-expression-syntax: errors generated by the regular expression library.

  * misc-error: other errors.

C Support
.........

In the following C functions, SUBR and MESSAGE parameters can be NULL to give the effect of #f described above.

 -- C Function: SCM scm_error (SCM KEY, const char *SUBR, const char *MESSAGE, SCM ARGS, SCM REST)
     Throw an error, as per scm-error (see Error Reporting).

 -- C Function: void scm_syserror (const char *SUBR)
 -- C Function: void scm_syserror_msg (const char *SUBR, const char *MESSAGE, SCM ARGS)
     Throw an error with key system-error and supply errno in the REST argument.  For scm_syserror the message is generated using strerror.

     Care should be taken that any code in between the failing operation and the call to these routines doesn't change errno.

 -- C Function: void scm_num_overflow (const char *SUBR)
 -- C Function: void scm_out_of_range (const char *SUBR, SCM BAD_VALUE)
 -- C Function: void scm_wrong_num_args (SCM PROC)
 -- C Function: void scm_wrong_type_arg (const char *SUBR, int ARGNUM, SCM BAD_VALUE)
 -- C Function: void scm_wrong_type_arg_msg (const char *SUBR, int ARGNUM, SCM BAD_VALUE, const char *EXPECTED)
 -- C Function: void scm_misc_error (const char *SUBR, const char *MESSAGE, SCM ARGS)
     Throw an error with the various keys described above.

     In scm_wrong_num_args, PROC should be a Scheme symbol which is the name of the procedure incorrectly invoked.  The other routines take the name of the invoked procedure as a C string.

     In scm_wrong_type_arg_msg, EXPECTED is a C string describing the type of argument that was expected.

     In scm_misc_error, MESSAGE is the error message string, possibly containing simple-format escapes (see Simple Output), and the corresponding arguments in the ARGS list.

Signalling Type Errors
......................

Every function visible at the Scheme level should aggressively check the types of its arguments, to avoid misinterpreting a value, and perhaps causing a segmentation fault.  Guile provides some macros to make this easier.

 -- Macro: void SCM_ASSERT (int TEST, SCM OBJ, unsigned int POSITION, const char *SUBR)
 -- Macro: void SCM_ASSERT_TYPE (int TEST, SCM OBJ, unsigned int POSITION, const char *SUBR, const char *EXPECTED)
     If TEST is zero, signal a ``wrong type argument'' error, attributed to the subroutine named SUBR, operating on the value OBJ, which is the POSITION'th argument of SUBR.

     In SCM_ASSERT_TYPE, EXPECTED is a C string describing the type of argument that was expected.

 -- Macro: int SCM_ARG1
 -- Macro: int SCM_ARG2
 -- Macro: int SCM_ARG3
 -- Macro: int SCM_ARG4
 -- Macro: int SCM_ARG5
 -- Macro: int SCM_ARG6
 -- Macro: int SCM_ARG7
     One of the above values can be used for POSITION to indicate the number of the argument of SUBR which is being checked. Alternatively, a positive integer number can be used, which allows to check arguments after the seventh.  However, for parameter numbers up to seven it is preferable to use SCM_ARGN instead of the corresponding raw number, since it will make the code easier to understand.

 -- Macro: int SCM_ARGn
     Passing a value of zero or SCM_ARGn for POSITION allows to leave it unspecified which argument's type is incorrect.  Again, SCM_ARGn should be preferred over a raw zero constant.

Continuation Barriers
---------------------

The non-local flow of control caused by continuations might sometimes not be wanted. You can use with-continuation-barrier to erect fences that continuations can not pass.

 -- Scheme Procedure: with-continuation-barrier proc
 -- C Function: scm_with_continuation_barrier (proc)
     Call PROC and return its result.  Do not allow the invocation of continuations that would leave or enter the dynamic extent of the call to with-continuation-barrier.  Such an attempt causes an error to be signaled.

     Throws (such as errors) that are not caught from within PROC are caught by with-continuation-barrier.  In that case, a short message is printed to the current error port and #f is returned.

     Thus, with-continuation-barrier returns exactly once.

 -- C Function: void * scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
     Like scm_with_continuation_barrier but call FUNC on DATA.  When an error is caught, NULL is returned.