Tcl uplevel Command

last modified October 20, 2026

The Tcl uplevel command evaluates a script in a different stack level. It's a powerful feature for controlling execution context. This command is essential for advanced Tcl programming techniques.

Basic Definition

The uplevel command executes a script in the variable context of a different stack level. It can access variables from higher stack frames.

Syntax: uplevel ?level? arg ?arg ...?. The level specifies which stack frame to use (default is 1, the caller). A number such as 2 is relative to the current frame, while #0 is the global frame and #1 the first procedure called from it. The args form the script to evaluate; several args are joined with spaces as concat does.

Simple uplevel Example

This demonstrates basic usage of uplevel to access variables from a higher stack level.

basic_uplevel.tcl

proc outer {} {
    set x 10
    inner
}

proc inner {} {
    uplevel {puts "x is $x"}
}

outer

The inner procedure uses uplevel to access the x variable from its caller's context. This prints "x is 10" when executed.

Modifying Variables with uplevel

uplevel can modify variables in the caller's context.

uplevel_modify.tcl

proc increment {} {
    uplevel {incr counter}
}

set counter 5
increment
puts "Counter is now $counter"

This example shows how uplevel can modify variables in the caller's scope. The increment procedure increases the counter variable from its caller's context.

Specifying Stack Levels

You can specify exactly which stack level to use with uplevel.

uplevel_levels.tcl

proc level1 {} {
    set x 100
    level2
}

proc level2 {} {
    set x 200
    level3
}

proc level3 {} {
    uplevel 1 {puts "Level1 x: $x"}
    uplevel 2 {puts "Level2 x: $x"}
}

level1

This demonstrates accessing different stack levels. Relative level 1 is the caller of level3, which is the procedure level2, so the first line prints its x (200). Level 2 is level1, so the second line prints 100. The names in the output ("Level1", "Level2") refer to the relative levels, not to the procedure names.

Creating Control Structures

uplevel is often used to create custom control structures.

uplevel_control.tcl

proc repeat {count script} {
    for {set i 0} {$i < $count} {incr i} {
        uplevel $script
    }
}

set x 0
repeat 3 {
    incr x
    puts "x is now $x"
}

This creates a repeat command that executes a script multiple times. The script runs in the caller's context, allowing it to modify variables.

Error Handling with uplevel

An error in a script run by uplevel propagates out of the uplevel command like an error from any other command, so it can be caught with catch.

uplevel_error.tcl

proc safe_eval {script} {
    if {[catch {uplevel $script} result]} {
        puts "Error: $result"
        return 0
    }
    return 1
}

safe_eval {error "Something went wrong"}
safe_eval {puts "This works fine"}

This shows how to handle errors when using uplevel. The catch command captures errors from the uplevel execution, and the procedure returns 0 or 1 to tell the caller whether the script succeeded.

Combining uplevel with upvar

uplevel can be combined with upvar for more control.

uplevel_upvar.tcl

proc process_vars {name} {
    upvar 1 $name v
    set v [expr {$v * 2}]
    uplevel 1 {set y [expr {$a + 10}]}
}

set a 5
set result [process_vars a]
puts "a: $a, result: $result"

This combines upvar and uplevel to modify variables and create new ones in the caller's context. The upvar command links the variable named by the argument and doubles it, and uplevel runs a script in the caller, which creates the variable y there and returns its value. The output shows "a: 10, result: 20".

Best Practices

Braces: Pass the script in braces so that variables are substituted at the target level, not in the calling procedure.
Levels: Be explicit about stack levels when needed.
Scope: Understand variable scope implications.
Errors: Always consider error handling with uplevel.
Alternatives: Consider if upvar or other methods would be clearer.

This tutorial covered the Tcl uplevel command with practical examples showing its usage in different scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Tcl Tutorials.

Ebooks