diff options
| -rw-r--r-- | doc/catch.n | 5 | ||||
| -rw-r--r-- | doc/return.n | 97 |
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) |