com.sun.electric.database.variable
Class VarContext

java.lang.Object
  extended by com.sun.electric.database.variable.VarContext
All Implemented Interfaces:
java.io.Serializable

public class VarContext
extends java.lang.Object
implements java.io.Serializable

VarContext represents a hierarchical path of NodeInsts. Its primary use is to determine the value of variables which contain Java code. In particular, the syntax @foo expands to P("foo") which looks for the variable called foo in the NodeInst of this VarContext.

A VarContext can also be used to recover the names of instances along a hierarchical path. LE.getdrive() is an example of a method that does this.

The VarContext object that represents the base top level is VarContext.globalContext. You can get a new VarContext with an extra NodeInst context attached by calling push(NodeInst) on the parent context. You can get a VarContext with the most recent NodeInst removed by calling pop(). Note that individual VarContexts are immutable: you get new ones by calling push and pop; push and pop do not edit their own VarContexts.

Retrieve a Variable by calling getVar(String name) on any ElectricObject.

If the one knows that the Variable contains an object that does not need to be evaluated, that object can be retrieved using Variable.getObject().

On the other hand, if the object may need to be evaluated because it is type Java, TCL, or Lisp, then such evaluation may be hierarchy dependent and one must call context.evalVar(variable).

Extra variables defined in the interpreter:

Extra functions defined in the interpreter:
P(name) -- get the value of variable name on the most recent NodeInst. Defaults to Integer(0).

Methods PD(), PAR(), and PARD() are either gone or deprecated (RKao). Here are what they used to do:
PD(name, default) -- get the value of variable name on the most recent NodeInst. Defaults to default.
PAR(name) -- get the value of variable name on any NodeInst, starting with the most recent. Defaults to Integer(0).
PARD(name, default) -- get the value of variable name on any NodeInst, starting with the most recent. Defaults to default.

This class is thread-safe.

See Also:
Serialized Form

Nested Class Summary
static class VarContext.EvalException
           
 
Field Summary
static VarContext globalContext
          The blank VarContext that is the parent of all VarContext chains.
 
Method Summary
 void deleteVariableCache()
          Get rid of the variable cache thereby release its storage
 boolean equals(java.lang.Object o)
          Does deep comparison of two VarContexts.
 java.lang.Object evalSpice(Variable var, boolean recurse)
          Evaluate a spice variable
 java.lang.Object evalVar(Variable var)
          Gets the value of Variable @param var.
 java.lang.Object evalVar(Variable var, java.lang.Object info)
          Same as evalVar, except an additional object 'info' is passed to the evaluator.
 java.lang.Object evalVarRecurse(Variable var, java.lang.Object info)
          This is the recursive version of evalVar that may throw an EvalException.
 java.lang.String getInstPath(java.lang.String sep)
          Return the concatonation of all instances names left to right from the root to the leaf.
 Nodable getNodable()
          Return the Node Instance that provides the context for the variable evaluation for this level.
 int getNumLevels()
          Get the number of levels of context in this VarContext
 java.util.Iterator<Nodable> getPathIterator()
          Get an iterator over the Nodables that describe this context.
 PortInst getPortInst()
          Return the PortInst that resides on the NodeInst that provides the context.
protected  java.lang.Object lookupVarEval(java.lang.String name)
          Lookup Variable one level up the hierarchy and evaluate.
static double objectToDouble(java.lang.Object obj, double def)
          Helper method to convert an Object to a double, if possible.
static float objectToFloat(java.lang.Object obj, float def)
          Helper method to convert an Object to a float, if possible.
static int objectToInt(java.lang.Object obj, int def)
          Helper method to convert an Object to an integer, if possible.
static short objectToShort(java.lang.Object obj, short def)
          Helper method to convert an Object to a short, if possible.
 VarContext pop()
          get the VarContext that existed before you called push on it.
static void printException(VarContext.EvalException e, Variable var, VarContext context, java.lang.Object info)
           
 VarContext push(Nodable ni)
          get a new VarContext that consists of the current VarContext with the given NodeInst pushed onto the stack
 VarContext pushCaching(Nodable ni)
          Push a new level onto the VarContext stack.
 VarContext removeParentContext(int levels)
          Remove N levels of parent context from this VarContext.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

globalContext

public static final VarContext globalContext
The blank VarContext that is the parent of all VarContext chains.

Method Detail

push

public VarContext push(Nodable ni)
get a new VarContext that consists of the current VarContext with the given NodeInst pushed onto the stack


pushCaching

public VarContext pushCaching(Nodable ni)
Push a new level onto the VarContext stack. If the value of any of ni's parameters is requested and if the computation of that value requires a call to the bean shell then the value is saved in this VarContext so that future requests don't result in additional calls to the bean shell. Note that this is implementing Call-By-Value semantics whereas the non-caching VarContext implements Call-By-Name.

