See also Funky Tcl extensibility on tricks to play with return -code return; error on return -code error

---

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...
 } ;# RS

DGP 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":

• braces still needed to be balanced
• some commands like set get byte-compiled early, so a syntax error is found if a line in that post-return comment starts with set and has more than two other words.

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" 1

as 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 -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.

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:

set y [if {$x} {lindex a} else {lindex b}]

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 no further bind scripts should process.