uplevel(n)

💅 uplevel(n) — bestie edition ✨

okay so this is the Tcl Built-In Commands page for uplevel, and it's literally the girlboss of stack frames. let's get into it 🫶

---

✨ NAME ✨

uplevel — execute a script in a different stack frame 💫

---

🌸 SYNOPSIS 🌸

uplevel ?level? arg ?arg ...?

---

🎀 DESCRIPTION 🎀

okay so first thing: all of the arg arguments get concatenated together, exactly as if you'd passed them to concat. then the result of that gets evaluated in the variable context that level points at. and uplevel returns the result of that evaluation. no cap. 🦋

now, level. if level is an integer, it's a distance — like, how far up the procedure calling stack you wanna scoot before running the command. if level is a # followed by an integer, then that's an absolute level instead. and if you just... don't give a level at all? it defaults to 1. 💅

⚠️ but bestie listen — level cannot be defaulted if the first command argument is an integer or starts with #. so watch out for that, fr fr.

so like, picture this: procedure a got invoked from top-level, and a called b, and b called c. and c invokes the uplevel command. here's the vibe check:

• if level is 1 or #2 or omitted → the command runs in the variable context of b 🌸
• if level is 2 or #1 → the command runs in the variable context of a ✨
• if level is 3 or #0 → the command runs at top-level (only global variables will be visible) 👑

and here's the main character energy part: uplevel causes the invoking procedure to disappear from the procedure calling stack while the command is being executed. iconic, honestly.

so in that same example, say c invokes this:

uplevel 1 {set x 43; d}

where d is another Tcl procedure. the set command is gonna modify the variable x in b's context, and d will execute at level 3, like it was called from b. and if d in turn executes this:

uplevel {set x 42}

then that set command modifies the same variable x in b's context. because c does not appear to be on the call stack at all while d is executing. it's giving ghosting but make it stack frames 💀

oh and you can use the info level command to grab the level of the current procedure. handy 🍓

uplevel is what makes it possible to implement new control constructs as Tcl procedures — like, for example, uplevel could be used to implement the while construct as a Tcl procedure. obsessed 😭

also important: the namespace eval and apply commands offer other ways (besides procedure calls) that the Tcl naming context can change. they add a call frame to the stack to represent the namespace context. which means each namespace eval command counts as another call level for uplevel and upvar commands. so for example, info level 1 will return a list describing a command that is either the outermost procedure call or the outermost namespace eval command. also, uplevel #0 evaluates a script at top-level in the outermost namespace (the global namespace). noted, bestie 📝

---

🌈 EXAMPLE 🌈

like we said, uplevel is useful for creating new control constructs. this example shows how (without error handling) it can be used to create a do command that's the counterpart of while — except it always performs the test after running the loop body:

proc do {body while condition} {
    if {$while ne "while"} {
        error "required word missing"
    }
    set conditionCmd [list expr $condition]
    while {1} {
        uplevel 1 $body
        if {![uplevel 1 $conditionCmd]} {
            break
        }
    }
}

slay. periodt. 💖

---

🦋 SEE ALSO 🦋

• apply(n)
• namespace(n)
• upvar(n)

---

👑 KEYWORDS 👑

• context
• level
• namespace
• stack frame
• variable

---

and that's the whole thing, bestie!! 💜 this was the uplevel(n) page from Tcl — the Tcl Built-In Commands manual — so go forth and uplevel responsibly. mwah 🎀💅✨