diff options
Diffstat (limited to 'tcl8.6/doc/catch.n')
| -rw-r--r-- | tcl8.6/doc/catch.n | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/tcl8.6/doc/catch.n b/tcl8.6/doc/catch.n new file mode 100644 index 0000000..d43a7ec --- /dev/null +++ b/tcl8.6/doc/catch.n @@ -0,0 +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. +'\" +.TH catch n "8.5" Tcl "Tcl Built-In Commands" +.so man.macros +.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?\fIresultVarName\fR? ?\fIoptionsVarName\fR? +.BE +.SH DESCRIPTION +.PP +The \fBcatch\fR command may be used to prevent errors from aborting command +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 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 +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 +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 { [\fBcatch\fR {open $someFile w} fid] } { + puts stderr "Could not open $someFile for writing\en$fid" + exit 1 +} +.CE +.PP +There are more complex examples of \fBcatch\fR usage in the +documentation for the \fBreturn\fR command. +.SH "SEE ALSO" +break(n), continue(n), dict(n), error(n), errorCode(n), errorInfo(n), info(n), +return(n) +.SH KEYWORDS +catch, error, exception +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |