Manual Pages for UNIX Darwin command on man upvar

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

NAME

upvar - Create link to variable in a different stack frame

SYNOPSIS

uuppvvaarr ?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 procedure call or to global variables. Level may have any of the forms permitted for the uupplleevveell command, and may be omitted if the first letter of the first

otherVar isn't ## or a digit (it defaults to 11). For each otherVar

argument, uuppvvaarr makes the variable by that name in the procedure frame

given by level (or at global level, if level is ##00) accessible in the

current procedure by the name given in the corresponding myVar argu-

ment. The variable named by otherVar 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 uuppvvaarr 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 aa((bb)), a regular variable is created. Other-

Var may refer to a scalar variable, an array, or an array element. UUppvvaarr returns an empty string.

The uuppvvaarr command 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: pprroocc aadddd22 nnaammee {{

uuppvvaarr $$nnaammee xx

sseett xx [[eexxpprr $$xx++22]]

}} AAdddd22 is invoked with an argument giving the name of a variable, and it adds two to the value of that variable. Although aadddd22 could have been implemented using uupplleevveell instead of uuppvvaarr, uuppvvaarr makes it simpler for aadddd22 to access the variable in the caller's procedure frame. nnaammeessppaaccee eevvaall is 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 nnaammeessppaaccee eevvaall command

counts as another call level for uupplleevveell and uuppvvaarr commands. For exam-

ple, iinnffoo lleevveell 11 will return a list describing a command that is either the outermost procedure call or the outermost nnaammeessppaaccee eevvaall

command. Also, uupplleevveell ##00 evaluates a script at top-level in the out-

ermost namespace (the global namespace).

If an upvar variable is unset (e.g. xx in aadddd22 above), the uunnsseett opera- |

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 uuppvvaarr command. |

TTrraacceess aanndd uuppvvaarr |

Upvar interacts with traces in a straightforward but possibly unex- |

pected manner. If a variable trace is defined on otherVar, that trace |

will be triggered by actions involving myVar. However, the trace pro- |

cedure will be passed the name of myVar, rather than the name of other- |

Var. Thus, the output of the following code will be llooccaallVVaarr rather | than oorriiggiinnaallVVaarr: | pprroocc ttrraacceepprroocc {{ nnaammee iinnddeexx oopp }} {{ |

ppuuttss $$nnaammee |

}} | pprroocc sseettBByyUUppvvaarr {{ nnaammee vvaalluuee }} {{ |

uuppvvaarr $$nnaammee llooccaallVVaarr |

sseett llooccaallVVaarr $$vvaalluuee |

}} | sseett oorriiggiinnaallVVaarr 11 | ttrraaccee vvaarriiaabbllee oorriiggiinnaallVVaarr ww ttrraacceepprroocc | sseettBByyUUppvvaarr oorriiggiinnaallVVaarr 22 | }} | 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 particu- |

lar, if the array is eennvv, then changes made to myVar will not be passed | to subprocesses correctly.