I can't understand how uplevel works - tcl

Question

Why do I get an error ?
#!/usr/bin/tclsh
proc add {a} {
uplevel 1 $a
puts $a
}
set n 0
add $n
I can't understand how uplevel works

Answer 1

uplevel executes some code in a different "stack frame" -- each time you invoke a procedure (and some other ways), Tcl adds an execution frame to the call stack.
Here's an example:
proc foo {} {
set fooVar 42
bar {expr {$fooVar + 21}}
}
proc bar {code} {
puts "in bar, code is: [list $code]"
puts "in bar, the fooVar variable [expr {[info exists fooVar] ? "does" : "does not"}] exist"
uplevel 1 $code
}
Running the foo procedure:
% foo
in bar, code is: {expr {$fooVar + 21}}
in bar, the fooVar variable does not exist
63
This is demonstrating that, because we're executing the code in one frame up in the call stack, the code fragment does have access to a local variable in that frame.
If we try to run bar with the same code block from the glocal scope, we'll
see an error:
% bar {expr {$fooVar + 21}}
in bar, code is: {expr {$fooVar + 21}}
in bar, the fooVar variable does not exist
can't read "fooVar": no such variable
But if we set the variable in the global scope, it works as expected:
% set fooVar -1
-1
% bar {expr {$fooVar + 21}}
in bar, code is: {expr {$fooVar + 21}}
in bar, the fooVar variable does not exist
20
Together with upvar, the uplevel command allows you to implement your own control structures -- Tcl is really an incredibly flexible language. An example:
proc foreachWithIndex {variableNames aList code} {
lassign $variableNames idxVar elemVar
upvar 1 $idxVar idx
upvar 1 $elemVar elem
set idx 0
foreach elem $aList {
uplevel 1 $code
incr idx
}
}
foreachWithIndex {i e} {a b c d} {puts "$i -> $e"}
0 -> a
1 -> b
2 -> c
3 -> d

Answer 2

If we run your code, we get the error message: invalid command name "0".
Let's investigate by printing the stack trace:
% puts $errorInfo
invalid command name "0"
while executing
"0"
("uplevel" body line 1)
invoked from within
"uplevel 1 $a"
(procedure "add" line 2)
invoked from within
"add $n"
That looks curious, but it is fine because the value of $a is 0 because the argument to add is the value of $n which is 0. The arguments to uplevel (after an optional first pseudo-numeric argument, which you are supplying; good!) are a script (with multiple arguments being concatenated). The string 0 can be a script, if you happen to have a command in scope whose name is the single digit 0, but that's pretty unusual.
Once it's got the script to run, uplevel 1 runs the script in the context of the caller of the current procedure. (Technically, it steps up 1 stack frame and runs it there. Tcl stack frames actually form a tree, though there's usually just one branch on the tree at a time; uplevel forms another branch.)
The two common forms of uplevel are uplevel 1 (for “run in the caller”) and uplevel #0 (for “run in the global scope”). There are others, but they're uncommon. Don't use uplevel 0; it's exactly like eval and confusion reigns if you get obscure like that.
It's good practice to usually keep your uplevel script forms to one of:
An argument passed in by the caller. (This is your script's case.)
A constant script.
A single command call generated by calling list. You can use {*}expansion when generating the list; this is a good way to handle a list of values or a command prefix.
All of these have been found to be generally non-confusing and fairly easy to use correctly (without weird hazards). Other options tend to be tricky.
I'm guessing your code should have actually been written like this:
proc add {varName} {
upvar 1 $varName v
set v [expr {$v + 1}]
# Or maybe: incr v
puts $v
}
set n 0
add n
The upvar command uses the same level resolution rules as uplevel, but instead aliases a named variable in that scope to the other local name in the current scope. A call to upvar #0 foo foo is functionally equivalent to the apparently simpler global foo.