OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tcl/] [doc/] [uplevel.n] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
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.1.1.1 2002-01-16 10:25:25 markom 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
 
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)
78
 
79
.SH KEYWORDS
80
context, level, namespace, stack frame, variables

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.