1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Contributions from Don Porter, NIST, 2003. (not subject to US copyright) |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: return.n,v 1.19 2007/12/13 15:22:33 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH return n 8.5 Tcl "Tcl Built-In Commands" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | return \- Return from a procedure, or set return code of a script |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBreturn \fR?\fIresult\fR? |
---|
19 | .sp |
---|
20 | \fBreturn \fR?\fB\-code \fIcode\fR? ?\fIresult\fR? |
---|
21 | .sp |
---|
22 | \fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR? |
---|
23 | .BE |
---|
24 | .SH DESCRIPTION |
---|
25 | .PP |
---|
26 | In its simplest usage, the \fBreturn\fR command is used without options |
---|
27 | in the body of a procedure to immediately return control to the caller |
---|
28 | of the procedure. If a \fIresult\fR argument is provided, its value |
---|
29 | becomes the result of the procedure passed back to the caller. |
---|
30 | If \fIresult\fR is not specified then an empty string will be returned |
---|
31 | to the caller as the result of the procedure. |
---|
32 | .PP |
---|
33 | The \fBreturn\fR command serves a similar function within script |
---|
34 | files that are evaluated by the \fBsource\fR command. When \fBsource\fR |
---|
35 | evaluates the contents of a file as a script, an invocation of |
---|
36 | the \fBreturn\fR command will cause script evaluation |
---|
37 | to immediately cease, and the value \fIresult\fR (or an empty string) |
---|
38 | will be returned as the result of the \fBsource\fR command. |
---|
39 | .SH "EXCEPTIONAL RETURN CODES" |
---|
40 | .PP |
---|
41 | In addition to the result of a procedure, the return |
---|
42 | code of a procedure may also be set by \fBreturn\fR |
---|
43 | through use of the \fB\-code\fR option. |
---|
44 | In the usual case where the \fB\-code\fR option is not |
---|
45 | specified the procedure will return normally. |
---|
46 | However, the \fB\-code\fR option may be used to generate an |
---|
47 | exceptional return from the procedure. |
---|
48 | \fICode\fR may have any of the following values: |
---|
49 | .TP 13 |
---|
50 | \fBok (or 0)\fR |
---|
51 | Normal return: same as if the option is omitted. The return code |
---|
52 | of the procedure is 0 (\fBTCL_OK\fR). |
---|
53 | .TP 13 |
---|
54 | \fBerror (1)\fR |
---|
55 | Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR). |
---|
56 | The procedure command behaves in its calling context as if it |
---|
57 | were the command \fBerror \fIresult\fR. See below for additional |
---|
58 | options. |
---|
59 | .TP 13 |
---|
60 | \fBreturn (2)\fR |
---|
61 | The return code of the procedure is 2 (\fBTCL_RETURN\fR). The |
---|
62 | procedure command behaves in its calling context as if it |
---|
63 | were the command \fBreturn\fR (with no arguments). |
---|
64 | .TP 13 |
---|
65 | \fBbreak (3)\fR |
---|
66 | The return code of the procedure is 3 (\fBTCL_BREAK\fR). The |
---|
67 | procedure command behaves in its calling context as if it |
---|
68 | were the command \fBbreak\fR. |
---|
69 | .TP 13 |
---|
70 | \fBcontinue (4)\fR |
---|
71 | The return code of the procedure is 4 (\fBTCL_CONTINUE\fR). The |
---|
72 | procedure command behaves in its calling context as if it |
---|
73 | were the command \fBcontinue\fR. |
---|
74 | .TP 13 |
---|
75 | \fIvalue\fR |
---|
76 | \fIValue\fR must be an integer; it will be returned as the |
---|
77 | return code for the current procedure. |
---|
78 | .LP |
---|
79 | When a procedure wants to signal that it has received invalid |
---|
80 | arguments from its caller, it may use \fBreturn -code error\fR |
---|
81 | with \fIresult\fR set to a suitable error message. Otherwise |
---|
82 | usage of the \fBreturn -code\fR option is mostly limited to |
---|
83 | procedures that implement a new control structure. |
---|
84 | .PP |
---|
85 | The \fBreturn \-code\fR command acts similarly within script |
---|
86 | files that are evaluated by the \fBsource\fR command. During the |
---|
87 | evaluation of the contents of a file as a script by \fBsource\fR, |
---|
88 | an invocation of the \fBreturn \-code \fIcode\fR command will cause |
---|
89 | the return code of \fBsource\fR to be \fIcode\fR. |
---|
90 | .SH "RETURN OPTIONS" |
---|
91 | .PP |
---|
92 | .VS 8.5 |
---|
93 | In addition to a result and a return code, evaluation of a command |
---|
94 | in Tcl also produces a dictionary of return options. In general |
---|
95 | usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR |
---|
96 | become entries in the return options dictionary, and any values at all |
---|
97 | are acceptable except as noted below. The \fBcatch\fR command may be |
---|
98 | used to capture all of this information \(em the return code, the result, |
---|
99 | and the return options dictionary \(em that arise from evaluation of a |
---|
100 | script. |
---|
101 | .VE 8.5 |
---|
102 | .PP |
---|
103 | As documented above, the \fB\-code\fR entry in the return options dictionary |
---|
104 | receives special treatment by Tcl. There are other return options also |
---|
105 | recognized and treated specially by Tcl. They are: |
---|
106 | .TP |
---|
107 | \fB\-errorcode \fIlist\fR |
---|
108 | The \fB\-errorcode\fR option receives special treatment only when the value |
---|
109 | of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then the \fIlist\fR value |
---|
110 | is meant to be additional information about the error, |
---|
111 | presented as a Tcl list for further processing by programs. |
---|
112 | If no \fB\-errorcode\fR option is provided to \fBreturn\fR when |
---|
113 | the \fB\-code error\fR option is provided, Tcl will set the value |
---|
114 | of the \fB\-errorcode\fR entry in the return options dictionary |
---|
115 | to the default value of \fBNONE\fR. The \fB\-errorcode\fR return |
---|
116 | option will also be stored in the global variable \fBerrorCode\fR. |
---|
117 | .TP |
---|
118 | \fB\-errorinfo \fIinfo\fR |
---|
119 | The \fB\-errorinfo\fR option receives special treatment only when the value |
---|
120 | of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then \fIinfo\fR is the initial |
---|
121 | stack trace, meant to provide to a human reader additional information |
---|
122 | about the context in which the error occurred. The stack trace will |
---|
123 | also be stored in the global variable \fBerrorInfo\fR. |
---|
124 | If no \fB\-errorinfo\fR option is provided to \fBreturn\fR when |
---|
125 | the \fB\-code error\fR option is provided, Tcl will provide its own |
---|
126 | initial stack trace value in the entry for \fB\-errorinfo\fR. Tcl's |
---|
127 | initial stack trace will include only the call to the procedure, and |
---|
128 | stack unwinding will append information about higher stack levels, but |
---|
129 | there will be no information about the context of the error within |
---|
130 | the procedure. Typically the \fIinfo\fR value is supplied from |
---|
131 | the value of \fB\-errorinfo\fR in a return options dictionary captured |
---|
132 | by the \fBcatch\fR command (or from the copy of that information |
---|
133 | stored in the global variable \fBerrorInfo\fR). |
---|
134 | .TP |
---|
135 | \fB\-level \fIlevel\fR |
---|
136 | .VS 8.5 |
---|
137 | The \fB\-level\fR and \fB\-code\fR options work together to set the return |
---|
138 | code to be returned by one of the commands currently being evaluated. |
---|
139 | The \fIlevel\fR value must be a non-negative integer representing a number |
---|
140 | of levels on the call stack. It defines the number of levels up the stack |
---|
141 | at which the return code of a command currently being evaluated should |
---|
142 | be \fIcode\fR. If no \fB\-level\fR option is provided, the default value |
---|
143 | of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the |
---|
144 | current procedure returns to its caller, 1 level up the call stack. The |
---|
145 | mechanism by which these options work is described in more detail below. |
---|
146 | .VE 8.5 |
---|
147 | .TP |
---|
148 | \fB\-options \fIoptions\fR |
---|
149 | .VS 8.5 |
---|
150 | The value \fIoptions\fR must be a valid dictionary. The entries of that |
---|
151 | dictionary are treated as additional \fIoption value\fR pairs for the |
---|
152 | \fBreturn\fR command. |
---|
153 | .VE 8.5 |
---|
154 | .SH "RETURN CODE HANDLING MECHANISMS" |
---|
155 | .PP |
---|
156 | Return codes are used in Tcl to control program flow. A Tcl script |
---|
157 | is a sequence of Tcl commands. So long as each command evaluation |
---|
158 | returns a return code of \fBTCL_OK\fR, evaluation will continue to the next |
---|
159 | command in the script. Any exceptional return code (non-\fBTCL_OK\fR) |
---|
160 | returned by a command evaluation causes the flow on to the next |
---|
161 | command to be interrupted. Script evaluation ceases, and the |
---|
162 | exceptional return code from the command becomes the return code |
---|
163 | of the full script evaluation. This is the mechanism by which |
---|
164 | errors during script evaluation cause an interruption and unwinding |
---|
165 | of the call stack. It is also the mechanism by which commands |
---|
166 | like \fBbreak\fR, \fBcontinue\fR, and \fBreturn\fR cause script |
---|
167 | evaluation to terminate without evaluating all commands in sequence. |
---|
168 | .PP |
---|
169 | Some of Tcl's built-in commands evaluate scripts as part of their |
---|
170 | functioning. These commands can make use of exceptional return |
---|
171 | codes to enable special features. For example, the built-in |
---|
172 | Tcl commands that provide loops \(em such as \fBwhile\fR, \fBfor\fR, |
---|
173 | and \fBforeach\fR \(em evaluate a script that is the body of the |
---|
174 | loop. If evaluation of the loop body returns the return code |
---|
175 | of \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR, the loop command can react in such |
---|
176 | a way as to give the \fBbreak\fR and \fBcontinue\fR commands |
---|
177 | their documented interpretation in loops. |
---|
178 | .PP |
---|
179 | .VS 8.5 |
---|
180 | Procedure invocation also involves evaluation of a script, the body |
---|
181 | of the procedure. Procedure invocation provides special treatment |
---|
182 | when evaluation of the procedure body returns the return code |
---|
183 | \fBTCL_RETURN\fR. In that circumstance, the \fB\-level\fR entry in the |
---|
184 | return options dictionary is decremented. If after decrementing, |
---|
185 | the value of the \fB\-level\fR entry is 0, then the value of |
---|
186 | the \fB\-code\fR entry becomes the return code of the procedure. |
---|
187 | If after decrementing, the value of the \fB\-level\fR entry is |
---|
188 | greater than zero, then the return code of the procedure is |
---|
189 | \fBTCL_RETURN\fR. If the procedure invocation occurred during the |
---|
190 | evaluation of the body of another procedure, the process will |
---|
191 | repeat itself up the call stack, decrementing the value of the |
---|
192 | \fB\-level\fR entry at each level, so that the \fIcode\fR will |
---|
193 | be the return code of the current command \fIlevel\fR levels |
---|
194 | up the call stack. The \fBsource\fR command performs the |
---|
195 | same handling of the \fBTCL_RETURN\fR return code, which explains |
---|
196 | the similarity of \fBreturn\fR invocation during a \fBsource\fR |
---|
197 | to \fBreturn\fR invocation within a procedure. |
---|
198 | .PP |
---|
199 | The return code of the \fBreturn\fR command itself triggers this |
---|
200 | special handling by procedure invocation. If \fBreturn\fR |
---|
201 | is provided the option \fB\-level 0\fR, then the return code |
---|
202 | of the \fBreturn\fR command itself will be the value \fIcode\fR |
---|
203 | of the \fB\-code\fR option (or \fBTCL_OK\fR by default). Any other value |
---|
204 | for the \fB\-level\fR option (including the default value of 1) |
---|
205 | will cause the return code of the \fBreturn\fR command itself |
---|
206 | to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure. |
---|
207 | .VE 8.5 |
---|
208 | .SH EXAMPLES |
---|
209 | First, a simple example of using \fBreturn\fR to return from a |
---|
210 | procedure, interrupting the procedure body. |
---|
211 | .CS |
---|
212 | proc printOneLine {} { |
---|
213 | puts "line 1" ;# This line will be printed. |
---|
214 | \fBreturn\fR |
---|
215 | puts "line 2" ;# This line will not be printed. |
---|
216 | } |
---|
217 | .CE |
---|
218 | .PP |
---|
219 | Next, an example of using \fBreturn\fR to set the value |
---|
220 | returned by the procedure. |
---|
221 | .CS |
---|
222 | proc returnX {} {\fBreturn\fR X} |
---|
223 | puts [returnX] ;# prints "X" |
---|
224 | .CE |
---|
225 | .PP |
---|
226 | Next, a more complete example, using \fBreturn -code error\fR |
---|
227 | to report invalid arguments. |
---|
228 | .CS |
---|
229 | proc factorial {n} { |
---|
230 | if {![string is integer $n] || ($n < 0)} { |
---|
231 | \fBreturn\fR -code error \e |
---|
232 | "expected non-negative integer,\e |
---|
233 | but got \e"$n\e"" |
---|
234 | } |
---|
235 | if {$n < 2} { |
---|
236 | \fBreturn\fR 1 |
---|
237 | } |
---|
238 | set m [expr {$n - 1}] |
---|
239 | set code [catch {factorial $m} factor] |
---|
240 | if {$code != 0} { |
---|
241 | \fBreturn\fR -code $code $factor |
---|
242 | } |
---|
243 | set product [expr {$n * $factor}] |
---|
244 | if {$product < 0} { |
---|
245 | \fBreturn\fR -code error \e |
---|
246 | "overflow computing factorial of $n" |
---|
247 | } |
---|
248 | \fBreturn\fR $product |
---|
249 | } |
---|
250 | .CE |
---|
251 | .PP |
---|
252 | Next, a procedure replacement for \fBbreak\fR. |
---|
253 | .CS |
---|
254 | proc myBreak {} { |
---|
255 | \fBreturn\fR -code break |
---|
256 | } |
---|
257 | .CE |
---|
258 | .PP |
---|
259 | .VS 8.5 |
---|
260 | With the \fB\-level 0\fR option, \fBreturn\fR itself can serve |
---|
261 | as a replacement for \fBbreak\fR. |
---|
262 | .CS |
---|
263 | interp alias {} Break {} \fBreturn\fR -level 0 -code break |
---|
264 | .CE |
---|
265 | .PP |
---|
266 | An example of using \fBcatch\fR and \fBreturn -options\fR to |
---|
267 | re-raise a caught error: |
---|
268 | .CS |
---|
269 | proc doSomething {} { |
---|
270 | set resource [allocate] |
---|
271 | catch { |
---|
272 | # Long script of operations |
---|
273 | # that might raise an error |
---|
274 | } result options |
---|
275 | deallocate $resource |
---|
276 | \fBreturn\fR -options $options $result |
---|
277 | } |
---|
278 | .CE |
---|
279 | .PP |
---|
280 | Finally an example of advanced use of the \fBreturn\fR options |
---|
281 | to create a procedure replacement for \fBreturn\fR itself: |
---|
282 | .CS |
---|
283 | proc myReturn {args} { |
---|
284 | set result "" |
---|
285 | if {[llength $args] % 2} { |
---|
286 | set result [lindex $args end] |
---|
287 | set args [lrange $args 0 end-1] |
---|
288 | } |
---|
289 | set options [dict merge {-level 1} $args] |
---|
290 | dict incr options -level |
---|
291 | \fBreturn\fR -options $options $result |
---|
292 | } |
---|
293 | .CE |
---|
294 | .VE 8.5 |
---|
295 | .SH "SEE ALSO" |
---|
296 | break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n) |
---|
297 | .SH KEYWORDS |
---|
298 | break, catch, continue, error, procedure, return |
---|