1return(n) Tcl Built-In Commands return(n)
2______________________________________________________________________________
6
8 return - Return from a procedure, or set return code of a script
9
11 return ?result?
12 return ?-code code? ?result?
14 return ?option value ...? ?result?
16______________________________________________________________________________
17
19 In its simplest usage, the return command is used without options in
20 the body of a procedure to immediately return control to the caller of
21 the procedure. If a result argument is provided, its value becomes the
22 result of the procedure passed back to the caller. If result is not
23 specified then an empty string will be returned to the caller as the
24 result of the procedure.
25 The return command serves a similar function within script files that
27 are evaluated by the source command. When source evaluates the con‐
28 tents of a file as a script, an invocation of the return command will
29 cause script evaluation to immediately cease, and the value result (or
30 an empty string) will be returned as the result of the source command.
31
33 In addition to the result of a procedure, the return code of a proce‐
34 dure may also be set by return through use of the -code option. In the
35 usual case where the -code option is not specified the procedure will
36 return normally. However, the -code option may be used to generate an
37 exceptional return from the procedure. Code may have any of the fol‐
38 lowing values:
39 ok (or 0) Normal return: same as if the option is omitted. The
41 return code of the procedure is 0 (TCL_OK).
42 error (or 1) Error return: the return code of the procedure is 1
44 (TCL_ERROR). The procedure command behaves in its calling
45 context as if it were the command error result. See below
46 for additional options.
47 return (or 2)
49 The return code of the procedure is 2 (TCL_RETURN). The
50 procedure command behaves in its calling context as if it
51 were the command return (with no arguments).
52 break (or 3) The return code of the procedure is 3 (TCL_BREAK). The
54 procedure command behaves in its calling context as if it
55 were the command break.
56 continue (or 4)
58 The return code of the procedure is 4 (TCL_CONTINUE). The
59 procedure command behaves in its calling context as if it
60 were the command continue.
61 value Value must be an integer; it will be returned as the
63 return code for the current procedure.
64 When a procedure wants to signal that it has received invalid arguments
66 from its caller, it may use return -code error with result set to a
67 suitable error message. Otherwise usage of the return -code option is
68 mostly limited to procedures that implement a new control structure.
69 The return -code command acts similarly within script files that are
71 evaluated by the source command. During the evaluation of the contents
72 of a file as a script by source, an invocation of the return -code code
73 command will cause the return code of source to be code.
74
76 In addition to a result and a return code, evaluation of a command in
77 Tcl also produces a dictionary of return options. In general usage,
78 all option value pairs given as arguments to return become entries in
79 the return options dictionary, and any values at all are acceptable
80 except as noted below. The catch command may be used to capture all of
81 this information — the return code, the result, and the return options
82 dictionary — that arise from evaluation of a script.
83 As documented above, the -code entry in the return options dictionary
85 receives special treatment by Tcl. There are other return options also
86 recognized and treated specially by Tcl. They are:
87 -errorcode list
89 The -errorcode option receives special treatment only when the
90 value of the -code option is TCL_ERROR. Then the list value is
91 meant to be additional information about the error, presented as
92 a Tcl list for further processing by programs. If no -errorcode
93 option is provided to return when the -code error option is pro‐
94 vided, Tcl will set the value of the -errorcode entry in the
95 return options dictionary to the default value of NONE. The
96 -errorcode return option will also be stored in the global vari‐
97 able errorCode.
98 -errorinfo info
100 The -errorinfo option receives special treatment only when the
101 value of the -code option is TCL_ERROR. Then info is the ini‐
102 tial stack trace, meant to provide to a human reader additional
103 information about the context in which the error occurred. The
104 stack trace will also be stored in the global variable error‐
105 Info. If no -errorinfo option is provided to return when the
106 -code error option is provided, Tcl will provide its own initial
107 stack trace value in the entry for -errorinfo. Tcl's initial
108 stack trace will include only the call to the procedure, and
109 stack unwinding will append information about higher stack lev‐
110 els, but there will be no information about the context of the
111 error within the procedure. Typically the info value is sup‐
112 plied from the value of -errorinfo in a return options dictio‐
113 nary captured by the catch command (or from the copy of that
114 information stored in the global variable errorInfo).
115 -errorstack list
117 The -errorstack option receives special treatment only when the │
118 value of the -code option is TCL_ERROR. Then list is the ini‐ │
119 tial error stack, recording actual argument values passed to │
120 each proc level. The error stack will also be reachable through │
121 info errorstack. If no -errorstack option is provided to return │
122 when the -code error option is provided, Tcl will provide its │
123 own initial error stack in the entry for -errorstack. Tcl's │
124 initial error stack will include only the call to the procedure, │
125 and stack unwinding will append information about higher stack │
126 levels, but there will be no information about the context of │
127 the error within the procedure. Typically the list value is │
128 supplied from the value of -errorstack in a return options dic‐ │
129 tionary captured by the catch command (or from the copy of that │
130 information from info errorstack).
131 -level level
133 The -level and -code options work together to set the return
134 code to be returned by one of the commands currently being eval‐
135 uated. The level value must be a non-negative integer repre‐
136 senting a number of levels on the call stack. It defines the
137 number of levels up the stack at which the return code of a com‐
138 mand currently being evaluated should be code. If no -level
139 option is provided, the default value of level is 1, so that
140 return sets the return code that the current procedure returns
141 to its caller, 1 level up the call stack. The mechanism by
142 which these options work is described in more detail below.
143 -options options
145 The value options must be a valid dictionary. The entries of
146 that dictionary are treated as additional option value pairs for
147 the return command.
148
150 Return codes are used in Tcl to control program flow. A Tcl script is
151 a sequence of Tcl commands. So long as each command evaluation returns
152 a return code of TCL_OK, evaluation will continue to the next command
153 in the script. Any exceptional return code (non-TCL_OK) returned by a
154 command evaluation causes the flow on to the next command to be inter‐
155 rupted. Script evaluation ceases, and the exceptional return code from
156 the command becomes the return code of the full script evaluation.
157 This is the mechanism by which errors during script evaluation cause an
158 interruption and unwinding of the call stack. It is also the mechanism
159 by which commands like break, continue, and return cause script evalua‐
160 tion to terminate without evaluating all commands in sequence.
161 Some of Tcl's built-in commands evaluate scripts as part of their func‐
163 tioning. These commands can make use of exceptional return codes to
164 enable special features. For example, the built-in Tcl commands that
165 provide loops — such as while, for, and foreach — evaluate a script
166 that is the body of the loop. If evaluation of the loop body returns
167 the return code of TCL_BREAK or TCL_CONTINUE, the loop command can
168 react in such a way as to give the break and continue commands their
169 documented interpretation in loops.
170 Procedure invocation also involves evaluation of a script, the body of
172 the procedure. Procedure invocation provides special treatment when
173 evaluation of the procedure body returns the return code TCL_RETURN.
174 In that circumstance, the -level entry in the return options dictionary
175 is decremented. If after decrementing, the value of the -level entry
176 is 0, then the value of the -code entry becomes the return code of the
177 procedure. If after decrementing, the value of the -level entry is
178 greater than zero, then the return code of the procedure is TCL_RETURN.
179 If the procedure invocation occurred during the evaluation of the body
180 of another procedure, the process will repeat itself up the call stack,
181 decrementing the value of the -level entry at each level, so that the
182 code will be the return code of the current command level levels up the
183 call stack. The source command performs the same handling of the
184 TCL_RETURN return code, which explains the similarity of return invoca‐
185 tion during a source to return invocation within a procedure.
186 The return code of the return command itself triggers this special han‐
188 dling by procedure invocation. If return is provided the option -level
189 0, then the return code of the return command itself will be the value
190 code of the -code option (or TCL_OK by default). Any other value for
191 the -level option (including the default value of 1) will cause the
192 return code of the return command itself to be TCL_RETURN, triggering a
193 return from the enclosing procedure.
194
196 First, a simple example of using return to return from a procedure,
197 interrupting the procedure body.
198 proc printOneLine {} {
200 puts "line 1" ;# This line will be printed.
201 return
202 puts "line 2" ;# This line will not be printed.
203 }
204 Next, an example of using return to set the value returned by the pro‐
206 cedure.
207 proc returnX {} {return X}
209 puts [returnX] ;# prints "X"
210 Next, a more complete example, using return -code error to report
212 invalid arguments.
213 proc factorial {n} {
215 if {![string is integer $n] || ($n < 0)} {
216 return -code error \
217 "expected non-negative integer,\
218 but got \"$n\""
219 }
220 if {$n < 2} {
221 return 1
222 }
223 set m [expr {$n - 1}]
224 set code [catch {factorial $m} factor]
225 if {$code != 0} {
226 return -code $code $factor
227 }
228 set product [expr {$n * $factor}]
229 if {$product < 0} {
230 return -code error \
231 "overflow computing factorial of $n"
232 }
233 return $product
234 }
235 Next, a procedure replacement for break.
237 proc myBreak {} {
239 return -code break
240 }
241 With the -level 0 option, return itself can serve as a replacement for
243 break, with the help of interp alias.
244 interp alias {} Break {} return -level 0 -code break
246 An example of using catch and return -options to re-raise a caught
248 error:
249 proc doSomething {} {
251 set resource [allocate]
252 catch {
253 # Long script of operations
254 # that might raise an error
255 } result options
256 deallocate $resource
257 return -options $options $result
258 }
259 Finally an example of advanced use of the return options to create a
261 procedure replacement for return itself:
262 proc myReturn {args} {
264 set result ""
265 if {[llength $args] % 2} {
266 set result [lindex $args end]
267 set args [lrange $args 0 end-1]
268 }
269 set options [dict merge {-level 1} $args]
270 dict incr options -level
271 return -options $options $result
272 }
273
275 break(n), catch(n), continue(n), dict(n), error(n), errorCode(n),
276 errorInfo(n), proc(n), source(n), throw(n), try(n)
277
279 break, catch, continue, error, exception, procedure, result, return
280Tcl 8.5 return(n)