return , a built-in Tcl command, terminates a script, specifying its result.
tailcall is also related to return in that it terminates execution of the current proc. However, unlike return, tailcall's continuation is not the caller. yieldTo is also related to tailcall in that it has a custom continuation.
Return immediately from the current procedure or script, with the specified result. The default result is the empty string.
When there is no return in a script, its value is the value of the last command evaluated in the script.
[TODO: Document Tcl 8.5's extended handling]
In the usual case where the -code option isn't specified, the procedure will return normally (its completion code will be TCL_OK). However, the -code option may be used to generate an exceptional return from the procedure. Code may have any of the following values:
The -code option is rarely used. It is provided so that procedures that implement new control structures can reflect exceptional conditions back to their callers.
Two additional options, -errorinfo and -errorcode, may be used to provide additional information during error returns. These options are ignored unless code is error.
The -errorinfo option specifies an initial stack trace for the errorInfo variable; if it is not specified then the stack trace left in errorInfo 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 info value is supplied from the value left in errorInfo after a catch command trapped an error within the procedure.
If the -errorcode option is specified then code provides a value for the errorCode variable. If the option is not specified then errorCode will default to NONE. (from: Tcl Help)
After return, your script can contain whatever, for instance comments:
proc foo {} {
puts Foo
return
This is not Tcl - code after the return is never evaluated so
may be used for commenting...
} ;# RSDGP: In Tcl 7 and in recent enough Tcl 8.5 that is correct. In the releases in between, due to some limitations in the bytecode compiler/execution machinery it could not be "whatever":
Joe English also disagrees that "whatever" can appear after a return command. proc interprets its third argument as a script. It's therefore unwise, and one could argue even illegal, to pass in something that's not at least syntactically valid as a script, even if you know that parts of it will never be executed. By way of analogy: lindex interprets its first argument as a list, so you'd better only pass it valid lists. In Tcl 7.6 and earlier you could actually get away with things like
lindex "a b c {bad{list" 1as long as the examined part of the list was syntactically valid. However, this was more of an accidental artifact of implementation details than anything guaranteed by the language, and in fact this raises an error in more recent Tcl versions. Similarly, if a command expects a script, you'd better pass it a script.
PYK 2013-12-10: However, if lindex is missing its second value, the first value can still be any value, list or otherwise.
jenglish's statement is correct, though it's more philosophical than practical. If [return] is redefined, code following the [return] could certainly come into play. Or perhaps the code isn't being executed but rather is being analyzed by Nagelfar, which will surely take issue with the invalidity of the code. One real possibility which would upset Tcl in any event is if the text following [return] contains mismatched braces. The fact that return also terminates source can be used for loading array contents without specifying an array name. Let the file t.tcl contain:
return {
one 1
two 2
three 3}
Then you can write it like this:
array set myArrayName source t.tcl ;# RS
[wdb] This works. But being a purist, I prefer this text in the file to ''source'':
list one 1 two 2 three 3
[RS] 2006-06-23: sure. Just if you have hundreds and thousands of array elements, with [list] you'd have to backslash-escape the newlines, while with bracing they need not. ---- ** Use in [pkgIndex.tcl] ** See [package index script interface guidelines] for another use of `[return]` in `[source]`d scripts: The main use for return outside procedures is in [pkgIndex.tcl]:
if {!package vsatisfies [package provide Tcl 8.4]} {return}
which avoids presenting the package to [interp]s that cannot use it. ---- [RS] 2005-08-08: Using ''`return -code error`'' in place of plain `[error]`, you get a leaner error traceback which is possibly better to read:
% proc 1 x {if {$x<=0} {error "too small"}}
% proc 2 x {if {$x<=0} {return -code error "too small"}}
% 1 0 too small % set errorInfo too small
while executing
"error "too small""
(procedure "1" line 1) invoked from within
"1 0"
% 2 0 too small % set errorInfo too small
while executing
"2 0"
----
** `return` to the Current Level **
[AMG]: ''`return -level 0 $x`'' simply sets the interpreter result to `$x`; it
doesn't cause the caller to return. [[`[expr] {$x}`] and [[`[subst] {$x}`]
do the same, except that `$x` must be brace-quoted for safety. [[`K $x ""`] is
also valid, as is [[`K* $x`] (K and K* are defined on the [K] wiki page.)
Let's say you have to pass a script to be `[eval]`'ed, and `[eval]`'s
return value is used somehow. What script do you pass if you want eval to
simply return a constant, the result of a substitution, or a concatenated
combination thereof? All of the above methods work, and ''`return -level 0`''
avoids the need for extra quoting or `[proc]` wrappers.
[AMG] [PYK]: `return -level 0 $x` simply sets the interpreter result to `$x`. This is the canonical [identity function]; see the linked page for more information.
Basically I have given a list of ways to perform Tcl substitution in a
functional context. More ways exist, but these are the simplest I know of.
Update: I have just discovered single-argument `[lindex]`, which simply
returns its argument. This is even easier than ''`return -level 0`''.
Update 2: I found an example use on the `[if]` page:
** Cancel an Error **set y if {$x} {lindex a} else {lindex b}
[HaO]: When a return code should be forwarded to the caller, one could remove Update 3: Here's another approach, on the `[switch]` page, thanks to [RS] (2005-05-30):
proc is x {set x} set type [switch -- $num {
1 - 9 {is odd}
2 - 3 - 5 - 7 {is prime}
0 - 4 - 6 - 8 {is even}}]
It's possible to delete the "`[proc]`" line and replace "is" with `lindex`. See "[I Know Nothing]" for more discussion of the -level option. ---- [HaO]: When a return code should be forwarded to the caller, one could remove the `level 0` to not directly trigger an eventual exception here:
if {[catch {cmd} err options]} {
dict unset options -level
return -options $options
}This was useful to me in the context of Tk bind scripts, which return break if This was useful to me in the context of Tk bind scripts, which return break, if no further bind scripts should process.