summaryrefslogtreecommitdiffstats
path: root/doc/catch.n
diff options
context:
space:
mode:
authorstanton <stanton>1999-04-16 00:46:29 (GMT)
committerstanton <stanton>1999-04-16 00:46:29 (GMT)
commit97464e6cba8eb0008cf2727c15718671992b913f (patch)
treece9959f2747257d98d52ec8d18bf3b0de99b9535 /doc/catch.n
parenta8c96ddb94d1483a9de5e340b740cb74ef6cafa7 (diff)
downloadtcl-97464e6cba8eb0008cf2727c15718671992b913f.zip
tcl-97464e6cba8eb0008cf2727c15718671992b913f.tar.gz
tcl-97464e6cba8eb0008cf2727c15718671992b913f.tar.bz2
merged tcl 8.1 branch back into the main trunk
Diffstat (limited to 'doc/catch.n')
-rw-r--r--doc/catch.n62
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