'''`[http://www.tcl.tk/man/tcl/TclCmd/unset.htm%|%unset]`''', a [Tcl Commands%|%built-in] [Tcl] [command], removes one or more
[variable%|%variables].



** Synopsis **

    :   '''unset''' ?'''-nocomplain'''? ''varName'' ?''varName ...''?



** Documentation **

   [http://www.tcl.tk/man/tcl/TclCmd/unset.htm%|%official reference]:   



** Description **

It is an error for the variables to not already exist, the name to be illegal,
etc. This error can be suppressed with the '''`-nocomplain`''' option.

A [trace] on the variable can resurrect it.

[DKF]: In 8.6, `[unset]` is bytecode compiled. (And don't use `catch
{unset foo}`; the operationally-equivalent `unset -nocomplain foo`
generates much better bytecode.)

----

In retrospect, `unset` should have been designed so that it was not an error to
unset a variable that didn't exist, in which case `-nocomplain` would not have
unset a variable that didn't exist, in which case -nocomplain would not have

[aspect]: more support for the above?  I removed it earlier as it's not a sentiment I hear often in the community, and error-by-default seems the appropriate behaviour to me.  Usually (ime) a "no such variable!" error from `unset` identifies a typo I'd rather catch early rather than a spot for `-nocomplain`.
[PYK] 2014-08-15: I added the comment in question after `unset` was mentioned in


Unsetting a variable will remove all the [trace]s on it.  If there are any `variable unset` traces, they will first be called.

Proc-local variables are implicitly unset when the proc returns.  By using an unset trace, we can do sneaky things:

======
package require lambda 
proc finally {script} {
    set v [lindex [uplevel 1 {info locals}] 0]
    tailcall trace add variable $v unset [lambda args $script]
}

proc test {n cmd} {
    finally {puts "Returning"}
    for {set x 0} {$x < $n} {incr x} {
        puts "$x ... [{*}$cmd]"
    }
}

test 3 {info level}
# 0 ... 1
# 1 ... 1
# 2 ... 1
# Returning
test 3 {expr 1/0}
# Returning
# ERROR: divide by zero
# while evaluating {test 3 {expr 1/0}}
======

** Unset and Tk `-variable` options **

Unsetting a variable that is still bound to an [entry] widget through the `-textvariable` option (for example), strange things may happen (they did in 2002 ...).  Beware if you do this!

Tcl8.6 offers a number of ways to protect against this, which amount to tying the object's lifecycle to the variable.  You can place them both in an object, or use an unset trace on the variable, or interpose a megawidget that binds correctly with [namespace upvar] ...


** Unset and Upvar **

Unsetting an [upvar]-bound variable will also unset all its other bindings (thanks [PYK] for correcting previous text here):
Unsetting an [upvar]-bound variable only breaks the binding - other references to the same variable are not affected.  Of course, [upvar] can replace an `upvar`ed variable without unsetting it first, so you may not need this.
======
[PYK] 2014-08-14:  Not true.  Unsetting an `[upvar]`-bound variable affects all
other references to the same variable:

set var1 one

proc p1 {} {
    upvar 1 var1 var1 
    unset var1
}

puts [info exists var1] ;# -> 1
p1
puts [info exists var1] ;# -> 0
======

If you want to redirect an upvar binding, you can simply "upvar over the top of it":
======
----


'''`[http://www.tcl.tk/man/tcl/TclCmd/unset.htm%|%unset]`''', a [Tcl