summaryrefslogtreecommitdiffstats
path: root/doc/return.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/return.n')
-rw-r--r--doc/return.n118
1 files changed, 85 insertions, 33 deletions
diff --git a/doc/return.n b/doc/return.n
index 2ea381d..685e0be 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: return.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: return.n,v 1.3.18.1 2004/10/27 14:23:58 dkf Exp $
'\"
.so man.macros
.TH return n 7.0 Tcl "Tcl Built-In Commands"
@@ -23,43 +23,45 @@ Return immediately from the current procedure
(or top-level command or \fBsource\fR command),
with \fIstring\fR as the return value. If \fIstring\fR is not specified then
an empty string will be returned as result.
-
-.SH "EXCEPTIONAL RETURNS"
+.SH "EXCEPTIONAL RETURN CODES"
.PP
+In addition to the result of a procedure, the return
+code of a procedure may also be set by \fBreturn\fR
+through use of the \fB-code\fR option.
In the usual case where the \fB\-code\fR option isn't
-specified the procedure will return normally (its completion
-code will be TCL_OK).
+specified the procedure will return normally.
However, the \fB\-code\fR option may be used to generate an
exceptional return from the procedure.
\fICode\fR may have any of the following values:
-.TP 10
-\fBok\fR
-Normal return: same as if the option is omitted.
-.TP 10
-\fBerror\fR
-Error return: same as if the \fBerror\fR command were used to
-terminate the procedure, except for handling of \fBerrorInfo\fR
-and \fBerrorCode\fR variables (see below).
-.TP 10
-\fBreturn\fR
-The current procedure will return with a completion code of
-TCL_RETURN, so that the procedure that invoked it will return
-also.
-.TP 10
-\fBbreak\fR
-The current procedure will return with a completion code of
-TCL_BREAK, which will terminate the innermost nested loop in
-the code that invoked the current procedure.
-.TP 10
-\fBcontinue\fR
-The current procedure will return with a completion code of
-TCL_CONTINUE, which will terminate the current iteration of
-the innermost nested loop in the code that invoked the current
-procedure.
-.TP 10
+.TP 13
+\fBok (or 0)\fR
+Normal return: same as if the option is omitted. The return code
+of the procedure is 0 (\fBTCL_OK\fR).
+.TP 13
+\fBerror (1)\fR
+Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR).
+The procedure command behaves in its calling context as if it
+were the command \fBerror \fIresult\fR. See below for additional
+options.
+.TP 13
+\fBreturn (2)\fR
+The return code of the procedure is 2 (\fBTCL_RETURN\fR). The
+procedure command behaves in its calling context as if it
+were the command \fBreturn\fR (with no arguments).
+.TP 13
+\fBbreak (3)\fR
+The return code of the procedure is 3 (\fBTCL_BREAK\fR). The
+procedure command behaves in its calling context as if it
+were the command \fBbreak\fR.
+.TP 13
+\fBcontinue (4)\fR
+The return code of the procedure is 4 (\fBTCL_CONTINUE\fR). The
+procedure command behaves in its calling context as if it
+were the command \fBcontinue\fR.
+.TP 13
\fIvalue\fR
\fIValue\fR must be an integer; it will be returned as the
-completion code for the current procedure.
+return code for the current procedure.
.LP
The \fB\-code\fR option is rarely used.
It is provided so that procedures that implement
@@ -84,9 +86,59 @@ If the \fB\-errorcode\fR option is specified then \fIcode\fR provides
a value for the \fBerrorCode\fR variable.
If the option is not specified then \fBerrorCode\fR will
default to \fBNONE\fR.
+.SH EXAMPLES
+First, a simple example of using \fBreturn\fR to return from a
+procedure, interrupting the procedure body.
+.CS
+proc printOneLine {} {
+ puts "line 1" ;# This line will be printed.
+ \fBreturn\fR
+ puts "line 2" ;# This line will not be printed.
+}
+.CE
+.PP
+Next, an example of using \fBreturn\fR to set the value
+returned by the procedure.
+.CS
+proc returnX {} {\fBreturn\fR X}
+puts [returnX] ;# prints "X"
+.CE
+.PP
+Next, a more complete example, using \fBreturn -code error\fR
+to report invalid arguments.
+.CS
+proc factorial {n} {
+ if {![string is integer $n] || ($n < 0)} {
+ \fBreturn\fR -code error \\
+ "expected non-negative integer,\\
+ but got \\"$n\\""
+ }
+ if {$n < 2} {
+ \fBreturn\fR 1
+ }
+ set m [expr {$n - 1}]
+ set code [catch {factorial $m} factor]
+ if {$code != 0} {
+ \fBreturn\fR -code $code $factor
+ }
+ set product [expr {$n * $factor}]
+ if {$product < 0} {
+ \fBreturn\fR -code error \\
+ "overflow computing factorial of $n"
+ }
+ \fBreturn\fR $product
+}
+.CE
+.PP
+Next, a procedure replacement for \fBbreak\fR.
+.CS
+proc myBreak {} {
+ \fBreturn\fR -code break
+}
+.CE
.SH "SEE ALSO"
-break(n), continue(n), error(n), proc(n)
+break(n), catch(n), continue(n), error(n), proc(n), source(n), tclvars(n)
.SH KEYWORDS
-break, continue, error, procedure, return
+break, catch, continue, error, procedure, return