NAME
upvar - Create link to variable in a different stack frame
SYNOPSIS
upvar ?level? otherVar myVar ?otherVar myVar ...?
_________________________________________________________________
DESCRIPTION
This command arranges for one or more local variables in
the current procedure to refer to variables in an enclos
ing procedure call or to global variables. Level may have
any of the forms permitted for the uplevel command, and
may be omitted if the first letter of the first otherVar
isn't # or a digit (it defaults to 1). For each otherVar
argument, upvar makes the variable by that name in the
procedure frame given by level (or at global level, if
level is #0) accessible in the current procedure by the
name given in the corresponding myVar argument. The vari
able named by otherVar need not exist at the time of the
call; it will be created the first time myVar is refer
enced, just like an ordinary variable. There must not
exist a variable by the name myVar at the time upvar is
invoked. MyVar is always treated as the name of a vari
able, not an array element. Even if the name looks like
an array element, such as a(b), a regular variable is cre
ated. OtherVar may refer to a scalar variable, an array,
or an array element. Upvar returns an empty string.
The upvar command simplifies the implementation of call-
by-name procedure calling and also makes it easier to
build new control constructs as Tcl procedures. For exam
ple, consider the following procedure:
proc add2 name {
upvar $name x
set x [expr $x+2]
}
Add2 is invoked with an argument giving the name of a
variable, and it adds two to the value of that variable.
Although add2 could have been implemented using uplevel
instead of upvar, upvar makes it simpler for add2 to
access the variable in the caller's procedure frame.
namespace eval is another way (besides procedure calls)
that 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
If an upvar variable is unset (e.g. x in add2 above), the |
unset operation affects the variable it is linked to, not |
the upvar variable. There is no way to unset an upvar |
variable except by exiting the procedure in which it is |
defined. However, it is possible to retarget an upvar |
variable by executing another upvar command. |
Traces and upvar |
Upvar interacts with traces in a straightforward but pos |
sibly unexpected manner. If a variable trace is defined |
on otherVar, that trace will be triggered by actions |
involving myVar. However, the trace procedure will be |
passed the name of myVar, rather than the name of other |
Var. Thus, the output of the following code will be |
localVar rather than originalVar: |
proc traceproc { name index op } { |
puts $name |
} |
proc setByUpvar { name value } { |
upvar $name localVar |
set localVar $value |
} |
set originalVar 1 |
trace variable originalVar w traceproc |
setByUpvar originalVar 2 |
} |
If otherVar refers to an element of an array, then vari |
able traces set for the entire array will not be invoked |
when myVar is accessed (but traces on the particular ele |
ment will still be invoked). In particular, if the array |
is env, then changes made to myVar will not be passed to |
subprocesses correctly.
SEE ALSO
global(n), namespace(n), uplevel(n), variable(n)
KEYWORDS
context, frame, global, level, namespace, procedure, vari
able
Man(1) output converted with
man2html