Author:		Schelte Bron <[email protected]>
State:		Withdrawn
Type:		Project
Vote:		Pending
Created:	26-Aug-2022
Tcl-Version:	9.0
Tcl-Branch:	tip-635
Keywords:	upvar,namespace upvar

---

Abstract

This tip proposes to provide script-level access to the way variables are linked together via 'upvar' and 'namespace upvar'.

Note: This TIP depends on functionality introduced by TIP 634, which is why it cannot target Tcl 8.7.

Rationale

The 'upvar' and 'namespace upvar' commands allow variables to be accessed using different names. In some circumstances it may be useful to be able to inquire about the mapping of a variable alias to the original name. This is especially relevant in callback handlers for variable traces on an entire array, after TIP #634 gets implemented.

Specification

A new info subcommand, 'info upvar' is implemented. It takes one argument: The name of a scalar variable or array (array elements can't be an alias). The command returns a list of variable length, depending on the situation:

• Empty list: The name is not a link to another variable.
• Two-element list: The name is a link to another scalar variable or array.
• Three-element list: The name is a link to an array element.

The array elements, if present, have the following meaning:

1. level: The absolute stack level of the target variable
2. target: The target scalar variable or array of the upvar
3. element: The subscript within the array of a target array element

If the name is not a scalar variable or array, the command throws an error.

If the target of the link is a namespace variable, the fully qualified name of that variable is reported.

The resulting target may itself again be an alias. The command can be invoked repeatedly until an empty list is returned to get the real variable.

set rc [info upvar $name]
while {[llength $rc]} {
    if {[llength $rc] > 2} {
        lassign $rc level target element
    } else {
        lassign $rc level target
    }
    set rc [uplevel #$level [list info upvar $target]]
}

Considerations

This TIP was supposed to address an issue that arrose after part 1 of TIP 634 would be implemented. However, after further thought, it seems the issue can be solved more elegantly by an amendment to TIP 634. If TIP 634 is accepted with the amendment, this TIP becomes effectively obsolete.

Reference Implementation

See branch tip-635

Withdrawal

The amendment to TIP 634 to always report the array index in the 'name2' argument for any variable that ultimately refers to an array element has made this TIP largely obsolete. For that reason, I withdraw this TIP.

Copyright

This document has been placed in the public domain.