DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(guile.info.gz) Catch

Info Catalog (guile.info.gz) Exception Terminology (guile.info.gz) Exceptions (guile.info.gz) Throw
 
 26.7.2 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'.
 
  -- Scheme Procedure: catch key thunk handler
  -- C Function: scm_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.
 
Info Catalog (guile.info.gz) Exception Terminology (guile.info.gz) Exceptions (guile.info.gz) Throw
automatically generated byinfo2html