upvar man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

upvar(n)		     Tcl Built-In Commands		      upvar(n)

______________________________________________________________________________

NAME
       upvar - Create link to variable in a different stack frame

SYNOPSIS
       upvar ?level? otherVar myVar ?otherVar myVar ...?
_________________________________________________________________

DESCRIPTION
       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.   Level  may have any of the forms permitted for the
       uplevel command, and may be omitted if the first letter	of  the	 first
       otherVar	 isn't	#  or  a  digit (it defaults to 1).  For each otherVar
       argument, upvar makes the variable by that name in the procedure	 frame
       given  by  level (or at global level, if level is #0) accessible in the
       current procedure by the name given in the  corresponding  myVar	 argu‐
       ment.  The variable named by otherVar need not exist at the time of the
       call;  it will be created the first time myVar is referenced, just like
       an  ordinary  variable.	 There	must  not exist a variable by the name
       myVar at the time upvar is invoked.  MyVar is  always  treated  as  the
       name  of a variable, not an array element.  Even if the name looks like
       an array element, such as a(b), a regular variable is created.	Other‐
       Var  may	 refer	to  a  scalar variable, an array, or an array element.
       Upvar returns an empty string.

       The upvar command simplifies the implementation of call-by-name	proce‐
       dure  calling  and also makes it easier to build new control constructs
       as Tcl procedures.  For example, consider the following procedure:
	      proc add2 name {
		upvar $name x
		set x [expr $x+2]
	      }
       Add2 is invoked with an argument giving the name of a variable, and  it
       adds  two to the value of that variable.	 Although add2 could have been
       implemented using uplevel instead of upvar, upvar makes it simpler  for
       add2 to access the variable in the caller's procedure frame.

       namespace  eval	is  another way (besides procedure calls) that the Tcl
       naming context can change.  It adds a call frame to the stack to repre‐
       sent  the  namespace  context.	This means each namespace eval command
       counts as another call level for uplevel and upvar commands.  For exam‐
       ple,  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 out‐
       ermost namespace (the global namespace).

       If an upvar variable is unset (e.g. x in add2 above), the unset	opera‐ │
       tion  affects  the  variable  it	 is linked to, not the upvar variable. │
       There is no way to unset an upvar variable except by exiting the proce‐ │
       dure  in	 which	it is defined.	However, it is possible to retarget an │
       upvar variable by executing another upvar command.		       │

Traces and upvar							       │
       Upvar interacts with traces in a	 straightforward  but  possibly	 unex‐ │
       pected  manner.	If a variable trace is defined on otherVar, that trace │
       will be triggered by actions involving myVar.  However, the trace  pro‐ │
       cedure will be passed the name of myVar, rather than the name of other‐ │
       Var.  Thus, the output of the following code will  be  localVar	rather │
       than originalVar:						       │
	      proc traceproc { name index op } {			       │
		puts $name						       │
	      }								       │
	      proc setByUpvar { name value } {				       │
		upvar $name localVar					       │
		set localVar $value					       │
	      }								       │
	      set originalVar 1						       │
	      trace variable originalVar w traceproc			       │
	      setByUpvar originalVar 2					       │
	      }								       │

       If  otherVar refers to an element of an array, then variable traces set │
       for the entire array will not be invoked when myVar  is	accessed  (but │
       traces  on  the particular element will still be invoked).  In particu‐ │
       lar, if the array is env, then changes made to myVar will not be passed │
       to subprocesses correctly.

SEE ALSO
       global(n), namespace(n), uplevel(n), variable(n)

KEYWORDS
       context, frame, global, level, namespace, procedure, variable

Tcl								      upvar(n)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net