Re: examples for catch and throw

[Mark Galassi <rosalia@cygnus.com>]

The Guile reference manual (from the guile-doc snapshot) has the
following node on catch/throw (which I include) as well as some other
nodes on how libguile provides such services for C programmers.

File: guile-ref.info,  Node: Exceptions,  Next: Modules,  Prev: Keywords,  Up: Top

Exceptions
**********

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

 - primitive: throw KEY &rest 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.

 - 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 `%s' escapes.
     When an error is reported, these are replaced by formating the
     corresponding members of ARGS: `%s' formats using `display' and
     `%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 ERRNO
     Returns the Unix error message corresponding to ERRNO, an integer.

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

   It is traditional in Scheme to implement exception systems using
`call-with-current-continuation', but his has not been done, for
performance reasons.  The implementation of
`call-with-current-continuation' is a stack copying implementation.
This allows it to interact well with ordinary C code.  Unfortunately, a
stack-copying implementation can be slow - creating a new continuation
involves a block copy of the stack.

   Instead of using `call-with-current-continuation', the exception
primitives are implemented as built-ins that take advantage of the
*upward only* nature of exceptions.