http://www.tcl.tk/man/tcl/TclCmd/return.htm
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.
[TODO: Document Tcl 8.5's extended handling]
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? Fabricio Rocha - 17 May 2010 - I have created a page about this: see Errors management. LV have already added some information to it, but it can surely benefit of more contributions.
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".
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 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: