uplevel(n) Tcl uplevel(n)
_________________________________________________________________
NAME
uplevel - Execute a script in a different stack frame
SYNOPSIS
uplevel ?level? arg ?arg ...?
_________________________________________________________________
DESCRIPTION
All of the arg arguments are concatenated as if they had
been passed to concat; the result is then evaluated in the
variable context indicated by level. Uplevel returns the
result of that evaluation.
If level is an integer then it gives a distance (up the
procedure calling stack) to move before executing the
command. If level consists of # followed by a number then
the number gives an absolute level number. If level is
omitted then it defaults to 1. Level cannot be defaulted if
the first command argument starts with a digit or #.
For example, suppose that procedure a was invoked from top-
level, and that it called b, and that b called c. Suppose
that c invokes the uplevel command. If level is 1 or #2 or
omitted, then the command will be executed in the variable
context of b. If level is 2 or #1 then the command will be
executed in the variable context of a. If level is 3 or #0
then the command will be executed at top-level (only global
variables will be visible).
The uplevel command causes the invoking procedure to
disappear from the procedure calling stack while the command
is being executed. In the above example, suppose c invokes
the command
uplevel 1 {set x 43; d}
where d is another Tcl procedure. The set command will
modify the variable x in b's context, and d will execute at
level 3, as if called from b. If it in turn executes the
command
uplevel {set x 42}
then the set command will modify the same variable x in b's
context: the procedure c does not appear to be on the call
stack when d is executing. The command ``info level'' may
be used to obtain the level of the current procedure.
Uplevel makes it possible to implement new control
constructs as Tcl procedures (for example, uplevel could be
used to implement the while construct as a Tcl procedure).
namespace eval is another way (besides procedure calls) that
Page 1 (printed 2/19/99)
uplevel(n) Tcl uplevel(n)
the Tcl naming context can change. It adds a call frame to
the stack to represent the namespace context. This means
each namespace eval command counts as another call level for
uplevel and upvar commands. For example, info level 1 will
return a list describing a command that is either the
outermost procedure call or the outermost namespace eval
command. Also, uplevel #0 evaluates a script at top-level
in the outermost namespace (the global namespace).
SEE ALSO
namespace(n)
KEYWORDS
context, level, namespace, stack frame, variables
Page 2 (printed 2/19/99)
