diff options
Diffstat (limited to 'doc/catch.n')
| -rw-r--r-- | doc/catch.n | 132 |
1 files changed, 94 insertions, 38 deletions
diff --git a/doc/catch.n b/doc/catch.n index 01d0628..94fa5dd 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -1,69 +1,125 @@ '\" '\" 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. '\" -'\" RCS: @(#) $Id: catch.n,v 1.5 2000/09/07 14:27:46 poenitz Exp $ -'\" +.TH catch n "8.5" Tcl "Tcl Built-In Commands" .so man.macros -.TH catch n "8.0" 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 .PP The \fBcatch\fR command may be used to prevent errors from aborting command -interpretation. \fBCatch\fR calls the Tcl interpreter recursively to -execute \fIscript\fR, and always returns without raising an error, +interpretation. The \fBcatch\fR command calls the Tcl interpreter recursively +to execute \fIscript\fR, and always returns without raising an error, regardless of any errors that might occur while executing \fIscript\fR. .PP If \fIscript\fR raises an error, \fBcatch\fR will return a non-zero integer -value corresponding to one of the exceptional return codes (see tcl.h -for the definitions of code values). If the \fIvarName\fR argument is -given, then the variable it names is set to the error message from -interpreting \fIscript\fR. +value corresponding to the exceptional return code returned by evaluation +of \fIscript\fR. Tcl defines the normal return code from script +evaluation to be zero (0), or \fBTCL_OK\fR. Tcl also defines four exceptional +return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR), +and 4 (\fBTCL_CONTINUE\fR). Errors during evaluation of a script are indicated +by a return code of \fBTCL_ERROR\fR. The other exceptional return codes are +returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands +and in other special situations as documented. Tcl packages can define +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 \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 \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 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 -If \fIscript\fR does not raise an error, \fBcatch\fR will return 0 -(TCL_OK) and set the variable to the value returned from \fIscript\fR. +When the return code from evaluation of \fIscript\fR is +\fBTCL_ERROR\fR, four additional entries are defined in the dictionary +of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, +\fB\-errorcode\fR, \fB\-errorline\fR, and +.VS 8.6 +\fB\-errorstack\fR. +.VE 8.6 +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. +.VS 8.6 +The value of the \fB\-errorstack\fR entry is an +even-sized list made of token-parameter pairs accumulated while +unwinding the stack. The token may be +.QW \fBCALL\fR , +in which case the parameter is a list made of the proc name and arguments at +the corresponding level; or it may be +.QW \fBUP\fR , +in which case the parameter is +the relative level (as in \fBuplevel\fR) of the previous \fBCALL\fR. The +salient differences with respect to \fB\-errorinfo\fR are that: +.IP [1] +it is a machine-readable form that is amenable to processing with +[\fBforeach\fR {tok prm} ...], +.IP [2] +it contains the true (substituted) values passed to the functions, instead of +the static text of the calling sites, and +.IP [3] +it is coarser-grained, with only one element per stack frame (like procs; no +separate elements for \fBforeach\fR constructs for example). +.VE 8.6 .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. - +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. +.VS 8.6 +The value of the \fB\-errorstack\fR entry surfaces as \fBinfo errorstack\fR. +.VE 8.6 +.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. .SH EXAMPLES - +.PP The \fBcatch\fR command may be used in an \fBif\fR to branch based on the success of a script. - +.PP .CS -if { [catch {open $someFile w} fid] } { - puts stderr "Could not open $someFile for writing\\n$fid" +if { [\fBcatch\fR {open $someFile w} fid] } { + puts stderr "Could not open $someFile for writing\en$fid" exit 1 } .CE -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 {} { - catch {expr {1 +- }} -} -.CE - +.PP +There are more complex examples of \fBcatch\fR usage in the +documentation for the \fBreturn\fR command. .SH "SEE ALSO" -error(n), break(n), continue(n) - +break(n), continue(n), dict(n), error(n), errorCode(n), errorInfo(n), info(n), +return(n) .SH KEYWORDS -catch, error +catch, error, exception +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |