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 (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 (2) The return code of the procedure is 2 (TCL_RETURN). The
49 procedure command behaves in its calling context as if it
50 were the command return (with no arguments).
51 break (3) The return code of the procedure is 3 (TCL_BREAK). The
53 procedure command behaves in its calling context as if it
54 were the command break.
55 continue (4) The return code of the procedure is 4 (TCL_CONTINUE). The
57 procedure command behaves in its calling context as if it
58 were the command continue.
59 value Value must be an integer; it will be returned as the
61 return code for the current procedure.
62 When a procedure wants to signal that it has received invalid arguments
64 from its caller, it may use return -code error with result set to a
65 suitable error message. Otherwise usage of the return -code option is
66 mostly limited to procedures that implement a new control structure.
67 The return -code command acts similarly within script files that are
69 evaluated by the source command. During the evaluation of the contents
70 of a file as a script by source, an invocation of the return -code code
71 command will cause the return code of source to be code.
72
74 In addition to a result and a return code, evaluation of a command in │
75 Tcl also produces a dictionary of return options. In general usage, │
76 all option value pairs given as arguments to return become entries in │
77 the return options dictionary, and any values at all are acceptable │
78 except as noted below. The catch command may be used to capture all of │
79 this information — the return code, the result, and the return options │
80 dictionary — that arise from evaluation of a script.
81 As documented above, the -code entry in the return options dictionary
83 receives special treatment by Tcl. There are other return options also
84 recognized and treated specially by Tcl. They are:
85 -errorcode list
87 The -errorcode option receives special treatment only when the
88 value of the -code option is TCL_ERROR. Then the list value is
89 meant to be additional information about the error, presented as
90 a Tcl list for further processing by programs. If no -errorcode
91 option is provided to return when the -code error option is pro‐
92 vided, Tcl will set the value of the -errorcode entry in the
93 return options dictionary to the default value of NONE. The
94 -errorcode return option will also be stored in the global vari‐
95 able errorCode.
96 -errorinfo info
98 The -errorinfo option receives special treatment only when the
99 value of the -code option is TCL_ERROR. Then info is the ini‐
100 tial stack trace, meant to provide to a human reader additional
101 information about the context in which the error occurred. The
102 stack trace will also be stored in the global variable error‐
103 Info. If no -errorinfo option is provided to return when the
104 -code error option is provided, Tcl will provide its own initial
105 stack trace value in the entry for -errorinfo. Tcl's initial
106 stack trace will include only the call to the procedure, and
107 stack unwinding will append information about higher stack lev‐
108 els, but there will be no information about the context of the
109 error within the procedure. Typically the info value is sup‐
110 plied from the value of -errorinfo in a return options dictio‐
111 nary captured by the catch command (or from the copy of that
112 information stored in the global variable errorInfo).
113 -level level
115 The -level and -code options work together to set the return │
116 code to be returned by one of the commands currently being eval‐ │
117 uated. The level value must be a non-negative integer repre‐ │
118 senting a number of levels on the call stack. It defines the │
119 number of levels up the stack at which the return code of a com‐ │
120 mand currently being evaluated should be code. If no -level │
121 option is provided, the default value of level is 1, so that │
122 return sets the return code that the current procedure returns │
123 to its caller, 1 level up the call stack. The mechanism by │
124 which these options work is described in more detail below.
125 -options options
127 The value options must be a valid dictionary. The entries of │
128 that dictionary are treated as additional option value pairs for │
129 the return command.
130
132 Return codes are used in Tcl to control program flow. A Tcl script is
133 a sequence of Tcl commands. So long as each command evaluation returns
134 a return code of TCL_OK, evaluation will continue to the next command
135 in the script. Any exceptional return code (non-TCL_OK) returned by a
136 command evaluation causes the flow on to the next command to be inter‐
137 rupted. Script evaluation ceases, and the exceptional return code from
138 the command becomes the return code of the full script evaluation.
139 This is the mechanism by which errors during script evaluation cause an
140 interruption and unwinding of the call stack. It is also the mechanism
141 by which commands like break, continue, and return cause script evalua‐
142 tion to terminate without evaluating all commands in sequence.
143 Some of Tcl's built-in commands evaluate scripts as part of their func‐
145 tioning. These commands can make use of exceptional return codes to
146 enable special features. For example, the built-in Tcl commands that
147 provide loops — such as while, for, and foreach — evaluate a script
148 that is the body of the loop. If evaluation of the loop body returns
149 the return code of TCL_BREAK or TCL_CONTINUE, the loop command can
150 react in such a way as to give the break and continue commands their
151 documented interpretation in loops.
152 Procedure invocation also involves evaluation of a script, the body of │
154 the procedure. Procedure invocation provides special treatment when │
155 evaluation of the procedure body returns the return code TCL_RETURN. │
156 In that circumstance, the -level entry in the return options dictionary │
157 is decremented. If after decrementing, the value of the -level entry │
158 is 0, then the value of the -code entry becomes the return code of the │
159 procedure. If after decrementing, the value of the -level entry is │
160 greater than zero, then the return code of the procedure is TCL_RETURN. │
161 If the procedure invocation occurred during the evaluation of the body │
162 of another procedure, the process will repeat itself up the call stack, │
163 decrementing the value of the -level entry at each level, so that the │
164 code will be the return code of the current command level levels up the │
165 call stack. The source command performs the same handling of the │
166 TCL_RETURN return code, which explains the similarity of return invoca‐ │
167 tion during a source to return invocation within a procedure. │
168 The return code of the return command itself triggers this special han‐ │
170 dling by procedure invocation. If return is provided the option -level │
171 0, then the return code of the return command itself will be the value │
172 code of the -code option (or TCL_OK by default). Any other value for │
173 the -level option (including the default value of 1) will cause the │
174 return code of the return command itself to be TCL_RETURN, triggering a │
175 return from the enclosing procedure.
176
178 First, a simple example of using return to return from a procedure,
179 interrupting the procedure body.
180 proc printOneLine {} {
181 puts "line 1" ;# This line will be printed.
182 return
183 puts "line 2" ;# This line will not be printed.
184 }
185 Next, an example of using return to set the value returned by the pro‐
187 cedure.
188 proc returnX {} {return X}
189 puts [returnX] ;# prints "X"
190 Next, a more complete example, using return -code error to report
192 invalid arguments.
193 proc factorial {n} {
194 if {![string is integer $n] || ($n < 0)} {
195 return -code error \
196 "expected non-negative integer,\
197 but got \"$n\""
198 }
199 if {$n < 2} {
200 return 1
201 }
202 set m [expr {$n - 1}]
203 set code [catch {factorial $m} factor]
204 if {$code != 0} {
205 return -code $code $factor
206 }
207 set product [expr {$n * $factor}]
208 if {$product < 0} {
209 return -code error \
210 "overflow computing factorial of $n"
211 }
212 return $product
213 }
214 Next, a procedure replacement for break.
216 proc myBreak {} {
217 return -code break
218 }
219 With the -level 0 option, return itself can serve as a replacement for │
221 break. │
222 interp alias {} Break {} return -level 0 -code break │
223 An example of using catch and return -options to re-raise a caught │
225 error: │
226 proc doSomething {} { │
227 set resource [allocate] │
228 catch { │
229 # Long script of operations │
230 # that might raise an error │
231 } result options │
232 deallocate $resource │
233 return -options $options $result │
234 } │
235 Finally an example of advanced use of the return options to create a │
237 procedure replacement for return itself: │
238 proc myReturn {args} { │
239 set result "" │
240 if {[llength $args] % 2} { │
241 set result [lindex $args end] │
242 set args [lrange $args 0 end-1] │
243 } │
244 set options [dict merge {-level 1} $args] │
245 dict incr options -level │
246 return -options $options $result │
247 } │
248
250 break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n),
251 tclvars(n)
252
254 break, catch, continue, error, procedure, return
255Tcl 8.5 return(n)