Be warned that there is no mechanism to automatically flush the caches when the design is modified. The design MUST NOT change over the life time of this VarContext. If the design might change then you should use the non-caching VarContext.


pop

public VarContext pop()
get the VarContext that existed before you called push on it. may return globalContext if the stack is empty.


getNodable

public Nodable getNodable()
Return the Node Instance that provides the context for the variable evaluation for this level.


getPortInst

public PortInst getPortInst()
Return the PortInst that resides on the NodeInst that provides the context. This is currently only useful for Highlighting.


equals

public boolean equals(java.lang.Object o)
Does deep comparison of two VarContexts. Matches hierarchy traversal. Returns true if they both represent the same hierarchy traversal, false otherwise. (Recursive method). Does not compare PortInsts.

Overrides:
equals in class java.lang.Object
Parameters:
o - the VarContext to compare against.
Returns:
true if equal, false otherwise.

getPathIterator

public java.util.Iterator<Nodable> getPathIterator()
Get an iterator over the Nodables that describe this context. This iterator starts from the top of the hierarchy, and goes down.

Returns:
an iterator over the context path

removeParentContext

public VarContext removeParentContext(int levels)
Remove N levels of parent context from this VarContext. Returns a new VarContext. This will return VarContext.globalContext if the 'levels' is greater than or equal to the number of levels in this context.

Parameters:
levels - the number of levels of parent context to remove
Returns:
a new VarContext

getNumLevels

public int getNumLevels()
Get the number of levels of context in this VarContext

Returns:
the number of levels of context in this VarContext

deleteVariableCache

public void deleteVariableCache()
Get rid of the variable cache thereby release its storage


evalVar

public java.lang.Object evalVar(Variable var)
Gets the value of Variable @param var. If variable is Java, uses EvalJavaBsh to evaluate If variable is TCL, uses ... to evaluate If variable is Lisp, uses ... to evaluate otherwise, just returns the Variable's object

Returns:
the evlauated Object. Returns null if the variable is code and evaluation fails.

evalVar

public java.lang.Object evalVar(Variable var,
                                java.lang.Object info)
Same as evalVar, except an additional object 'info' is passed to the evaluator. 'info' may be or contain additional information necessary for proper evaluation. Usually info is the NodeInst on which the var exists.

Returns:
the evlauated Object. Returns null if the variable is code and evaluation fails.

printException

public static void printException(VarContext.EvalException e,
                                  Variable var,
                                  VarContext context,
                                  java.lang.Object info)

evalVarRecurse

public java.lang.Object evalVarRecurse(Variable var,
                                       java.lang.Object info)
                                throws VarContext.EvalException
This is the recursive version of evalVar that may throw an EvalException. The message of the EvalException states the reason that evaluation failed. This is made public so code elsewhere that is meant to be used in Attribute's java code can call this method. This is useful such that the first EvalException encountered is thrown all the way to the top of the eval caller, rather than getting caught and handled somewhere inbetween.

Parameters:
var - the variable to evaluate
info - an info object that may be needed by the evaluator
Returns:
the variable's object if not code, otherwise an evaluated result object if evaluation succeeds
Throws:
VarContext.EvalException - an exception whose message contains the reason evaluation failed

evalSpice

public java.lang.Object evalSpice(Variable var,
                                  boolean recurse)
Evaluate a spice variable

Parameters:
var - the variable to evaluate
recurse - false to not recursively evaluate (only if param call is SPICE code).
Returns:
the evaluated string, or null on eval error

lookupVarEval

protected java.lang.Object lookupVarEval(java.lang.String name)
                                  throws VarContext.EvalException
Lookup Variable one level up the hierarchy and evaluate. Looks for the var on the most recent NodeInst on the hierarchy stack. If not found, look for the default Variable of the same name on the NodeProto.

Parameters:
name - the name of the variable
Returns:
an object representing the evaluated variable, or null if no var or default var found.
Throws:
VarContext.EvalException

getInstPath

public java.lang.String getInstPath(java.lang.String sep)
Return the concatonation of all instances names left to right from the root to the leaf. Begin with the string with a separator and place a separator between adjacent instance names.

Parameters:
sep - the separator string.

objectToFloat

public static float objectToFloat(java.lang.Object obj,
                                  float def)
Helper method to convert an Object to a float, if possible. if not possible, return @param def.


objectToInt

public static int objectToInt(java.lang.Object obj,
                              int def)
Helper method to convert an Object to an integer, if possible. if not possible, return @param def.


objectToShort

public static short objectToShort(java.lang.Object obj,
                                  short def)
Helper method to convert an Object to a short, if possible. if not possible, return @param def.


objectToDouble

public static double objectToDouble(java.lang.Object obj,
                                    double def)
Helper method to convert an Object to a double, if possible. if not possible, return @param def.