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: ok: Normal return: same as if the option is omitted. error: Error return: same as if the [error] command were used to terminate the procedure, except for handling of [errorInfo] and [errorCode] variables (see below). return: The current procedure will return with a completion code of TCL_RETURN, so that the procedure that invoked it will return also. break: The current procedure will return with a completion code of TCL_BREAK, which will terminate the innermost nested loop in the code that invoked the current procedure. continue: The current procedure will return with a completion code of TCL_CONTINUE, which will terminate the current iteration of the innermost nested loop in the code that invoked the current procedure. value: Value must be an integer; it will be returned as the completion code for the current procedure. 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 [return]s are spaghetti producers, as are [break]s 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... } ;# RS [Donald Porter] pointed out that it can't be "whatever": * braces still need 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 [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" ---- [[ [Tcl syntax help] | [Arts and crafts of Tcl-Tk programming] | [Category Command] | [Category Control Structure] ]]