Tcl Source Code

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: upvar.n,v 1.13 2007/10/25 09:58:53 dkf Exp $
'\" 
.so man.macros
.TH upvar n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
upvar \- Create link to variable in a different stack frame
.SH SYNOPSIS
\fBupvar \fR?\fIlevel\fR? \fIotherVar myVar \fR?\fIotherVar myVar \fR...?
.BE

.SH DESCRIPTION
.PP
This command arranges for one or more local variables in the current
procedure to refer to variables in an enclosing procedure call or
to global variables.
\fILevel\fR may have any of the forms permitted for the \fBuplevel\fR
command, and may be omitted if the first letter of the first \fIotherVar\fR

.SH "TRACES AND UPVAR"
.PP
Upvar interacts with traces in a straightforward but possibly
unexpected manner.  If a variable trace is defined on \fIotherVar\fR, that
trace will be triggered by actions involving \fImyVar\fR.  However,
the trace procedure will be passed the name of \fImyVar\fR, rather
than the name of \fIotherVar\fR.  Thus, the output of the following code
will be
.QW "\fIlocalVar\fR"
rather than
.QW "\fIoriginalVar\fR" :
.CS
proc \fItraceproc\fR { name index op } {
   puts $name
}
proc \fIsetByUpvar\fR { name value } {
   \fBupvar\fR $name localVar
   set localVar $value

the value from the variable instead of adding it:
.CS
proc decr {varName {decrement 1}} {
    \fBupvar\fR 1 $varName var
    incr var [expr {-$decrement}]
}
.CE

.SH "SEE ALSO"
global(n), namespace(n), uplevel(n), variable(n)

.SH KEYWORDS
context, frame, global, level, namespace, procedure, variable