1uplevel(n) Tcl Built-In Commands uplevel(n)
2______________________________________________________________________________
6
8 uplevel - Execute a script in a different stack frame
9
11 uplevel ?level? arg ?arg ...?
12_________________________________________________________________
13
16 All of the arg arguments are concatenated as if they had been passed to
17 concat; the result is then evaluated in the variable context indicated
18 by level. Uplevel returns the result of that evaluation.
19 If level is an integer then it gives a distance (up the procedure call‐
21 ing stack) to move before executing the command. If level consists of
22 # followed by a number then the number gives an absolute level number.
23 If level is omitted then it defaults to 1. Level cannot be defaulted
24 if the first command argument starts with a digit or #.
25 For example, suppose that procedure a was invoked from top-level, and
27 that it called b, and that b called c. Suppose that c invokes the
28 uplevel command. If level is 1 or #2 or omitted, then the command
29 will be executed in the variable context of b. If level is 2 or #1
30 then the command will be executed in the variable context of a. If
31 level is 3 or #0 then the command will be executed at top-level (only
32 global variables will be visible).
33 The uplevel command causes the invoking procedure to disappear from the
35 procedure calling stack while the command is being executed. In the
36 above example, suppose c invokes the command
37 uplevel 1 {set x 43; d}
38 where d is another Tcl procedure. The set command will modify the
39 variable x in b's context, and d will execute at level 3, as if called
40 from b. If it in turn executes the command
41 uplevel {set x 42}
42 then the set command will modify the same variable x in b's context:
43 the procedure c does not appear to be on the call stack when d is exe‐
44 cuting. The command ``info level'' may be used to obtain the level of
45 the current procedure.
46 Uplevel makes it possible to implement new control constructs as Tcl
48 procedures (for example, uplevel could be used to implement the while
49 construct as a Tcl procedure).
50 namespace eval is another way (besides procedure calls) that the Tcl
52 naming context can change. It adds a call frame to the stack to repre‐
53 sent the namespace context. This means each namespace eval command
54 counts as another call level for uplevel and upvar commands. For exam‐
55 ple, info level 1 will return a list describing a command that is
56 either the outermost procedure call or the outermost namespace eval
57 command. Also, uplevel #0 evaluates a script at top-level in the out‐
58 ermost namespace (the global namespace).
59
61 As stated above, the uplevel command is useful for creating new control
62 constructs. This example shows how (without error handling) it can be
63 used to create a do command that is the counterpart of while except for
64 always performing the test after running the loop body:
65 proc do {body while condition} {
66 if {$while ne "while"} {
67 error "required word missing"
68 }
69 set conditionCmd [list expr $condition]
70 while {1} {
71 uplevel 1 $body
72 if {![uplevel 1 $conditionCmd]} {
73 break
74 }
75 }
76 }
77
80 namespace(n), upvar(n)
81
84 context, level, namespace, stack frame, variables
85Tcl uplevel(n)