tcl.lang
Class Var

java.lang.Object
  tcl.lang.Var

public class Var
extends Object

Field Summary

static int	EXPLICIT_LOCAL_NAME
String	hashKey The key under which this variable is stored in the hash table.
Namespace	ns Reference to the namespace that contains this variable.
int	refCount Counts number of active uses of this variable, not including its entry in the call frame or the hash table: 1 for each additional variable whose link points here, 1 for each nested trace active on variable, and 1 if the variable is a namespace variable.
ArrayList	sidVec
Map	table If variable is in a hashtable, either the hash table entry that refers to this variable or null if the variable has been detached from its hash table (e.g.
ArrayList	traces List that holds the traces that were placed in this Var

Constructor Summary

Var()
NewVar -> Var Construct a variable and initialize its fields.

Method Summary

static void	AppendLocals(Interp interp, TclObject list, String pattern, boolean includeLinks)
static String	callTraces(Interp interp, Var array, Var var, String part1, String part2, int flags) CallTraces -> callTraces This procedure is invoked to find and invoke relevant trace procedures associated with a particular operation on a variable.
protected static void	cleanupVar(Var var, Var array) CleanupVar -> cleanupVar This procedure is called when it looks like it may be OK to free up the variable's record and hash table entry, and those of its containing parent.
void	clearVarInHashtable()
void	createArrayMap() Create a new array map in this Var
protected static void	deleteArray(Interp interp, String arrayName, Var var, int flags) DeleteArray -> deleteArray This procedure is called to free up everything in an array variable.
void	deleteArrayMap() Remove the existing array map in this var
protected static void	deleteSearches(Var arrayVar) DeleteSearches -> deleteSearches This procedure is called to free up all of the searches associated with an array variable.
protected static void	deleteVar(Interp interp, Var var, int flags) deleteVar This procedure is called to recycle all the storage space associated with a single Var instance.
static void	deleteVars(Interp interp, HashMap table) TclDeleteVars -> deleteVars This procedure is called to recycle all the storage space associated with a table of variables.
protected static void	deleteVars(Interp interp, Var[] compiledLocals) // FIXME: Make more like TclDeleteCompiledLocalVars() TclDeleteVars -> deleteVars This procedure is called to recycle all the storage space associated with an array of variables.
Map<String,Var>	getArrayMap()
int	getNextIndex() Used by ArrayCmd to create a unique searchId string.
Iterator	getSearch(String s) Find the SearchId that in the sidVec List that is equal the unique String s and returns the iterator associated with that SearchId.
static ArrayList	getTraces(Interp interp, String part1, String part2, int flags) Tcl_VarTraceInfo2 -> getTraces
TclObject	getValue()
static TclObject	getVar(Interp interp, String part1, String part2, int flags) Tcl_GetVar2Ex -> getVar Query the value of a variable, given a two-part name consisting of array name and element within array.
static TclObject	getVarCompiledLocalArray(Interp interp, String varname, String key, Var resolved, boolean leaveErrMsg)
static TclObject	getVarCompiledLocalArrayInvalid(Interp interp, String varname, String key)
static TclObject	getVarCompiledLocalScalarInvalid(Interp interp, String varname)
static String	getVariableFullName(Interp interp, Var var)
static TclObject	incrVar(Interp interp, String part1, String part2, long incrAmount, int flags) TclIncrVar2 -> incrVar Given a two-part variable name, which may refer either to a scalar variable or an element of an array, increment the Tcl object value of the variable by a specified amount.
static TclObject	initVarCompiledLocalArray(Interp interp, String varname, String key, TclObject newValue, Var[] compiledLocals, int localIndex)
static TclObject	initVarCompiledLocalScalar(Interp interp, String varname, TclObject newValue, Var[] compiledLocals, int localIndex)
static boolean	isArrayVarname(String varName)
boolean	isVarArray()
boolean	isVarArrayElement()
boolean	isVarInHashtable()
boolean	isVarLink()
boolean	isVarNamespace()
boolean	isVarNoCache()
boolean	isVarScalar()
boolean	isVarTraceExists()
boolean	isVarUndefined()
static Var[]	lookupVar(Interp interp, String part1, String part2, int flags, String msg, boolean createPart1, boolean createPart2) TclLookupVar -> lookupVar This procedure is used by virtually all of the variable code to locate a variable given its name(s).
static void	makeUpvar(Interp interp, CallFrame frame, String otherP1, String otherP2, int otherFlags, String myName, int myFlags, int localIndex) MakeUpvar -> makeUpvar Create a reference of a variable in otherFrame in the current CallFrame, given a two-part name consisting of array name and element within array.
boolean	removeSearch(String sid) Find the SearchId object in the sidVec list and remove it.
static Var	resolveArray(Var v)
static Var	resolveScalar(Var v)
void	setValue(TclObject tobj) Set the value of this Var (either as a scalar or as an array element)
static TclObject	setVar(Interp interp, String part1, String part2, TclObject newValue, int flags) Tcl_SetVar2Ex -> setVar Given a two-part variable name, which may refer either to a scalar variable or an element of an array, change the value of the variable to a new Tcl object value.
static TclObject	setVarCompiledLocalArray(Interp interp, String varname, String key, TclObject newValue, Var resolved)
static TclObject	setVarCompiledLocalArrayInvalid(Interp interp, String varname, String key, TclObject newValue)
static TclObject	setVarCompiledLocalScalarInvalid(Interp interp, String varname, TclObject newValue)
void	setVarNamespace()
String	toString() Used to create a String that describes this variable.
static void	traceVar(Interp interp, String part1, String part2, int flags, VarTrace proc) Tcl_TraceVar2 -> traceVar Trace a variable, given a two-part name consisting of array name and element within array.
static void	untraceVar(Interp interp, String part1, String part2, int flags, VarTrace proc) Tcl_UntraceVar2 -> untraceVar Untrace a variable, given a two-part name consisting of array name and element within array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

EXPLICIT_LOCAL_NAME

public static final int EXPLICIT_LOCAL_NAME

See Also:

Constant Field Values

traces

public ArrayList traces

List that holds the traces that were placed in this Var

sidVec

public ArrayList sidVec

table

public Map table

If variable is in a hashtable, either the hash table entry that refers to this variable or null if the variable has been detached from its hash table (e.g. an array is deleted, but some of its elements are still referred to in upvars). null if the variable is not in a hashtable. This is used to delete an variable from its hashtable if it is no longer needed.

hashKey

public String hashKey

The key under which this variable is stored in the hash table.

refCount

public int refCount

Counts number of active uses of this variable, not including its entry in the call frame or the hash table: 1 for each additional variable whose link points here, 1 for each nested trace active on variable, and 1 if the variable is a namespace variable. This record can't be deleted until refCount becomes 0.

ns

public Namespace ns

Reference to the namespace that contains this variable. This is set only for namespace variables. A local variable in a procedure will always have a null ns field.

Constructor Detail

Var

public Var()

NewVar -> Var Construct a variable and initialize its fields.

Method Detail

isVarScalar

public final boolean isVarScalar()

isVarLink

public final boolean isVarLink()

isVarArray

public final boolean isVarArray()

isVarUndefined

public final boolean isVarUndefined()

isVarArrayElement

public final boolean isVarArrayElement()

isVarNamespace

public final boolean isVarNamespace()

isVarInHashtable

public final boolean isVarInHashtable()

isVarTraceExists

public final boolean isVarTraceExists()

isVarNoCache

public final boolean isVarNoCache()

setVarNamespace

public final void setVarNamespace()

clearVarInHashtable

public final void clearVarInHashtable()

setValue

public void setValue(TclObject tobj)

Set the value of this Var (either as a scalar or as an array element)

Parameters:

tobj -

getValue

public TclObject getValue()

Returns:

the value of this Var (if it is a scalar or array element)

getArrayMap

public Map<String,Var> getArrayMap()

Returns:

the Map that contains the values if thiis is an array element

createArrayMap

public void createArrayMap()

Create a new array map in this Var

deleteArrayMap

public void deleteArrayMap()

Remove the existing array map in this var

toString

public String toString()

Used to create a String that describes this variable.

Overrides:

toString in class Object

getNextIndex

public int getNextIndex()

Used by ArrayCmd to create a unique searchId string. If the sidVec List is empty then simply return 1. Else return 1 plus the SearchId.index value of the last Object in the vector.

Returns:

The int value for unique SearchId string.

getSearch

public Iterator getSearch(String s)

Find the SearchId that in the sidVec List that is equal the unique String s and returns the iterator associated with that SearchId.

Parameters:

s - String that ia a unique identifier for a SearchId object

Returns:

Iterator if a match is found else null.

removeSearch

public boolean removeSearch(String sid)

Find the SearchId object in the sidVec list and remove it.

Parameters:

sid - String that ia a unique identifier for a SearchId object.

isArrayVarname

public static final boolean isArrayVarname(String varName)

lookupVar

public static Var[] lookupVar(Interp interp,
                              String part1,
                              String part2,
                              int flags,
                              String msg,
                              boolean createPart1,
                              boolean createPart2)
                       throws TclException

TclLookupVar -> lookupVar This procedure is used by virtually all of the variable code to locate a variable given its name(s).

Parameters:

part1 - if part2 isn't NULL, this is the name of an array. Otherwise, this is a full variable name that could include a parenthesized array element or a scalar.

part2 - Name of an element within array, or null.

flags - Only the TCL.GLOBAL_ONLY bit matters.

msg - Verb to use in error messages, e.g. "read" or "set".

createPart2 - OR'ed combination of CRT_PART1 and CRT_PART2. Tells which entries to create if they don't already exist.

Returns:

a two element array. a[0] is the variable indicated by part1 and part2, or null if the variable couldn't be found and throwException is false.

If the variable is found, a[1] is the array that contains the variable (or null if the variable is a scalar). If the variable can't be found and either createPart1 or createPart2 are true, a new as-yet-undefined (VAR_UNDEFINED) variable instance is created, entered into a hash table, and returned. Note: it's possible that var.value of the returned variable may be null (variable undefined), even if createPart1 or createPart2 are true (these only cause the hash table entry or array to be created). For example, the variable might be a global that has been unset but is still referenced by a procedure, or a variable that has been unset but it only being kept in existence by a trace.

Throws:

TclException - if the variable cannot be found and throwException is true.

getVar

public static TclObject getVar(Interp interp,
                               String part1,
                               String part2,
                               int flags)
                        throws TclException

Tcl_GetVar2Ex -> getVar Query the value of a variable, given a two-part name consisting of array name and element within array.

Parameters:

interp - the interp that holds the variable

part1 - 1st part of the variable name.

part2 - 2nd part of the variable name.

flags - misc flags that control the actions of this method.

Returns:

the value of the variable.

Throws:

TclException

setVar

public static TclObject setVar(Interp interp,
                               String part1,
                               String part2,
                               TclObject newValue,
                               int flags)
                        throws TclException

Tcl_SetVar2Ex -> setVar Given a two-part variable name, which may refer either to a scalar variable or an element of an array, change the value of the variable to a new Tcl object value. See the setVarPtr() method for the arguments to be passed to this method.

Throws:

TclException

initVarCompiledLocalScalar

public static TclObject initVarCompiledLocalScalar(Interp interp,
                                                   String varname,
                                                   TclObject newValue,
                                                   Var[] compiledLocals,
                                                   int localIndex)
                                            throws TclException

Throws:

TclException

setVarCompiledLocalScalarInvalid

public static TclObject setVarCompiledLocalScalarInvalid(Interp interp,
                                                         String varname,
                                                         TclObject newValue)
                                                  throws TclException

Throws:

TclException

getVarCompiledLocalScalarInvalid

public static TclObject getVarCompiledLocalScalarInvalid(Interp interp,
                                                         String varname)
                                                  throws TclException

Throws:

TclException

initVarCompiledLocalArray

public static TclObject initVarCompiledLocalArray(Interp interp,
                                                  String varname,
                                                  String key,
                                                  TclObject newValue,
                                                  Var[] compiledLocals,
                                                  int localIndex)
                                           throws TclException

Throws:

TclException

setVarCompiledLocalArrayInvalid

public static TclObject setVarCompiledLocalArrayInvalid(Interp interp,
                                                        String varname,
                                                        String key,
                                                        TclObject newValue)
                                                 throws TclException

Throws:

TclException

getVarCompiledLocalArrayInvalid

public static TclObject getVarCompiledLocalArrayInvalid(Interp interp,
                                                        String varname,
                                                        String key)
                                                 throws TclException

Throws:

TclException

getVarCompiledLocalArray

public static TclObject getVarCompiledLocalArray(Interp interp,
                                                 String varname,
                                                 String key,
                                                 Var resolved,
                                                 boolean leaveErrMsg)
                                          throws TclException

Throws:

TclException

setVarCompiledLocalArray

public static TclObject setVarCompiledLocalArray(Interp interp,
                                                 String varname,
                                                 String key,
                                                 TclObject newValue,
                                                 Var resolved)
                                          throws TclException

Throws:

TclException

incrVar

public static TclObject incrVar(Interp interp,
                                String part1,
                                String part2,
                                long incrAmount,
                                int flags)
                         throws TclException

TclIncrVar2 -> incrVar Given a two-part variable name, which may refer either to a scalar variable or an element of an array, increment the Tcl object value of the variable by a specified amount.

Parameters:

part1 - 1st part of the variable name.

part2 - 2nd part of the variable name.

incrAmount - Amount to be added to variable.

flags - misc flags that control the actions of this method Results: Returns a reference to the TclObject holding the new value of the variable. If the specified variable doesn't exist, or there is a clash in array usage, or an error occurs while executing variable traces, then a TclException will be raised. Side effects: The value of the given variable is incremented by the specified amount. If either the array or the entry didn't exist then a new variable is created. The ref count for the returned object is _not_ incremented to reflect the returned reference; if you want to keep a reference to the object you must increment its ref count yourself. ---------------------------------------------------------------- ------

Throws:

TclException

traceVar

public static void traceVar(Interp interp,
                            String part1,
                            String part2,
                            int flags,
                            VarTrace proc)
                     throws TclException

Tcl_TraceVar2 -> traceVar Trace a variable, given a two-part name consisting of array name and element within array.

Parameters:

part1 - 1st part of the variable name.

part2 - 2nd part of the variable name. null means part1 is a scalar or whole array.

flags - misc flags that control the actions of this method. OR-ed collection of bits, including any of TCL.TRACE_READS, TCL.TRACE_WRITES, TCL.TRACE_UNSETS, TCL.GLOBAL_ONLY, // and TCL.NAMESPACE_ONLY.

proc - the trace to comand to add.

Throws:

TclException

untraceVar

public static void untraceVar(Interp interp,
                              String part1,
                              String part2,
                              int flags,
                              VarTrace proc)

Tcl_UntraceVar2 -> untraceVar Untrace a variable, given a two-part name consisting of array name and element within array. This will Remove a previously-created trace for a variable.

Parameters:

interp - Interpreter containing variable.

part1 - 1st part of the variable name.

part2 - 2nd part of the variable name.

flags - misc flags that control the actions of this method.

proc - the trace to delete.

getTraces

public static ArrayList getTraces(Interp interp,
                                  String part1,
                                  String part2,
                                  int flags)
                           throws TclException

Tcl_VarTraceInfo2 -> getTraces

Parameters:

interp - Interpreter containing variable.

part1 - 1st part of the variable name.

part2 - 2nd part of the variable name (can be null).

flags - misc flags that control the actions of this method.

Returns:

the list of traces of a variable.

Throws:

TclException

makeUpvar

public static void makeUpvar(Interp interp,
                             CallFrame frame,
                             String otherP1,
                             String otherP2,
                             int otherFlags,
                             String myName,
                             int myFlags,
                             int localIndex)
                      throws TclException

MakeUpvar -> makeUpvar Create a reference of a variable in otherFrame in the current CallFrame, given a two-part name consisting of array name and element within array.

Parameters:

interp - Interp containing the variables

frame - CallFrame containing "other" variable. null means use global context.

otherP1 - the 1st part name of the variable in the "other" frame.

otherP2 - the 2nd part name of the variable in the "other" frame.

otherFlags - the flags for scaope of "other" variable

myName - Name of scalar variable which will refer to otherP1/otherP2.

myFlags - only the TCL.GLOBAL_ONLY bit matters, indicating the scope of myName.

Throws:

TclException - if the upvar cannot be created.

getVariableFullName

public static String getVariableFullName(Interp interp,
                                         Var var)

callTraces

public static String callTraces(Interp interp,
                                Var array,
                                Var var,
                                String part1,
                                String part2,
                                int flags)

CallTraces -> callTraces This procedure is invoked to find and invoke relevant trace procedures associated with a particular operation on a variable. This procedure invokes traces both on the variable and on its containing array (where relevant).

Parameters:

interp - Interpreter containing variable.

array - array variable that contains the variable, or null if the variable isn't an element of an array.

var - Variable whose traces are to be invoked.

part1 - the first part of a variable name.

part2 - the second part of a variable name.

flags - Flags to pass to trace procedures: indicates what's happening to variable, plus other stuff like TCL.GLOBAL_ONLY, TCL.NAMESPACE_ONLY, and TCL.INTERP_DESTROYED.

Returns:

null if no trace procedures were invoked, or if all the invoked trace procedures returned successfully. The return value is non-null if a trace procedure returned an error (in this case no more trace procedures were invoked after the error was returned). In this case the return value is a pointer to a string describing the error.

deleteSearches

protected static void deleteSearches(Var arrayVar)

DeleteSearches -> deleteSearches This procedure is called to free up all of the searches associated with an array variable.

Parameters:

arrayVar - the array variable to delete searches from.

deleteVars

public static void deleteVars(Interp interp,
                              HashMap table)

TclDeleteVars -> deleteVars This procedure is called to recycle all the storage space associated with a table of variables. For this procedure to work correctly, it must not be possible for any of the variables in the table to be accessed from Tcl commands (e.g. from trace procedures).

Parameters:

interp - Interpreter containing array.

table - HashMap that holds the Vars to delete

deleteVars

protected static void deleteVars(Interp interp,
                                 Var[] compiledLocals)

// FIXME: Make more like TclDeleteCompiledLocalVars() TclDeleteVars -> deleteVars This procedure is called to recycle all the storage space associated with an array of variables. For this procedure to work correctly, it must not be possible for any of the variables in the array to be accessed from Tcl commands (e.g. from trace procedures).

Parameters:

interp - Interpreter containing array.

compiledLocals - array of compiled local variables

deleteVar

protected static void deleteVar(Interp interp,
                                Var var,
                                int flags)

deleteVar This procedure is called to recycle all the storage space associated with a single Var instance.

Parameters:

interp - Interpreter containing array.

var - A Var refrence to be deleted

flags - flags to pass to trace callbacks.

deleteArray

protected static void deleteArray(Interp interp,
                                  String arrayName,
                                  Var var,
                                  int flags)

DeleteArray -> deleteArray This procedure is called to free up everything in an array variable. It's the caller's responsibility to make sure that the array is no longer accessible before this procedure is called.

Parameters:

interp - Interpreter containing array.

arrayName - name of array (used for trace callbacks).

var - the array variable to delete.

flags - Flags to pass to CallTraces.

cleanupVar

protected static void cleanupVar(Var var,
                                 Var array)

CleanupVar -> cleanupVar This procedure is called when it looks like it may be OK to free up the variable's record and hash table entry, and those of its containing parent. It's called, for example, when a trace on a variable deletes the variable.

Parameters:

var - variable that may be a candidate for being expunged.

array - Array that contains the variable, or NULL if this variable isn't an array element.

resolveScalar

public static Var resolveScalar(Var v)

resolveArray

public static Var resolveArray(Var v)

AppendLocals

public static void AppendLocals(Interp interp,
                                TclObject list,
                                String pattern,
                                boolean includeLinks)
                         throws TclException

Throws:

TclException