Caius - API

NAME

Error - fine-grained error handling facilities

EXAMPLE

package require Itcl
package require Error

::itcl::class MyError {
    inherit ::Exception

    constructor {msg} { ::Exception::constructor $msg } {}
    destructor {}
}

except {
    # ...
    raise MyError "something unexpected happened"
} e {
    TclError {
        puts "caught a native Tcl error"
    }
    RuntimeError {
        puts "handling a runtime error"

        # re-raise the error
        reraise $e
    }
    MyError {
        puts "handling my error type"
    }
} final {
    puts "always executed"
}

DESCRIPTION

The Error module provides facilities to raise and handle errors and exceptions. It also defines a number of base exception types.

API

raise class string: Raise an exception of type class with error message string.

In order to catch exceptions (or Tcl errors) that may occur during the execution of a code block, the block may be guarded with an except statement:

except {
  control_flow
} evar {
  ?class1 {
    handler_code
    ?reraise $evar?
  }?
  ...
  classN {
    handler_code
    ?reraise $evar?
  }
} ?final {
  control_flow
}?

The except command takes a minimum of three arguments:

the block of code to be executed,
the name of a variable for storing an exception object reference,
a list of exception types to catch and corresponding handler clauses.

If a regular Tcl error occurs inside a block guarded by except then it is automatically converted to an exception of type TclError (see also the example at the top). Inside a handler clause, the exception can be re-thrown with the reraise keyword.

Optionally the list of handlers can be followed by the keyword final and another code block which will be executed regardless of whether an exception occurred or not.

itcl::class Exception

The mother of all exceptions. All user-defined exceptions should directly or indirectly inherit from Exception.

constructor msg: Exceptions are generally not created directly, but rather by use of the raise command.
method msg: Return the error message stored with the exception object.

itcl::class RuntimeError

Inherits from Exception.

itcl::class ValueError

Inherits from RuntimeError.

itcl::class TimeoutError