diff options
Diffstat (limited to 'doc/catch.n')
| -rw-r--r-- | doc/catch.n | 66 |
1 files changed, 42 insertions, 24 deletions
diff --git a/doc/catch.n b/doc/catch.n index f2d5533..0e2ec04 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -1,18 +1,19 @@ '\" '\" Copyright (c) 1993-1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright) '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH catch n "8.0" Tcl "Tcl Built-In Commands" +.TH catch n "8.5" Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME catch \- Evaluate script and trap exceptional returns .SH SYNOPSIS -\fBcatch\fI script \fR?\fIvarName\fR? +\fBcatch\fI script \fR?\fIresultVarName\fR? ?\fIoptionsVarName\fR? .BE .SH DESCRIPTION @@ -35,44 +36,61 @@ new commands that return other integer values as return codes as well, and scripts that make use of the \fBreturn -code\fR command can also have return codes other than the five defined by Tcl. .PP -If the \fIvarName\fR argument is given, then the variable it names is +If the \fIresultVarName\fR argument is given, then the variable it names is set to the result of the script evaluation. When the return code from -the script is 1 (\fBTCL_ERROR\fR), the value stored in \fIvarName\fR is an error +the script is 1 (\fBTCL_ERROR\fR), the value stored in \fIresultVarName\fR is an error message. When the return code from the script is 0 (\fBTCL_OK\fR), the value stored in \fIresultVarName\fR is the value returned from \fIscript\fR. .PP -If \fIscript\fR does not raise an error, \fBcatch\fR will return 0 -(\fBTCL_OK\fR) and set the variable to the value returned from \fIscript\fR. +.VS 8.5 +If the \fIoptionsVarName\fR argument is given, then the variable it +names is set to a dictionary of return options returned by evaluation +of \fIscript\fR. Tcl specifies two entries that are always +defined in the dictionary: \fB\-code\fR and \fB\-level\fR. When +the return code from evaluation of \fIscript\fR is not \fBTCL_RETURN\fR, +the value of the \fB\-level\fR entry will be 0, and the value +of the \fB\-code\fR entry will be the same as the return code. +Only when the return code is \fBTCL_RETURN\fR will the values of +the \fB\-level\fR and \fB\-code\fR entries be something else, as +further described in the documentation for the \fBreturn\fR command. .PP -Note that \fBcatch\fR catches all exceptions, including those -generated by \fBbreak\fR and \fBcontinue\fR as well as errors. The -only errors that are not caught are syntax errors found when the -script is compiled. This is because the catch command only catches -errors during runtime. When the catch statement is compiled, the -script is compiled as well and any syntax errors will generate a Tcl -error. - +When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR, +three additional entries are defined in the dictionary of return options +stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, \fB\-errorcode\fR, +and \fB\-errorline\fR. The value of the \fB\-errorinfo\fR entry +is a formatted stack trace containing more information about +the context in which the error happened. The formatted stack +trace is meant to be read by a person. The value of +the \fB\-errorcode\fR entry is additional information about the +error stored as a list. The \fB\-errorcode\fR value is meant to +be further processed by programs, and may not be particularly +readable by people. The value of the \fB\-errorline\fR entry +is an integer indicating which line of \fIscript\fR was being +evaluated when the error occurred. The values of the \fB\-errorinfo\fR +and \fB\-errorcode\fR entries of the most recent error are also +available as values of the global variables \fB::errorInfo\fR +and \fB::errorCode\fR respectively. +.PP +Tcl packages may provide commands that set other entries in the +dictionary of return options, and the \fBreturn\fR command may be +used by scripts to set return options in addition to those defined +above. +.VE 8.5 .SH EXAMPLES The \fBcatch\fR command may be used in an \fBif\fR to branch based on the success of a script. .CS if { [\fBcatch\fR {open $someFile w} fid] } { - puts stderr "Could not open $someFile for writing\\n$fid" + puts stderr "Could not open $someFile for writing\en$fid" exit 1 } .CE .PP -The \fBcatch\fR command will not catch compiled syntax errors. The -first time proc \fBfoo\fR is called, the body will be compiled and a -Tcl error will be generated. -.CS -proc foo {} { - \fBcatch\fR {expr {1 +- }} -} -.CE +There are more complex examples of \fBcatch\fR usage in the +documentation for the \fBreturn\fR command. .SH "SEE ALSO" -break(n), continue(n), error(n), return(n), tclvars(n) +break(n), continue(n), dict(n), error(n), return(n), tclvars(n) .SH KEYWORDS catch, error |