CLASS

tcl.lang.Interp -- This manual entry contains Interp methods that manipulate Tcl variables.

METHODS

void setVar(String name, TclObject value, int flags) throws TclException

void setVar(String part1, String part2, TclObjectvalue, int flags) throws TclException

TclObject getVar(String name, int flags) throws TclException

TclObject getVar(String part1, String part2, int flags) throws TclException

void unsetVar(String name, int flags) throws TclException

void unsetVar(String part1, String part2, int flags) throws TclException

OTHER METHODS

ARGUMENTS

DESCRIPTION

setVar

getVar

unsetVar

OVERLOADING

FLAGS

TCL.GLOBAL_ONLY

TCL.NAMESPACE_ONLY

TCL.APPEND_VALUE

TCL.LIST_ELEMENT

EQUIVALENT C FUNCTIONS

SEE ALSO

KEYWORDS

CLASS

METHODS

void setVar(String name, TclObject value, int flags) throws TclException

void setVar(String part1, String part2, TclObjectvalue, int flags) throws TclException

TclObject getVar(String name, int flags) throws TclException

TclObject getVar(String part1, String part2, int flags) throws TclException

void unsetVar(String name, int flags) throws TclException

void unsetVar(String part1, String part2, int flags) throws TclException

OTHER METHODS

ARGUMENTS

String name ()

Name of variable. May refer to a scalar variable or an array variable with a parenthesized index.

String part1 ()

Name of scalar or array variable. If part2 is null, part1 is treated like name. Otherwise, part1 must be an array variable with no index.

String part2 ()

If not null, gives name of element within array; in this case part1 must refer to an array variable with no index.

TclObject value ()

The TclObject containing the new value for the variable.

int flags ()

OR-ed combination of bits providing additional information. See below for valid values.

DESCRIPTION

setVar

The setVar methods create a new variable or modify the existing variable whose name is name or the combination of part1 and part2. See the OVERLOADING section below to learn how arguments part1 and part2 are combined to form a valid variable name. These methods set the given variable to the value given by value and return void. If an error occurs in setting the variable (e.g. an array variable is referenced without giving an index into the array) a TclException is generated and an error message is left in interp's result unless the TCL.DONT_THROW_EXCEPTION flag bit is set.

getVar

The getVar methods return the current value of the variable whose name is name or the combination of part1 and part2 (as described for the setVar method above). The return value is a TclObject containing the variable's value. If an error occurs while reading the variable (e.g. the variable doesn't exist or an array element is specified for a scalar variable), then a TclException is generated and an error message is left in interp's result unless the TCL.DONT_THROW_EXCEPTION flag bit is set.

unsetVar

The unsetVar methods may be used to remove a variable, so that future attempts to read the variable will generate exceptions. The arguments to these methods are treated in the same way as the arguments to the methods above. If the variable cannot be removed because it doesn't exist then a TclException is generated and an error message is left in interp's result unless the TCL.DONT_THROW_EXCEPTION flag bit is set. If an array element is specified, the given element is removed but the array remains. If an array name is specified without an index, then the entire array is removed.

OVERLOADING

[1]

If setVar, getVar, or unsetVar is invoked with the name argument, the variable name is given as a single string, name. If name contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is treated as an index (which can have any string value) and the characters before the first open parenthesis are treated as the name of an array variable. If name doesn't have parentheses as described above, then the entire string is treated as the name of a scalar variable.

[2]

If the part1 and part2 arguments are provided and part2 is not null, then the variable part1(part2) is specified. The part1 argument contains the array name, and the part2 argument contains the index.

[3]

If the part1 and part2 arguments are provided and part2 is null, then part1 is treated the same as the name argument in step [1].

FLAGS

TCL.GLOBAL_ONLY

Under normal circumstances, the procedures look up variables as follows. If a procedure call is active in Interp, the variable is looked up at the current level of procedure call. Otherwise, the variable is looked up first in the current namespace, then in the global namespace. However, if this bit is set in flags then the variable is looked up only in the global namespace, even if there is an active procedure call. If both TCL.GLOBAL_ONLY and TCL.NAMESPACE_ONLY are given, TCL.GLOBAL_ONLY is ignored.

TCL.NAMESPACE_ONLY

If this bit is set in flags then the variable is looked up only in the current namespace; if a procedure is active, its variables are ignored, and the global namespace is also ignored unless it is the current namespace.

TCL.APPEND_VALUE

If this bit is set then value is appended to variable's the current value instead of replacing it. If the variable is currently undefined, then the bit is ignored. This bit is only used by the setVar methods.

TCL.LIST_ELEMENT

If this bit is set, then value is converted to a valid Tcl list element before setting (or appending to) the variable. A separator space is appended before the new list element unless the list element is going to be the first element in a list or sublist (i.e. the variable's current value is empty, or contains the single character ``{'', or ends in `` }'').

EQUIVALENT C FUNCTIONS

SEE ALSO

KEYWORDS

Copyright © 1998 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.