TIP 635: Introspection for 'upvar' and 'namespace upvar'

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Author:		Schelte Bron <[email protected]>
State:		Draft
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:

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

Copyright

This document has been placed in the public domain.