tcl/doc/uplevel.n

   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$
   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
  20 .SH DESCRIPTION
  21 .PP
  22 All of the \fIarg\fR arguments are concatenated as if they had
  23 been passed to \fBconcat\fR; the result is then evaluated in the
  24 variable context indicated by \fIlevel\fR.  \fBUplevel\fR returns
  25 the result of that evaluation.
  26 .PP
  27 If \fIlevel\fR is an integer then
  28 it gives a distance (up the procedure calling stack) to move before
  29 executing the command.  If \fIlevel\fR consists of \fB#\fR followed by
  30 a number then the number gives an absolute level number.  If \fIlevel\fR
  31 is omitted then it defaults to \fB1\fR.  \fILevel\fR cannot be
  32 defaulted if the first \fIcommand\fR argument starts with a digit or \fB#\fR.
  33 .PP
  34 For example, suppose that procedure \fBa\fR was invoked
  35 from top-level, and that it called \fBb\fR, and that \fBb\fR called \fBc\fR.
  36 Suppose that \fBc\fR invokes the \fBuplevel\fR command.  If \fIlevel\fR
  37 is \fB1\fR or \fB#2\fR  or omitted, then the command will be executed
  38 in the variable context of \fBb\fR.  If \fIlevel\fR is \fB2\fR or \fB#1\fR
  39 then the command will be executed in the variable context of \fBa\fR.
  40 If \fIlevel\fR is \fB3\fR or \fB#0\fR then the command will be executed
  41 at top-level (only global variables will be visible).
  42 .PP
  43 The \fBuplevel\fR command causes the invoking procedure to disappear
  44 from the procedure calling stack while the command is being executed.
  45 In the above example, suppose \fBc\fR invokes the command
  46 .CS
  47 \fBuplevel 1 {set x 43; d}\fR
  48 .CE
  49 where \fBd\fR is another Tcl procedure.  The \fBset\fR command will
  50 modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
  51 at level 3, as if called from \fBb\fR.  If it in turn executes
  52 the command
  53 .CS
  54 \fBuplevel {set x 42}\fR
  55 .CE
  56 then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
  57 context:  the procedure \fBc\fR does not appear to be on the call stack
  58 when \fBd\fR is executing.  The command ``\fBinfo level\fR'' may
  59 be used to obtain the level of the current procedure.
  60 .PP
  61 \fBUplevel\fR makes it possible to implement new control
  62 constructs as Tcl procedures (for example, \fBuplevel\fR could
  63 be used to implement the \fBwhile\fR construct as a Tcl procedure).
  64 .PP
  65 \fBnamespace eval\fR is another way (besides procedure calls)
  66 that the Tcl naming context can change.
  67 It adds a call frame to the stack to represent the namespace context.
  68 This means each \fBnamespace eval\fR command
  69 counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
  70 For example, \fBinfo level 1\fR will return a list
  71 describing a command that is either
  72 the outermost procedure call or the outermost \fBnamespace eval\fR command.
  73 Also, \fBuplevel #0\fR evaluates a script
  74 at top-level in the outermost namespace (the global namespace).
  75
  76 .SH "SEE ALSO"
  77 namespace(n), upvar(n)
  78
  79 .SH KEYWORDS
  80 context, level, namespace, stack frame, variables