uplevel(n)

_________________________________________________________________

NAME
       uplevel - Execute a script in a different stack frame

SYNOPSIS
       uplevel ?level? arg ?arg ...?
_________________________________________________________________

DESCRIPTION
       All  of  the arg arguments are concatenated as if they had
       been passed to concat; the result is then evaluated in the
       variable  context indicated by level.  Uplevel returns the
       result of that evaluation.

       If level is an integer then it gives a  distance  (up  the
       procedure calling stack) to move before executing the com-
       mand.  If level consists of # followed by  a  number  then
       the  number  gives  an absolute level number.  If level is
       omitted then it defaults to 1.  Level cannot be  defaulted
       if the first command argument starts with a digit or #.

       For  example,  suppose  that  procedure a was invoked from
       top-level, and that it called b,  and  that  b  called  c.
       Suppose that c invokes the uplevel command.  If level is 1
       or #2  or omitted, then the command will  be  executed  in
       the  variable  context of b.  If level is 2 or #1 then the
       command will be executed in the variable context of a.  If
       level is 3 or #0 then the command will be executed at top-
       level (only global variables will be visible).

       The uplevel command causes the invoking procedure to  dis-
       appear  from the procedure calling stack while the command
       is being  executed.   In  the  above  example,  suppose  c
       invokes the command
              uplevel 1 {set x 43; d}
       where  d  is  another Tcl procedure.  The set command will
       modify the variable x in b's context, and d  will  execute
       at  level  3, as if called from b.  If it in turn executes
       the command
              uplevel {set x 42}
       then the set command will modify the same  variable  x  in
       b's context:  the procedure c does not appear to be on the
       call stack  when  d  is  executing.   The  command  ``info
       level''  may  be  used  to obtain the level of the current
       procedure.

       Uplevel makes it possible to implement  new  control  con-
       structs  as  Tcl procedures (for example, uplevel could be
       used to implement the while construct as a Tcl procedure).

       namespace  eval  is  another way (besides procedure calls)
       that the Tcl naming context can change.  It  adds  a  call

       frame  to  the  stack  to represent the namespace context.
       This means each namespace eval command counts  as  another
       call  level  for uplevel and upvar commands.  For example,
       info level 1 will return a list describing a command  that
       is  either  the  outermost procedure call or the outermost
       namespace eval command.   Also,  uplevel  #0  evaluates  a
       script at top-level in the outermost namespace (the global
       namespace).

SEE ALSO
       namespace(n) 

KEYWORDS
       context, level, namespace, stack frame, variables