upvar(n)              Tcl Built-In Commands              upvar(n)



_________________________________________________________________

NAME
     upvar - Create link to variable in a different stack frame

SYNOPSIS
     upvar ?_l_e_v_e_l? _o_t_h_e_r_V_a_r _m_y_V_a_r ?_o_t_h_e_r_V_a_r _m_y_V_a_r ...?
_________________________________________________________________


DESCRIPTION
     This command arranges for one or more local variables in the
     current procedure to refer to variables in an enclosing pro-
     cedure call or to global variables.  _L_e_v_e_l may have  any  of
     the  forms  permitted  for  the  uplevel command, and may be
     omitted if the first letter of the first _o_t_h_e_r_V_a_r isn't # or
     a  digit  (it  defaults  to 1).  For each _o_t_h_e_r_V_a_r argument,
     upvar makes the variable by that name in the procedure frame
     given by _l_e_v_e_l (or at global level, if _l_e_v_e_l is #0) accessi-
     ble in the current  procedure  by  the  name  given  in  the
     corresponding  _m_y_V_a_r argument.  The variable named by _o_t_h_e_r_-
     _V_a_r need not exist at the time of  the  call;   it  will  be
     created  the  first  time  _m_y_V_a_r is referenced, just like an
     ordinary variable.  There must not exist a variable  by  the
     name  _m_y_V_a_r  at  the time upvar is invoked.  _M_y_V_a_r is always
     treated as the name of a variable,  not  an  array  element.
     Even  if the name looks like an array element, such as a(b),
     a regular variable is created.   _O_t_h_e_r_V_a_r  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 example, 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  vari-
     able,  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.

     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 vari-  |
     able except by exiting the procedure in which it is defined.  |
     However, it is possible to retarget  an  upvar  variable  by  |
     executing another upvar command.                              |




Tcl                       Last change:                          1






upvar(n)              Tcl Built-In Commands              upvar(n)



BUGS                                                               |
     If _o_t_h_e_r_V_a_r refers to an element of an array, then  variable  |
     traces  set  for  the  entire array will not be invoked when  |
     _m_y_V_a_r is accessed (but traces on the particular element will  |
     still be invoked).  In particular, if the array is env, then  |
     changes made to _m_y_V_a_r will not  be  passed  to  subprocesses  |
     correctly.


KEYWORDS
     context, frame, global, level, procedure, variable












































Tcl                       Last change:                          2