try(3tcllib)					   Forward compatibility implementation of [try]				      try(3tcllib)

__________________________________________________________________________________________________________________________________________________

NAME

       try - try - Trap and process errors and exceptions

SYNOPSIS

       package require Tcl  8.5

       package require try  ?1?

       ::try body ?handler...? ?finally script?

_________________________________________________________________

DESCRIPTION

       This package provides a forward-compatibility implementation of Tcl 8.6's try/finally command (TIP 329), for Tcl 8.5. The code was directly
       pulled from Tcl 8.6 revision ?, when try/finally was implemented as Tcl procedure instead of in C.

       ::try body ?handler...? ?finally script?
	      This command executes the script body and, depending on what the outcome of that script is (normal exit, error, or some other excep-
	      tional  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  propa-
	      gate. 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 han-
		     dler 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 origi-
		     nal 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]
	      } 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"
	      }

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain bugs and other problems.  Please report such in the category  try	of
       the  Tcllib  SF	Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you may have for
       either package and/or documentation.

SEE ALSO

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

KEYWORDS

       cleanup, error, exception, final, resource management

CATEGORY

       Utility

COPYRIGHT

       Copyright (c) 2008 Donal K. Fellows, BSD licensed

try									 1							      try(3tcllib)