tcl7.6 User Commands - upvar






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 enclosing pro-
     cedure 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) accessi-
     ble in the current  procedure  by  the  name  given  in  the
     corresponding  myVar argument.  The variable named by other-
     Var need not exist at the time of  the  call;   it  will  be
     created  the  first  time  myVar is referenced, 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 variable,  not  an  array  element.
     Even  if the name looks like an array element, such as a(b),
     a regular variable is created.   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 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.                              |


BUGS |

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



KEYWORDS

     context, frame, global, level, procedure, variable