[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: uplevel.n,v 1.10 2007/12/13 15:22:33 dgp Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH uplevel n "" Tcl "Tcl Built-In Commands" |
---|
| 12 | .BS |
---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 14 | .SH NAME |
---|
| 15 | uplevel \- Execute a script in a different stack frame |
---|
| 16 | .SH SYNOPSIS |
---|
| 17 | \fBuplevel \fR?\fIlevel\fR?\fI arg \fR?\fIarg ...\fR? |
---|
| 18 | .BE |
---|
| 19 | .SH DESCRIPTION |
---|
| 20 | .PP |
---|
| 21 | All of the \fIarg\fR arguments are concatenated as if they had |
---|
| 22 | been passed to \fBconcat\fR; the result is then evaluated in the |
---|
| 23 | variable context indicated by \fIlevel\fR. \fBUplevel\fR returns |
---|
| 24 | the result of that evaluation. |
---|
| 25 | .PP |
---|
| 26 | If \fIlevel\fR is an integer then |
---|
| 27 | it gives a distance (up the procedure calling stack) to move before |
---|
| 28 | executing the command. If \fIlevel\fR consists of \fB#\fR followed by |
---|
| 29 | a number then the number gives an absolute level number. If \fIlevel\fR |
---|
| 30 | is omitted then it defaults to \fB1\fR. \fILevel\fR cannot be |
---|
| 31 | defaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR. |
---|
| 32 | .PP |
---|
| 33 | For example, suppose that procedure \fBa\fR was invoked |
---|
| 34 | from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR. |
---|
| 35 | Suppose that \fBc\fR invokes the \fBuplevel\fR command. If \fIlevel\fR |
---|
| 36 | is \fB1\fR or \fB#2\fR or omitted, then the command will be executed |
---|
| 37 | in the variable context of \fBb\fR. If \fIlevel\fR is \fB2\fR or \fB#1\fR |
---|
| 38 | then the command will be executed in the variable context of \fBa\fR. |
---|
| 39 | If \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed |
---|
| 40 | at top-level (only global variables will be visible). |
---|
| 41 | .PP |
---|
| 42 | The \fBuplevel\fR command causes the invoking procedure to disappear |
---|
| 43 | from the procedure calling stack while the command is being executed. |
---|
| 44 | In the above example, suppose \fBc\fR invokes the command |
---|
| 45 | .CS |
---|
| 46 | \fBuplevel\fR 1 {set x 43; d} |
---|
| 47 | .CE |
---|
| 48 | where \fBd\fR is another Tcl procedure. The \fBset\fR command will |
---|
| 49 | modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute |
---|
| 50 | at level 3, as if called from \fBb\fR. If it in turn executes |
---|
| 51 | the command |
---|
| 52 | .CS |
---|
| 53 | \fBuplevel\fR {set x 42} |
---|
| 54 | .CE |
---|
| 55 | then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's |
---|
| 56 | context: the procedure \fBc\fR does not appear to be on the call stack |
---|
| 57 | when \fBd\fR is executing. The \fBinfo level\fR command may |
---|
| 58 | be used to obtain the level of the current procedure. |
---|
| 59 | .PP |
---|
| 60 | \fBUplevel\fR makes it possible to implement new control |
---|
| 61 | constructs as Tcl procedures (for example, \fBuplevel\fR could |
---|
| 62 | be used to implement the \fBwhile\fR construct as a Tcl procedure). |
---|
| 63 | .PP |
---|
| 64 | The \fBnamespace eval\fR and \fBapply\fR commands offer other ways |
---|
| 65 | (besides procedure calls) that the Tcl naming context can change. |
---|
| 66 | They add a call frame to the stack to represent the namespace context. |
---|
| 67 | This means each \fBnamespace eval\fR command |
---|
| 68 | counts as another call level for \fBuplevel\fR and \fBupvar\fR commands. |
---|
| 69 | For example, \fBinfo level 1\fR will return a list |
---|
| 70 | describing a command that is either |
---|
| 71 | the outermost procedure call or the outermost \fBnamespace eval\fR command. |
---|
| 72 | Also, \fBuplevel #0\fR evaluates a script |
---|
| 73 | at top-level in the outermost namespace (the global namespace). |
---|
| 74 | .SH EXAMPLE |
---|
| 75 | As stated above, the \fBuplevel\fR command is useful for creating new |
---|
| 76 | control constructs. This example shows how (without error handling) |
---|
| 77 | it can be used to create a \fBdo\fR command that is the counterpart of |
---|
| 78 | \fBwhile\fR except for always performing the test after running the |
---|
| 79 | loop body: |
---|
| 80 | .CS |
---|
| 81 | proc do {body while condition} { |
---|
| 82 | if {$while ne "while"} { |
---|
| 83 | error "required word missing" |
---|
| 84 | } |
---|
| 85 | set conditionCmd [list expr $condition] |
---|
| 86 | while {1} { |
---|
| 87 | \fBuplevel\fR 1 $body |
---|
| 88 | if {![\fBuplevel\fR 1 $conditionCmd]} { |
---|
| 89 | break |
---|
| 90 | } |
---|
| 91 | } |
---|
| 92 | } |
---|
| 93 | .CE |
---|
| 94 | .SH "SEE ALSO" |
---|
| 95 | apply(n), namespace(n), upvar(n) |
---|
| 96 | .SH KEYWORDS |
---|
| 97 | context, level, namespace, stack frame, variables |
---|