通讯编程

开发平台：
Visual C++

upvar.n：源码内容
							'"
'" 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.5.18.2 2004/11/12 09:02:30 das 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?fIlevelfR? 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.
fILevelfR may have any of the forms permitted for the fBuplevelfR
command, and may be omitted if the first letter of the first fIotherVarfR
isn't fB#fR or a digit (it defaults to fB1fR).
For each fIotherVarfR argument, fBupvarfR makes the variable
by that name in the procedure frame given by fIlevelfR (or at
global level, if fIlevelfR is fB#0fR) accessible
in the current procedure by the name given in the corresponding
fImyVarfR argument.
The variable named by fIotherVarfR need not exist at the time of the
call;  it will be created the first time fImyVarfR is referenced, just like
an ordinary variable.  There must not exist a variable by the
name fImyVarfR at the time fBupvarfR is invoked.
fIMyVarfR is always treated as the name of a variable, not an
array element.  Even if the name looks like an array element,
such as fBa(b)fR, a regular variable is created.
fIOtherVarfR may refer to a scalar variable, an array,
or an array element.
fBUpvarfR returns an empty string.
.PP
The fBupvarfR command simplifies the implementation of call-by-name
procedure calling and also makes it easier to build new control constructs
as Tcl procedures.
For example, consider the following procedure:
.CS
proc add2 name {
   fBupvarfR $name x
   set x [expr $x+2]
}
.CE
fBadd2fR is invoked with an argument giving the name of a variable,
and it adds two to the value of that variable.
Although fBadd2fR could have been implemented using fBuplevelfR
instead of fBupvarfR, fBupvarfR makes it simpler for fBadd2fR
to access the variable in the caller's procedure frame.
.PP
fBnamespace evalfR 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 fBnamespace evalfR command
counts as another call level for fBuplevelfR and fBupvarfR commands.
For example, fBinfo level 1fR will return a list
describing a command that is either
the outermost procedure call or the outermost fBnamespace evalfR command.
Also, fBuplevel #0fR evaluates a script
at top-level in the outermost namespace (the global namespace).
.PP
.VS
If an upvar variable is unset (e.g. fBxfR in fBadd2fR above), the
fBunsetfR 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 fBupvarfR
command.
.SH "TRACES AND UPVAR"
.PP
Upvar interacts with traces in a straightforward but possibly
unexpected manner.  If a variable trace is defined on fIotherVarfR, that
trace will be triggered by actions involving fImyVarfR.  However,
the trace procedure will be passed the name of fImyVarfR, rather
than the name of fIotherVarfR.  Thus, the output of the following code
will be fBlocalVarfR rather than fBoriginalVarfR:
.CS
proc fBtraceprocfR { name index op } {
   puts $name
}
proc fBsetByUpvarfR { name value } {
   fBupvarfR $name localVar
   set localVar $value
}
set originalVar 1
trace variable originalVar w fBtraceprocfR
fBsetByUpvarfR originalVar 2
}
.CE
.PP
If fIotherVarfR refers to an element of an array, then variable
traces set for the entire array will not be invoked when fImyVarfR
is accessed (but traces on the particular element will still be
invoked).  In particular, if the array is fBenvfR, then changes
made to fImyVarfR will not be passed to subprocesses correctly.
.VE
.SH EXAMPLE
A fBdecrfR command that works like fBincrfR except it subtracts
the value from the variable instead of adding it:
.CS
proc decr {varName {decrement 1}} {
    fBupvarfR 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

						