summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/catch.n5
-rw-r--r--doc/return.n97
2 files changed, 100 insertions, 2 deletions
diff --git a/doc/catch.n b/doc/catch.n
index 4d83c5d..043c3d8 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -6,7 +6,7 @@
'\" 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.6 2003/08/31 21:39:23 dgp Exp $
+'\" RCS: @(#) $Id: catch.n,v 1.7 2003/09/02 18:51:31 dgp Exp $
'\"
.so man.macros
.TH catch n "8.5" Tcl "Tcl Built-In Commands"
@@ -108,6 +108,9 @@ proc foo {} {
}
.CE
+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), return(n), tclvars(n)
diff --git a/doc/return.n b/doc/return.n
index 50407e9..7afe66c 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -6,7 +6,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.5 2003/09/02 16:48:22 dgp Exp $
+'\" RCS: @(#) $Id: return.n,v 1.6 2003/09/02 18:51:31 dgp Exp $
'\"
.so man.macros
.TH return n 8.5 Tcl "Tcl Built-In Commands"
@@ -201,6 +201,101 @@ for the \fB-level\fR option (including the default value of 1)
will cause the return code of the \fBreturn\fR command itself
to be TCL_RETURN, triggering a return from the enclosing procedure.
+.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.
+ return
+ puts "line 2" ;# This line will not be printed.
+}
+.CE
+
+Next, an example of using \fBreturn\fR to set the value
+returned by the procedure.
+
+.CS
+proc returnX {} {return X}
+puts [returnX] ;# prints "X"
+.CE
+
+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)} {
+ return -code error \\
+ "expected non-negative integer,\\
+ but got \\"$n\\""
+ }
+ if {$n < 2} {
+ return 1
+ }
+ set m [expr {$n - 1}]
+ set code [catch {factorial $m} factor]
+ if {$code != 0} {
+ return -code $code $factor
+ }
+ set product [expr {$n * $factor}]
+ if {$product < 0} {
+ return -code error \\
+ "overflow computing factorial of $n"
+ }
+ return $product
+}
+.CE
+
+Next, a procedure replacement for \fBbreak\fR.
+
+.CS
+proc myBreak {} {
+ return -code break
+}
+.CE
+
+With the \fB-level 0\fR option, \fBreturn\fR itself can serve
+as a replacement for \fBbreak\fR.
+
+.CS
+interp alias {} Break {} return -level 0 -code break
+.CE
+
+An example of using \fBcatch\fR and \fBreturn -options\fR to
+re-raise a caught error:
+
+.CS
+proc doSomething {} {
+ set resource [allocate]
+ catch {
+ # Long script of operations
+ # that might raise an error
+ } result options
+ deallocate $resource
+ return -options $options $result
+}
+.CE
+
+Finally an example of advanced use of the \fBreturn\fR options
+to create a procedure replacement for \fBreturn\fR itself:
+
+.CS
+proc myReturn {args} {
+ set result ""
+ if {[llength $args] % 2} {
+ set result [lindex $args end]
+ set args [lrange $args 0 end-1]
+ }
+ set options [dict create -level 1]
+ eval [list dict replace $options] $args
+ dict incr options -level
+ return -options $options $result
+}
+.CE
+
.SH "SEE ALSO"
break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)