NAME

       try - Trap and process errors and exceptions

SYNOPSIS

       try body ?handler...? ?finally script?
_________________________________________________________________

DESCRIPTION

       This command executes the script body and, depending on what the outcome of that script is
       (normal exit, error, or some other exceptional result), runs a handler script to deal with
       the  case.  Once  that  has  all happened, if the finally clause is present, the script it
       includes will be run and the result of the handler (or the body if no handler matched)  is
       allowed  to  continue  to  propagate. Note that the finally clause is processed even if an
       error occurs and irrespective of which, if any, handler is used.

       The handler clauses are each expressed  as  several  words,  and  must  have  one  of  the
       following forms:

       on code variableList script
              This  clause  matches  if  the evaluation of body completed with the exception code
              code. The code may be expressed as an integer  or  one  of  the  following  literal
              words:  ok,  error,  return,  break,  or continue. Those literals correspond to the
              integers 0 through 4 respectively.

       trap pattern variableList script
              This clause matches if the evaluation of body resulted in an error and  the  prefix
              of the -errorcode from the interpreter's status dictionary is equal to the pattern.
              The number of prefix words taken from the -errorcode is equal to the list-length of
              pattern,  and  inter-word  spaces are normalized in both the -errorcode and pattern
              before comparison.

       The variableList word in each handler is always interpreted as a list of  variable  names.
       If the first word of the list is present and non-empty, it names a variable into which the
       result of the evaluation of body (from the main try) will be placed; this will contain the
       human-readable  form  of  any  errors.  If the second word of the list is present and non-
       empty, it names a variable into which the options dictionary of  the  interpreter  at  the
       moment of completion of execution of body will be placed.

       The  script  word  of each handler is also always interpreted the same: as a Tcl script to
       evaluate if the clause is matched. If script is a literal “-” and the handler is  not  the
       last  one,  the  script  of  the  following handler is invoked instead (just like with the
       switch command).

       Note that handler clauses are matched against in order, and that the first matching one is
       always  selected.  At most one handler clause will selected. As a consequence, an on error
       will mask any subsequent trap in the try. Also note that on error is  equivalent  to  trap
       {}.

       If  an  exception  (i.e.  any  non-ok  result)  occurs during the evaluation of either the
       handler or the finally clause, the original exception's status dictionary will be added to
       the new exception's status dictionary under the -during key.

EXAMPLES

       Ensure that a file is closed no matter what:

              set f [open /some/file/name a]
              try {
                  puts $f "some message"
                  # ...
              } finally {
                  close $f
              }

       Handle different reasons for a file to not be openable for reading:

              try {
                  set f [open /some/file/name w]
              } trap {POSIX EISDIR} {} {
                  puts "failed to open /some/file/name: it's a directory"
              } trap {POSIX ENOENT} {} {
                  puts "failed to open /some/file/name: it doesn't exist"
              }

SEE ALSO

       catch(3tcl), error(3tcl), return(3tcl), throw(3tcl)

KEYWORDS

       cleanup, error, exception, final, resource management