1mNAME0m
       upvar - Create link to variable in a different stack frame

1mSYNOPSIS0m
       1mupvar 22m?4mlevel24m? 4motherVar24m 4mmyVar24m ?4motherVar24m 4mmyVar24m ...?


1mDESCRIPTION0m
       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.   4mLevel24m  may have any of the forms permitted for the
       1muplevel 22mcommand, and may be omitted if the first letter  of  the  first
       4motherVar24m  isn't  1m#  22mor  a  digit (it defaults to 1m122m).  For each 4motherVar0m
       argument, 1mupvar 22mmakes the variable by that name in the procedure  frame
       given  by  4mlevel24m (or at global level, if 4mlevel24m is 1m#022m) accessible in the
       current procedure by the name given in the  corresponding  4mmyVar24m  argu-
       ment.  The variable named by 4motherVar24m need not exist at the time of the
       call;  it will be created the first time 4mmyVar24m is referenced, just like
       an  ordinary  variable.   There  must  not exist a variable by the name
       4mmyVar24m at the time 1mupvar 22mis invoked.  4mMyVar24m is  always  treated  as  the
       name  of a variable, not an array element.  Even if the name looks like
       an array element, such as 1ma(b)22m, a regular variable is created.   4mOther-0m
       4mVar24m  may  refer  to  a  scalar variable, an array, or an array element.
       1mUpvar 22mreturns an empty string.

       The 1mupvar 22mcommand simplifies the implementation of call-by-name  proce-
       dure  calling  and also makes it easier to build new control constructs
       as Tcl procedures.  For example, consider the following procedure:
              1mproc add2 name {0m
                1mupvar $name x0m
                1mset x [expr $x+2]0m
              1m}0m
       1mAdd2 22mis invoked with an argument giving the name of a variable, and  it
       adds  two to the value of that variable.  Although 1madd2 22mcould have been
       implemented using 1muplevel 22minstead of 1mupvar22m, 1mupvar 22mmakes it simpler  for
       1madd2 22mto access the variable in the caller's procedure frame.

       1mnamespace  eval  22mis  another way (besides procedure calls) that the Tcl
       naming context can change.  It adds a call frame to the stack to repre-
       sent  the  namespace  context.   This means each 1mnamespace eval 22mcommand
       counts as another call level for 1muplevel 22mand 1mupvar 22mcommands.  For exam-
       ple,  1minfo  level  1  22mwill  return  a list describing a command that is
       either the outermost procedure call or  the  outermost  1mnamespace  eval0m
       command.   Also, 1muplevel #0 22mevaluates a script at top-level in the out-
       ermost namespace (the global namespace).

       If an upvar variable is unset (e.g. 1mx 22min 1madd2 22mabove), the 1munset  22mopera-
       tion  affects  the  variable  it  is linked to, not the upvar variable.
       There is no way to unset an upvar variable except by exiting the proce-
       dure  in  which  it is defined.  However, it is possible to retarget an
       upvar variable by executing another 1mupvar 22mcommand.


1mTraces and upvar0m
       Upvar interacts with traces in a  straightforward  but  possibly  unex-
       pected  manner.  If a variable trace is defined on 4motherVar24m, that trace
       will be triggered by actions involving 4mmyVar24m.  However, the trace  pro-
       cedure will be passed the name of 4mmyVar24m, rather than the name of 4mother-0m
       4mVar24m.  Thus, the output of the following code will  be  1mlocalVar  22mrather
       than 1moriginalVar22m:
              1mproc traceproc { name index op } {0m
                1mputs $name0m
              1m}0m
              1mproc setByUpvar { name value } {0m
                1mupvar $name localVar0m
                1mset localVar $value0m
              1m}0m
              1mset originalVar 10m
              1mtrace variable originalVar w traceproc0m
              1msetByUpvar originalVar 20m
              1m}0m

       If  4motherVar24m refers to an element of an array, then variable traces set
       for the entire array will not be invoked when 4mmyVar24m  is  accessed  (but
       traces  on  the particular element will still be invoked).  In particu-
       lar, if the array is 1menv22m, then changes made to 4mmyVar24m will not be passed
       to subprocesses correctly.


1mSEE ALSO0m
       global(n), namespace(n), uplevel(n), variable(n)


1mKEYWORDS0m
