byucc.jhdl.base
Class Nameable

java.lang.Object
  byucc.jhdl.base.Nameable

Direct Known Subclasses:

Node, Wire

public abstract class Nameable

extends java.lang.Object

Class for providing name capability for Wires and Nodes in the JHDL circuit graph. Methods provided by this class support the generation of default names which are guaranteed to be unique, or assignment of user-specified names, which are checked to be unique and which are modified to be unique if a name clash is detected at runtime. Objects with names must have parents. If there is no parent, the object becomes orphan (without name). The orphan capability can be disabled in the derived class if desired. Note that the parent must provide the following methods at a minimum: int generateLocalInstanceNo() which must provide a new integer that is guaranteed not to be used in the current context, and Node getParent() which gets a parent. Also note that Nodes must be Nameable so that hierarchical names can be generated.

Nameable also controls whether JHDL is case sensitive or not. By default, JHDL is case sensitive, allowing a larger namespace; but there are times when it is useful to turn case sensitivity off (as when parsing EDIF).

Author:

Brad L. Hutchings

Method Summary

static boolean	caseSensitivity() Returns the current value of JHDL case sensitivity.
static boolean	caseSensitivity(boolean flag) Sets the current value of JHDL case sensitivity.
static void	disableNameClashChecking() Deprecated. JHDL now uniquifies names automatically, so this is unneeded.
java.lang.String	getFullName() The full name that globally identifies this node.
java.lang.String	getFullNameNoTestBench() The full name that globally identifies this node.
java.lang.String	getHierNameNoTestBench() getHierName recursively traverses the circuit hierarchy building the hierarchical name without the testbench name.
int	getInstanceNo() Deprecated. use getInstanceNumber()
int	getInstanceNumber() Returns the uniquifying instance number of this object
java.lang.String	getLeafName() Returns the leaf name of the Node or Wire.
java.lang.String	getLeafName(boolean lower_case) Returns the leaf name of the Node or Wire.
java.lang.String	getRelativeName(Node ancestor) The relative name uniquely identifies this nameable with respect to an ancestor node.
java.lang.String	getUserName() Returns the user name, or a default name if the user did not provide one, with no uniquification (see hasUserSpecifiedName()).
java.lang.String	getUserName(boolean lower_case) Returns the user name, or a default name if the user did not provide one, with no uniquification (see hasUserSpecifiedName()).
boolean	hasUserSpecifiedName() Used to determine if the user-specified the name for this Node.
boolean	isDescendantOf(Node ancestor) Convenience method that returns whether this is a descendant of the indicated node.
void	setInstanceNumber(int number) Sets the uniquifying instance number of this object.

Methods inherited from class java.lang.Object

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

Method Detail

disableNameClashChecking

public static void disableNameClashChecking()

Deprecated. JHDL now uniquifies names automatically, so this is unneeded.

Turn clash checking off for the next named instance. Following the creation of a new item, clash checking is turned back on.

caseSensitivity

public static boolean caseSensitivity()

Returns the current value of JHDL case sensitivity. Defaults to true.

Returns:

true if JHDL is case sensitive (FOO, Foo, and foo are not the same items), false if JHDL is case insensitive (FOO, Foo, and foo are the same).

caseSensitivity

public static boolean caseSensitivity(boolean flag)

Sets the current value of JHDL case sensitivity.

Parameters:

flag - the new value of JHDL case sensitivity.

Returns:

the prior value.

getUserName

public final java.lang.String getUserName()

Returns the user name, or a default name if the user did not provide one, with no uniquification (see hasUserSpecifiedName()). This is not to be used to get the actual leaf name. Use getLeafName() for that purpose.

Returns:

the user name slot (will never be null).

getUserName

public final java.lang.String getUserName(boolean lower_case)

Returns the user name, or a default name if the user did not provide one, with no uniquification (see hasUserSpecifiedName()). This version can preserve or change the user's case.

Parameters:

lower_case - true to return the name as a lower case.

Returns:

the user name slot (will never be null).

getLeafName

public java.lang.String getLeafName()

Returns the leaf name of the Node or Wire. Leaf names can be user-specified at construction time, or automatically generated. Automatic names consist of the class name, a delimiter, and an instance number. User-specified names, if unique, are left exactly as specified. If a user-specified name is not unique, a delimiter and a relative instance number are appended. All of this is determined when the cell is constructed.

Returns:

the local, or leaf-level name of the object.

getLeafName

public final java.lang.String getLeafName(boolean lower_case)

Returns the leaf name of the Node or Wire. Leaf names can be user-specified at construction time, or automatically generated. Automatic names consist of the class name, a delimiter, and an instance number. User-specified names, if unique, are left exactly as specified. If a user-specified name is not unique, a delimiter and a relative instance number are appended. All of this is determined when the cell is constructed. This version can preserve or change the user's case.

Parameters:

lower_case - true to return the name as a lower case.

Returns:

the local, or leaf-level name of the object.

getHierNameNoTestBench

public java.lang.String getHierNameNoTestBench()

getHierName recursively traverses the circuit hierarchy building the hierarchical name without the testbench name.

Returns:

the full hierarchical name.

getFullName

public java.lang.String getFullName()

The full name that globally identifies this node. Includes the hierarchical prefix, the leaf name and the instance number.

Returns:

the fully qualified name of this item.

getFullNameNoTestBench

public java.lang.String getFullNameNoTestBench()

The full name that globally identifies this node. Includes the hierarchical prefix, the leaf name and the instance number. This name does not include the testbench name if it is at the root. This is handy for netlisting purposes.

Returns:

the fully qualified name of this item, without the testbench.

getRelativeName

public java.lang.String getRelativeName(Node ancestor)

The relative name uniquely identifies this nameable with respect to an ancestor node. For example, the relative name of tb_foo/foo-0/bar-1/and2 to the node tb_foo/foo-0 is "bar-1/and2". If this object is the given target, "" is returned, and if this object is not a descendent, null is returned.

Parameters:

ancestor - the target ancestor for the relative name

Returns:

the hierarchical name of this item, starting after the ancestor, or null if this is not a descendent

hasUserSpecifiedName

public boolean hasUserSpecifiedName()

Used to determine if the user-specified the name for this Node.

Returns:

true if the name for this node was either full or partially specified. Partially specified means that the user-specified the name but that it was not unique and and had to have an instance number added to it to make it unique.

isDescendantOf

public boolean isDescendantOf(Node ancestor)

Convenience method that returns whether this is a descendant of the indicated node.

Parameters:

ancestor - the node we want to check against.

Returns:

true if this item's parent or higher ancestor is the given node

getInstanceNo

public final int getInstanceNo()

Deprecated. use getInstanceNumber()

Returns the uniquifying instance number of this object

Returns:

this object's instance number

getInstanceNumber

public final int getInstanceNumber()

Returns the uniquifying instance number of this object

Returns:

this object's instance number

setInstanceNumber

public final void setInstanceNumber(int number)

Sets the uniquifying instance number of this object. This should only be used in rare circumstances. One example is when deleting a cell and replacing it with a slightly modified version; this method can then be called after the original version is gone to give the new version the same identifying number as before.

Parameters:

number - the new instance number

Throws:

BuildException - if the new instance number cannot be used because it would cause a clash