diff options
Diffstat (limited to 'doc/return.n')
| -rw-r--r-- | doc/return.n | 234 |
1 files changed, 194 insertions, 40 deletions
diff --git a/doc/return.n b/doc/return.n index 25cf8b4..b08de4a 100644 --- a/doc/return.n +++ b/doc/return.n @@ -1,32 +1,45 @@ '\" '\" Copyright (c) 1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright) '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH return n 7.0 Tcl "Tcl Built-In Commands" +.TH return n 8.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -return \- Return from a procedure +return \- Return from a procedure, or set return code of a script .SH SYNOPSIS -\fBreturn \fR?\fB\-code \fIcode\fR? ?\fB\-errorinfo \fIinfo\fR? ?\fB\-errorcode\fI code\fR? ?\fIstring\fR? +\fBreturn \fR?\fIresult\fR? +.sp +\fBreturn \fR?\fB\-code \fIcode\fR? ?\fIresult\fR? +.sp +\fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR? .BE - .SH DESCRIPTION .PP -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. +In its simplest usage, the \fBreturn\fR command is used without options +in the body of a procedure to immediately return control to the caller +of the procedure. If a \fIresult\fR argument is provided, its value +becomes the result of the procedure passed back to the caller. +If \fIresult\fR is not specified then an empty string will be returned +to the caller as the result of the procedure. +.PP +The \fBreturn\fR command serves a similar function within script +files that are evaluated by the \fBsource\fR command. When \fBsource\fR +evaluates the contents of a file as a script, an invocation of +the \fBreturn\fR command will cause script evaluation +to immediately cease, and the value \fIresult\fR (or an empty string) +will be returned as the result of the \fBsource\fR command. .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 +through use of the \fB\-code\fR option. +In the usual case where the \fB\-code\fR option is not specified the procedure will return normally. However, the \fB\-code\fR option may be used to generate an exceptional return from the procedure. @@ -61,29 +74,135 @@ were the command \fBcontinue\fR. \fIValue\fR must be an integer; it will be returned as the return code for the current procedure. .LP -The \fB\-code\fR option is rarely used. -It is provided so that procedures that implement -new control structures can reflect exceptional conditions back to -their callers. -.PP -Two additional options, \fB\-errorinfo\fR and \fB\-errorcode\fR, -may be used to provide additional information during error -returns. -These options are ignored unless \fIcode\fR is \fBerror\fR. -.PP -The \fB\-errorinfo\fR option specifies an initial stack -trace for the \fBerrorInfo\fR variable; if it is not specified then -the stack trace left in \fBerrorInfo\fR will include the call to -the procedure and higher levels on the stack but it will not include -any information about the context of the error within the procedure. -Typically the \fIinfo\fR value is supplied from the value left -in \fBerrorInfo\fR after a \fBcatch\fR command trapped an error within -the procedure. -.PP -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. +When a procedure wants to signal that it has received invalid +arguments from its caller, it may use \fBreturn -code error\fR +with \fIresult\fR set to a suitable error message. Otherwise +usage of the \fBreturn -code\fR option is mostly limited to +procedures that implement a new control structure. +.PP +The \fBreturn \-code\fR command acts similarly within script +files that are evaluated by the \fBsource\fR command. During the +evaluation of the contents of a file as a script by \fBsource\fR, +an invocation of the \fBreturn \-code \fIcode\fR command will cause +the return code of \fBsource\fR to be \fIcode\fR. +.SH "RETURN OPTIONS" +.PP +.VS 8.5 +In addition to a result and a return code, evaluation of a command +in Tcl also produces a dictionary of return options. In general +usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR +become entries in the return options dictionary, and any values at all +are acceptable except as noted below. The \fBcatch\fR command may be +used to capture all of this information \(em the return code, the result, +and the return options dictionary \(em that arise from evaluation of a +script. +.VE 8.5 +.PP +As documented above, the \fB\-code\fR entry in the return options dictionary +receives special treatment by Tcl. There are other return options also +recognized and treated specially by Tcl. They are: +.TP +\fB\-errorcode \fIlist\fR +The \fB\-errorcode\fR option receives special treatment only when the value +of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value +is meant to be additional information about the error, +presented as a Tcl list for further processing by programs. +If no \fB\-errorcode\fR option is provided to \fBreturn\fR when +the \fB\-code error\fR option is provided, Tcl will set the value +of the \fB\-errorcode\fR entry in the return options dictionary +to the default value of \fBNONE\fR. The \fB\-errorcode\fR return +option will also be stored in the global variable \fBerrorCode\fR. +.TP +\fB\-errorinfo \fIinfo\fR +The \fB\-errorinfo\fR option receives special treatment only when the value +of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then \fIinfo\fR is the initial +stack trace, meant to provide to a human reader additional information +about the context in which the error occurred. The stack trace will +also be stored in the global variable \fBerrorInfo\fR. +If no \fB\-errorinfo\fR option is provided to \fBreturn\fR when +the \fB\-code error\fR option is provided, Tcl will provide its own +initial stack trace value in the entry for \fB\-errorinfo\fR. Tcl's +initial stack trace will include only the call to the procedure, and +stack unwinding will append information about higher stack levels, but +there will be no information about the context of the error within +the procedure. Typically the \fIinfo\fR value is supplied from +the value of \fB\-errorinfo\fR in a return options dictionary captured +by the \fBcatch\fR command (or from the copy of that information +stored in the global variable \fBerrorInfo\fR). +.TP +\fB\-level \fIlevel\fR +.VS 8.5 +The \fB\-level\fR and \fB\-code\fR options work together to set the return +code to be returned by one of the commands currently being evaluated. +The \fIlevel\fR value must be a non-negative integer representing a number +of levels on the call stack. It defines the number of levels up the stack +at which the return code of a command currently being evaluated should +be \fIcode\fR. If no \fB\-level\fR option is provided, the default value +of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the +current procedure returns to its caller, 1 level up the call stack. The +mechanism by which these options work is described in more detail below. +.VE 8.5 +.TP +\fB\-options \fIoptions\fR +.VS 8.5 +The value \fIoptions\fR must be a valid dictionary. The entries of that +dictionary are treated as additional \fIoption value\fR pairs for the +\fBreturn\fR command. +.VE 8.5 +.SH "RETURN CODE HANDLING MECHANISMS" +.PP +Return codes are used in Tcl to control program flow. A Tcl script +is a sequence of Tcl commands. So long as each command evaluation +returns a return code of \fBTCL_OK\fR, evaluation will continue to the next +command in the script. Any exceptional return code (non-\fBTCL_OK\fR) +returned by a command evaluation causes the flow on to the next +command to be interrupted. Script evaluation ceases, and the +exceptional return code from the command becomes the return code +of the full script evaluation. This is the mechanism by which +errors during script evaluation cause an interruption and unwinding +of the call stack. It is also the mechanism by which commands +like \fBbreak\fR, \fBcontinue\fR, and \fBreturn\fR cause script +evaluation to terminate without evaluating all commands in sequence. +.PP +Some of Tcl's built-in commands evaluate scripts as part of their +functioning. These commands can make use of exceptional return +codes to enable special features. For example, the built-in +Tcl commands that provide loops \(em such as \fBwhile\fR, \fBfor\fR, +and \fBforeach\fR \(em evaluate a script that is the body of the +loop. If evaluation of the loop body returns the return code +of \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR, the loop command can react in such +a way as to give the \fBbreak\fR and \fBcontinue\fR commands +their documented interpretation in loops. +.PP +.VS 8.5 +Procedure invocation also involves evaluation of a script, the body +of the procedure. Procedure invocation provides special treatment +when evaluation of the procedure body returns the return code +\fBTCL_RETURN\fR. In that circumstance, the \fB\-level\fR entry in the +return options dictionary is decremented. If after decrementing, +the value of the \fB\-level\fR entry is 0, then the value of +the \fB\-code\fR entry becomes the return code of the procedure. +If after decrementing, the value of the \fB\-level\fR entry is +greater than zero, then the return code of the procedure is +\fBTCL_RETURN\fR. If the procedure invocation occurred during the +evaluation of the body of another procedure, the process will +repeat itself up the call stack, decrementing the value of the +\fB\-level\fR entry at each level, so that the \fIcode\fR will +be the return code of the current command \fIlevel\fR levels +up the call stack. The \fBsource\fR command performs the +same handling of the \fBTCL_RETURN\fR return code, which explains +the similarity of \fBreturn\fR invocation during a \fBsource\fR +to \fBreturn\fR invocation within a procedure. +.PP +The return code of the \fBreturn\fR command itself triggers this +special handling by procedure invocation. If \fBreturn\fR +is provided the option \fB\-level 0\fR, then the return code +of the \fBreturn\fR command itself will be the value \fIcode\fR +of the \fB\-code\fR option (or \fBTCL_OK\fR by default). Any other value +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 \fBTCL_RETURN\fR, triggering a return from the enclosing procedure. +.VE 8.5 .SH EXAMPLES First, a simple example of using \fBreturn\fR to return from a procedure, interrupting the procedure body. @@ -107,9 +226,9 @@ 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\\"" + \fBreturn\fR -code error \e + "expected non-negative integer,\e + but got \e"$n\e"" } if {$n < 2} { \fBreturn\fR 1 @@ -121,7 +240,7 @@ proc factorial {n} { } set product [expr {$n * $factor}] if {$product < 0} { - \fBreturn\fR -code error \\ + \fBreturn\fR -code error \e "overflow computing factorial of $n" } \fBreturn\fR $product @@ -134,9 +253,44 @@ proc myBreak {} { \fBreturn\fR -code break } .CE - +.PP +.VS 8.5 +With the \fB\-level 0\fR option, \fBreturn\fR itself can serve +as a replacement for \fBbreak\fR. +.CS +interp alias {} Break {} \fBreturn\fR -level 0 -code break +.CE +.PP +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 + \fBreturn\fR -options $options $result +} +.CE +.PP +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 merge {-level 1} $args] + dict incr options -level + \fBreturn\fR -options $options $result +} +.CE +.VE 8.5 .SH "SEE ALSO" -break(n), catch(n), continue(n), error(n), proc(n), source(n), tclvars(n) - +break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n) .SH KEYWORDS break, catch, continue, error, procedure, return |