|
ActiveTcl User Guide |
|
- NAME
- return - Return from a procedure, or set return code of a
script
- SYNOPSIS
- return ?result?
- return ?-code code? ?result?
- return ?option value ...? ?result?
- DESCRIPTION
- EXCEPTIONAL RETURN
CODES
- ok (or 0)
- error (1)
- return (2)
- break (3)
- continue
(4)
- value
- RETURN OPTIONS
- -errorcode
list
- -errorinfo
info
- -level
level
- -options
options
- RETURN CODE HANDLING
MECHANISMS
- EXAMPLES
- SEE ALSO
- KEYWORDS
return - Return from a procedure, or set return code of a script
return ?result?
return ?-code code? ?result?
return ?option value ...? ?result?
In its simplest usage, the return command is used without
options in the body of a procedure to immediately return control to
the caller of the procedure. If a result argument is
provided, its value becomes the result of the procedure passed back
to the caller. If result is not specified then an empty
string will be returned to the caller as the result of the
procedure.
The return command serves a similar function within
script files that are evaluated by the source command. When source evaluates the contents of a
file as a script, an invocation of the return command will
cause script evaluation to immediately cease, and the value
result (or an empty string) will be returned as the result
of the source
command.
In addition to the result of a procedure, the return code of a
procedure may also be set by return through use of the
-code option. In the usual case where the -code
option is not specified the procedure will return normally.
However, the -code option may be used to generate an
exceptional return from the procedure. Code may have any of
the following values:
- ok (or 0)
- Normal return: same as if the option is omitted. The return
code of the procedure is 0 (TCL_OK).
- error (1)
- Error return: the return code of the procedure is 1
(TCL_ERROR). The procedure command behaves in its calling
context as if it were the command error result. See
below for additional options.
- return (2)
- The return code of the procedure is 2 (TCL_RETURN). The
procedure command behaves in its calling context as if it were the
command return (with no arguments).
- break (3)
- The return code of the procedure is 3 (TCL_BREAK). The
procedure command behaves in its calling context as if it were the
command break.
- continue (4)
- The return code of the procedure is 4 (TCL_CONTINUE).
The procedure command behaves in its calling context as if it were
the command continue.
- value
- Value must be an integer; it will be returned as the
return code for the current procedure.
When a procedure wants to signal that it has received invalid
arguments from its caller, it may use return -code error
with result set to a suitable error message. Otherwise usage
of the return -code option is mostly limited to procedures
that implement a new control structure.
The return -code command acts similarly within script
files that are evaluated by the source command. During the
evaluation of the contents of a file as a script by source, an invocation of the
return -code code command will cause the return code
of source to be
code.
In addition to a result and a return code, evaluation of a command
in Tcl also produces a dictionary of return options. In general
usage, all option value pairs given as arguments to
return become entries in the return options dictionary, and
any values at all are acceptable except as noted below. The catch command may be used to
capture all of this information — the return code, the
result, and the return options dictionary — that arise from
evaluation of a script.
As documented above, the -code entry in the return
options dictionary receives special treatment by Tcl. There are
other return options also recognized and treated specially by Tcl.
They are:
- -errorcode list
- The -errorcode option receives special treatment only
when the value of the -code option is TCL_ERROR. Then
the list value is meant to be additional information about
the error, presented as a Tcl list for further processing by
programs. If no -errorcode option is provided to
return when the -code error option is provided, Tcl
will set the value of the -errorcode entry in the return
options dictionary to the default value of NONE. The
-errorcode return option will also be stored in the global
variable errorCode.
- -errorinfo info
- The -errorinfo option receives special treatment only
when the value of the -code option is TCL_ERROR. Then
info is the initial stack trace, meant to provide to a human
reader additional information about the context in which the error
occurred. The stack trace will also be stored in the global
variable errorInfo. If no -errorinfo option is
provided to return when the -code error option is
provided, Tcl will provide its own initial stack trace value in the
entry for -errorinfo. Tcl's initial stack trace will include
only the call to the procedure, and stack unwinding will append
information about higher stack levels, but there will be no
information about the context of the error within the procedure.
Typically the info value is supplied from the value of
-errorinfo in a return options dictionary captured by the
catch command (or from the
copy of that information stored in the global variable
errorInfo).
- -level level
- The -level and -code options work together to set
the return code to be returned by one of the commands currently
being evaluated. The level value must be a non-negative
integer representing a number of levels on the call stack. It
defines the number of levels up the stack at which the return code
of a command currently being evaluated should be code. If no
-level option is provided, the default value of level
is 1, so that return sets the return code that the current
procedure returns to its caller, 1 level up the call stack. The
mechanism by which these options work is described in more detail
below.
- -options options
- The value options must be a valid dictionary. The
entries of that dictionary are treated as additional option
value pairs for the return command.
Return codes are used in Tcl to control program flow. A Tcl script
is a sequence of Tcl commands. So long as each command evaluation
returns a return code of TCL_OK, evaluation will continue to
the next command in the script. Any exceptional return code
(non-TCL_OK) returned by a command evaluation causes the
flow on to the next command to be interrupted. Script evaluation
ceases, and the exceptional return code from the command becomes
the return code of the full script evaluation. This is the
mechanism by which errors during script evaluation cause an
interruption and unwinding of the call stack. It is also the
mechanism by which commands like break, continue, and
return cause script evaluation to terminate without
evaluating all commands in sequence.
Some of Tcl's built-in commands evaluate scripts as part of
their functioning. These commands can make use of exceptional
return codes to enable special features. For example, the built-in
Tcl commands that provide loops — such as while, for, and foreach — evaluate a script
that is the body of the loop. If evaluation of the loop body
returns the return code of TCL_BREAK or TCL_CONTINUE,
the loop command can react in such a way as to give the
break and continue commands their documented
interpretation in loops.
Procedure invocation also involves evaluation of a script, the
body of the procedure. Procedure invocation provides special
treatment when evaluation of the procedure body returns the return
code TCL_RETURN. In that circumstance, the -level
entry in the return options dictionary is decremented. If after
decrementing, the value of the -level entry is 0, then the
value of the -code entry becomes the return code of the
procedure. If after decrementing, the value of the -level
entry is greater than zero, then the return code of the procedure
is TCL_RETURN. If the procedure invocation occurred during
the evaluation of the body of another procedure, the process will
repeat itself up the call stack, decrementing the value of the
-level entry at each level, so that the code will be
the return code of the current command level levels up the
call stack. The source
command performs the same handling of the TCL_RETURN return
code, which explains the similarity of return invocation
during a source to
return invocation within a procedure.
The return code of the return command itself triggers
this special handling by procedure invocation. If return is
provided the option -level 0, then the return code of the
return command itself will be the value code of the
-code option (or TCL_OK by default). Any other value
for the -level option (including the default value of 1)
will cause the return code of the return command itself to
be TCL_RETURN, triggering a return from the enclosing
procedure.
First, a simple example of using return to return from a
procedure, interrupting the procedure body.
proc printOneLine {} {
puts "line 1" ;# This line will be printed.
return
puts "line 2" ;# This line will not be printed.
}
Next, an example of using return to set the value
returned by the procedure.
proc returnX {} {return X}
puts [returnX] ;# prints "X"
Next, a more complete example, using return -code error
to report invalid arguments.
proc factorial {n} {
if {![string is integer $n] || ($n < 0)} {
return -code error \
"expected non-negative integer,\
but got \"$n\""
}
if {$n < 2} {
return 1
}
set m [expr {$n - 1}]
set code [catch {factorial $m} factor]
if {$code != 0} {
return -code $code $factor
}
set product [expr {$n * $factor}]
if {$product < 0} {
return -code error \
"overflow computing factorial of $n"
}
return $product
}
Next, a procedure replacement for break.
proc myBreak {} {
return -code break
}
With the -level 0 option, return itself can serve
as a replacement for break.
interp alias {} Break {} return -level 0 -code break
An example of using catch and return -options to
re-raise a caught error:
proc doSomething {} {
set resource [allocate]
catch {
# Long script of operations
# that might raise an error
} result options
deallocate $resource
return -options $options $result
}
Finally an example of advanced use of the return options
to create a procedure replacement for return itself:
proc myReturn {args} {
set result ""
if {[llength $args] % 2} {
set result [lindex $args end]
set args [lrange $args 0 end-1]
}
set options [dict merge {-level 1} $args]
dict incr options -level
return -options $options $result
}
break, catch,
continue, dict,
error, proc, source, tclvars
break, catch, continue, error, procedure, return
Copyright © 1995-1997 Roger E. Critchlow Jr.
Copyright © 1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.