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