diff options
Diffstat (limited to 'doc/catch.n')
| -rw-r--r-- | doc/catch.n | 62 |
1 files changed, 46 insertions, 16 deletions
diff --git a/doc/catch.n b/doc/catch.n index 17b5c1d..23771f9 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -5,10 +5,10 @@ '\" 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.2 1998/09/14 18:39:51 stanton Exp $ +'\" RCS: @(#) $Id: catch.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ '\" .so man.macros -.TH catch n "" Tcl "Tcl Built-In Commands" +.TH catch n "8.0" Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -19,22 +19,52 @@ catch \- Evaluate script and trap exceptional returns .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 a TCL_OK code, regardless of -any errors that might occur while executing \fIscript\fR. The return -value from \fBcatch\fR is a decimal string giving the -code returned by the Tcl interpreter after executing \fIscript\fR. -This will be \fB0\fR (TCL_OK) if there were no errors in \fIscript\fR; -otherwise -it will have a non-zero 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 it gives the name of a variable; -\fBcatch\fR will set the variable to the string returned -from \fIscript\fR (either a result or an error message). +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, +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. +.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. .PP Note that \fBcatch\fR catches all exceptions, including those -generated by \fBbreak\fR and \fBcontinue\fR as well as errors. +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. + +.SH EXAMPLES + +The \fBcatch\fR command may be used in an \fBif\fR to branch based on +the success of a script. + +.DS +.CS +if { [catch {open $someFile w} fid] } { + puts stderr "Could not open $someFile for writing\\n$fid" + exit 1 +} +.CE +.DE +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. + +.DS +.CS +proc foo {} { + catch {expr {1 +- }} +} +.CE +.DE .SH KEYWORDS catch, error |