diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
commit | 5514e37335c012cc70f5b9aee3cedfe3d57f583f (patch) | |
tree | 4ba7d8aad13735e52f59bdce7ca5ba3151ebd7e3 /tcl8.6/doc/upvar.n | |
parent | 768f87f613cc9789fcf8073018fa02178c8c91df (diff) | |
download | blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.zip blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.gz blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.bz2 |
undo subtree
Diffstat (limited to 'tcl8.6/doc/upvar.n')
-rw-r--r-- | tcl8.6/doc/upvar.n | 122 |
1 files changed, 0 insertions, 122 deletions
diff --git a/tcl8.6/doc/upvar.n b/tcl8.6/doc/upvar.n deleted file mode 100644 index 91defe6..0000000 --- a/tcl8.6/doc/upvar.n +++ /dev/null @@ -1,122 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH upvar n "" Tcl "Tcl Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -upvar \- Create link to variable in a different stack frame -.SH SYNOPSIS -\fBupvar \fR?\fIlevel\fR? \fIotherVar myVar \fR?\fIotherVar myVar \fR...? -.BE - -.SH DESCRIPTION -.PP -This command arranges for one or more local variables in the current -procedure to refer to variables in an enclosing procedure call or -to global variables. -\fILevel\fR may have any of the forms permitted for the \fBuplevel\fR -command, and may be omitted (it defaults to \fB1\fR). -For each \fIotherVar\fR argument, \fBupvar\fR makes the variable -by that name in the procedure frame given by \fIlevel\fR (or at -global level, if \fIlevel\fR is \fB#0\fR) accessible -in the current procedure by the name given in the corresponding -\fImyVar\fR argument. -The variable named by \fIotherVar\fR need not exist at the time of the -call; it will be created the first time \fImyVar\fR is referenced, just like -an ordinary variable. There must not exist a variable by the -name \fImyVar\fR at the time \fBupvar\fR is invoked. -\fIMyVar\fR is always treated as the name of a variable, not an -array element. An error is returned if the name looks like an array element, -such as \fBa(b)\fR. -\fIOtherVar\fR may refer to a scalar variable, an array, -or an array element. -\fBUpvar\fR returns an empty string. -.PP -The \fBupvar\fR command simplifies the implementation of call-by-name -procedure calling and also makes it easier to build new control constructs -as Tcl procedures. -For example, consider the following procedure: -.PP -.CS -proc \fIadd2\fR name { - \fBupvar\fR $name x - set x [expr {$x + 2}] -} -.CE -.PP -If \fIadd2\fR is invoked with an argument giving the name of a variable, -it adds two to the value of that variable. -Although \fIadd2\fR could have been implemented using \fBuplevel\fR -instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fIadd2\fR -to access the variable in the caller's procedure frame. -.PP -\fBnamespace eval\fR 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 \fBnamespace eval\fR command -counts as another call level for \fBuplevel\fR and \fBupvar\fR commands. -For example, \fBinfo level\fR \fB1\fR will return a list -describing a command that is either -the outermost procedure call or the outermost \fBnamespace eval\fR command. -Also, \fBuplevel #0\fR evaluates a script -at top-level in the outermost namespace (the global namespace). -.PP -If an upvar variable is unset (e.g. \fBx\fR in \fBadd2\fR above), the -\fBunset\fR operation affects the variable it is linked to, not the -upvar variable. There is no way to unset an upvar variable except -by exiting the procedure in which it is defined. However, it is -possible to retarget an upvar variable by executing another \fBupvar\fR -command. -.SH "TRACES AND UPVAR" -.PP -Upvar interacts with traces in a straightforward but possibly -unexpected manner. If a variable trace is defined on \fIotherVar\fR, that -trace will be triggered by actions involving \fImyVar\fR. However, -the trace procedure will be passed the name of \fImyVar\fR, rather -than the name of \fIotherVar\fR. Thus, the output of the following code -will be -.QW "\fIlocalVar\fR" -rather than -.QW "\fIoriginalVar\fR" : -.PP -.CS -proc \fItraceproc\fR { name index op } { - puts $name -} -proc \fIsetByUpvar\fR { name value } { - \fBupvar\fR $name localVar - set localVar $value -} -set originalVar 1 -trace variable originalVar w \fItraceproc\fR -\fIsetByUpvar\fR originalVar 2 -.CE -.PP -If \fIotherVar\fR refers to an element of an array, then variable -traces set for the entire array will not be invoked when \fImyVar\fR -is accessed (but traces on the particular element will still be -invoked). In particular, if the array is \fBenv\fR, then changes -made to \fImyVar\fR will not be passed to subprocesses correctly. -.SH EXAMPLE -A \fBdecr\fR command that works like \fBincr\fR except it subtracts -the value from the variable instead of adding it: -.PP -.CS -proc decr {varName {decrement 1}} { - \fBupvar\fR 1 $varName var - incr var [expr {-$decrement}] -} -.CE -.SH "SEE ALSO" -global(n), namespace(n), uplevel(n), variable(n) -.SH KEYWORDS -context, frame, global, level, namespace, procedure, upvar, variable -.\" Local Variables: -.\" mode: nroff -.\" End: |