http://www.purl.org/tcl/home/man/tcl8.4/TclCmd/return.htm
return ?-code code? ?-errorinfo info? ?-errorcode code? ?string?
Return immediately from the current procedure (or top-level command or source command), with string as the return value. If string is not specified then an empty string will be returned as result. If a proc is 'left' without explicit return, then its return value is the value of the last command executed in the procedure's body.
See also Funky Tcl extensibility on tricks to play with return -code return; error on return -code error
LV Can someone provide Wiki or other references to specific uses of Exception returns?
Also, one question I've seen beginners ask is "what do I code in Tcl so that when I invoke a procedure, I save the return value from the procedure in a variable".
EXCEPTIONAL RETURNS
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)
See the set page on why
set result
can under certain conditions be equivalent to (or better than)
return $result ;# RS
Rethinking this, it appears to me that return is a distant cousin of goto (Goto in Tcl). Good code however "starts at the beginning, proceeds to the end, then stops" (after Lewis Carroll), so not using return ensures the last command is really the end. Mid-code returns are spaghetti producers, as are breaks in a minor way - so I think I'll better avoid them...
DKF - While spaghetti code isn't good, neither is replicating all that pasta with complicated loop conditions and fancy variables. As is usual in programming, the best way to do it depends on the situation; use taste and discretion to decide what is best. And note that the big advantage to return is that it says that its argument is really meant to be the result of the procedure, and not merely that the programmer got called away to a vital meeting at an inconvenient moment! And in recent versions of Tcl there's no longer a performance penalty for using it either. :^)
See the try ... finally ... page for how to use [return -code] to implement a new control structure. - KBK (2 Jan 2001)
Lars H: Other pages which do that kind of thing are breakeval (using -code 10) and returneval (using -code -1).
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.
See also uplevel for a TclChat discussion on the future of return...
The fact that return also terminates a source command 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.
See package index script interface guidelines for another use of return in sourced 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 interps 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"AMG: [return] has many cousins: