NAME

throw - Throw an exception

SYNOPSIS

throw type message
throw

DESCRIPTION

The throw command is used to report exceptional conditions (exceptions) from within a Tcl script. It is intended to be used in conjunction with the try command.

This command is similar to the Tcl built-in error command. It generates an error that is propagated through the call stack, until it is caught by a catch or try statement. The use of throw is compatible with standard Tcl error handling. Exceptions are regular Tcl errors, thus are compatible with existing code that uses standard error and catch mechanism.

In its first form, throw takes 2 arguments:

type
the exception type. This is an arbitrary Tcl string that indicates the type of the thrown exception. You can also declare the exception type to be a subtype of another by mean of the exception command
.
message
a human-readable description of the exception.
For example: will throw an exception of type MyException, and the description of the exception will be "something very strange just happened...".

The second form is used to re-throw the currently caught exception from within try blocks. It can be very useful when catch clauses want to further propagate the caught exception while keeping the original exception information (ie the errorInfo variable). A re-thrown exception looks like it wasn't caught by the try block. Invoking this form when no exception is currently being caught raises an error.

Throw uses the standard error handling mechanism by positionning the errorCode Tcl global variable and returning an error status. More precisely, it uses the return command with -code and -errorcode options. The return value uses the following format:

The errorCode variable uses this format: This format is very similar to those used by the Tcl core, such as POSIX or ARITH errors (see tclvars).

When thrown, the exception will be propagated until it reaches a catch or try statement. In the latter case, if the exception type matches one that is handled by the try statement, then the exception is caught, else its propagation goes on.

SEE ALSO

catch(n), error(n), return(n), try, exception

KEYWORDS

error, exception