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
15 All of the arg arguments are concatenated as if they had been passed to
16 concat; the result is then evaluated in the variable context indicated
17 by level. Uplevel returns the result of that evaluation.
18 If level is an integer then it gives a distance (up the procedure call‐
20 ing stack) to move before executing the command. If level consists of
21 # followed by a number then the number gives an absolute level number.
22 If level is omitted then it defaults to 1. Level cannot be defaulted
23 if the first command argument starts with a digit or #.
24 For example, suppose that procedure a was invoked from top-level, and
26 that it called b, and that b called c. Suppose that c invokes the
27 uplevel command. If level is 1 or #2 or omitted, then the command
28 will be executed in the variable context of b. If level is 2 or #1
29 then the command will be executed in the variable context of a. If
30 level is 3 or #0 then the command will be executed at top-level (only
31 global variables will be visible).
32 The uplevel command causes the invoking procedure to disappear from the
34 procedure calling stack while the command is being executed. In the
35 above example, suppose c invokes the command
36 uplevel 1 {set x 43; d}
38 where d is another Tcl procedure. The set command will modify the
40 variable x in b's context, and d will execute at level 3, as if called
41 from b. If it in turn executes the command
42 uplevel {set x 42}
44 then the set command will modify the same variable x in b's context:
46 the procedure c does not appear to be on the call stack when d is exe‐
47 cuting. The info level command may be used to obtain the level of the
48 current procedure.
49 Uplevel makes it possible to implement new control constructs as Tcl
51 procedures (for example, uplevel could be used to implement the while
52 construct as a Tcl procedure).
53 The namespace eval and apply commands offer other ways (besides proce‐
55 dure calls) that the Tcl naming context can change. They add a call
56 frame to the stack to represent the namespace context. This means each
57 namespace eval command counts as another call level for uplevel and
58 upvar commands. For example, info level 1 will return a list describ‐
59 ing a command that is either the outermost procedure call or the outer‐
60 most namespace eval command. Also, uplevel #0 evaluates a script at
61 top-level in the outermost namespace (the global namespace).
62
64 As stated above, the uplevel command is useful for creating new control
65 constructs. This example shows how (without error handling) it can be
66 used to create a do command that is the counterpart of while except for
67 always performing the test after running the loop body:
68 proc do {body while condition} {
70 if {$while ne "while"} {
71 error "required word missing"
72 }
73 set conditionCmd [list expr $condition]
74 while {1} {
75 uplevel 1 $body
76 if {![uplevel 1 $conditionCmd]} {
77 break
78 }
79 }
80 }
81
83 apply(n), namespace(n), upvar(n)
84
86 context, level, namespace, stack frame, variable
87Tcl uplevel(n)