Deriving Your Own Namespace

A namespace refers to a set of rules for creating and interpreting legal names within an application. The OpenAccess database supports a number of commonly used namespaces, including VHDL, Verilog, CDBA, LEF, DEF, SPEF, SPF, UNIX, and Windows, as well as the oaNative OpenAccess namespace (the internal format for oaName objects).

Deriving a namespace to integrate your proprietary language with the OpenAccess database and other tools simplifies exporting your data to other systems.

This section includes the following topics:

Deriving from oaNameSpace
Implementation Flow: From Your Namespace to oaNative
Implementation Flow: From oaNative to Your Namespace
Functions for Converting to the oaNative Namespace
Functions for Converting from the oaNative Namespace

Deriving from oaNameSpace

Name spaces are derived from the abstract base class oaNameSpace. The oaNameSpace class defines the minimum amount of information you need to provide to the OpenAccess database in order to implement a namespace. Defining the required minimum input and output allows the OpenAccess database to interpret your data even though the database did not write the code.

When deriving a namespace, you must determine how to translate the names from the original language to the oaNative format, and vice versa. Because namespaces always know that any name they receive from the OpenAccess database is in the oaNative format, the namespaces really need to know only how to translate from oaNative to their language, and from their language to oaNative. Once that is implemented, names can then be translated into the correct format for any other derived namespace.

When creating a namespace, be sure to document what the namespace supports, what special characters are used, what keywords are required, any sequencing issues, and if there are any restrictions on characters used to begin or end the name.

Supported Name Objects

The oaName object is used in conjunction with oaNameSpace to perform name mapping. oaName has the capability to represent scalar names, vectorBit names, vector names, and bundle names. The minimum name object you must support when creating a namespace is scalar names, which includes the minimal set of library names and cell names. Generally, about half of all names are scalar names, and slightly less than half are vector or vectorBit names.

Name Mapping

Names are memory intensive as well as algorithmically intensive. When implementing a derived namespace, you must use a one-to-one name mapping algorithm. For example:

A legal name in the oaNative namespace must map to a legal name in your derived namespace, and vice versa.
In addition, every pair of names that are the same in the oaNative namespace map to the same names in your namespace, and vice versa.
Finally, all mappings must be reversible, with the exception of possible loss of case if the original name space is case-insensitive.

Additional information can be found in The Name Mapping Algorithm within the Name Mapping section of this Programmers Guide.

For specific examples of different name types, refer to the Examples of Name Mapping table within the Name Mapping section. These examples can help you understand fundamentally how your names map to oaNative and how oaNative maps to your names.

It is also helpful to study the namespaces that are already defined as OpenAccess classes for suggestions on implementing your own namespace. For example:

The Windows namespace (oaWinNS) is an example of a case-insensitive namespace that supports keywords and only supports scalar names.

The Native namespace (oaNativeNS) is an example of a case-sensitive namespace that supports all types of names, including hierarchical, scalar, vectorBit, vector, stepped, and bundle names.

The VHDL and Verilog namespaces (oaVhdlNS and oaVerilogNS) are examples of namespaces that support keywords and more than one name type.

Implementation Flow: From Your Namespace to oaNative

When implementing your derived namespace, mapping it to the oaNative format typically includes the following processes.

If your namespace supports more than one name type, each name string should be checked to determine what kind of name it is (using the oaNameSpace::getType() function).

If your namespace uses keywords, each name should be checked to determine if it is a keyword. If the name is a keyword, your namespace should throw an error.

Each character should be checked to determine if it is valid in the oaNative namespace. Validity is based on the oaNative language rules. Each valid character is written to a buffer, and then the next character is checked. A character that is a normal character in your original namespace but is a special character oaNative should be hex encoded.

For additional information on special characters, refer to Handling Illegal Characters in the Name Mapping section of this Programmers Guide.

Bus characters in your original namespace should be replaced with the oaNative bus character.

Case sensitivity is considered in both the your namespace and in the oaNative namespace throughout the flow.

For information on how case sensitivity is handled, see Understanding Case Sensitivity in the Name Mapping section of this Programmers Guide.

SampleNamespace Implementation: oaWinNs to oaNative

Implementation Flow: From oaNative to Your Namespace

Mapping from the oaNative namespace to your derived namespace typically includes the following processes.

If your namespace uses keywords, each name string should be checked to determine if it is a keyword. If the name is a keyword in your namespace, it must be escaped by adding the escape delimiter to the name string.

Each character should be checked to determine if it is a valid character in your namespace. Validity is based on the rules of your language. Each valid character is written to a buffer, and then the next character is checked. A character that is a normal character in oaNative but is a special character in your namespace should be hex encoded.

For additional information on special characters, refer to Handling Illegal Characters in the Name Mapping section of this Programmers Guide.

If your namespace supports bus characters, the oaNative bus characters should be replaced by the bus character for your namespace.

Case sensitivity is considered in both the oaNative namespace and your namespace throughout the flow.

For information on how case sensitivity is handled, see Understanding Case Sensitivity in the Name Mapping section of this Programmers Guide.

Sample NamespaceImplementation: oaNative to oaWinNS

Functions for Converting to the oaNative Namespace

When converting from a derived namespace to the oaNative namespace, you must implement the following virtual functions from the abstract base class oaNameSpace. In addition to these functions, you must also implement the isEqual functions.


void            getInternalMember(const oaChar  *in,		
                                  oaString      &out,		
                                  oaBoolean     &caseSensitive, 
                                  oaUInt4       len,		
                                  oaUInt4       flags = 0)	
				  const = 0;

This function returns the input string, including the case sensitivity setting, mapped into the oaNative namespace. The specified number of characters of the input string are evaluated; the default is to evaluate the entire string. The data is returned in the string out. Flags has no valid values other than zero.


void            getInternalScalar(const oaChar  *in, 
                                  oaScalarName  &out)
				  const = 0;

This function returns the input string mapped into the oaNative namespace. The data is returned in the string out.

Functions for Converting from the oaNative Namespace

When converting from the oaNative namespace to your derived namespace, youmust implement the following virtual functions from the abstract base classoaNameSpace. In addition to these functions, you must also implement the isEqual functions.


void            get(const oaByte    *data,
                    oaString        &out, 
                    oaUInt4         &loc) 
		    const = 0;

This function returns the input block data mapped into this namespace. The data is returned in the string out, beginning at the location loc.

The format for the data byte array is as follows:

The first unsigned integer returns the flags.

The upper half of the integer indicates the type of name this represents. (The mask oavNameTypeMask can be used to get the name type).

If the name is a Simple Name:	For all simple names, the first unsigned integer indicates the name type in the upper half and the number of members in the lower half.
	For vector names, the next three unsigned integers indicate the start, stop, and step values, respectively.
	For vectorBit names, the next unsigned integer indicates the bit value.
	For all simple names, for each of the members, read the array as follows: readStr() gives the const char* representing the name member. The next unsigned integer gives the case sensitivity of the member.

If the name is a Bundle Name:	The next unsigned integer indicates the number of members in the name.
	For each of the members, read the array as follows: The next unsigned integer is the repeat value for the member. Read the next set of data as you would a simple name.

The oaCdbaNS namespace is an example of a namespace that represents all of the different kinds of names. Since the code for reading the byte array doesn't change from namespace to namespace, studying this namespace can give you a better understanding of how to read the data byte array.

The readUInt4() and readStr() methods in oaNameSpace are available to make it easy to process the array.


oaNameType      getType(const oaChar    *in) 
			const = 0;

This function returns the type of name represented by the specified string in this namespace: scalar, vector bit, vector, or bundle. This function does not indicate if the name is valid.


void            getMember(const oaChar  *in,		
                          oaBoolean     caseSensitive,  
                          oaString      &out,		
                          oaUInt4       &loc,		
                          oaUInt4       flags = 0) 	
			  const = 0;

This function returns the input name member, with the specified case sensitivity value, mapped into this namespace. It is assumed that the input name is in the oaNative namespace format. The data is returned in the string out, at the location loc. Flags has no valid values other than zero.


void            getScalarName(const oaScalarName    &in,	
                              oaString              &out,	
                              oaUInt4               &loc) 	
		  	      const = 0;

This function returns the input scalar name mapped into this namespace. It is assumed the input name is in the oaNative namespace format. The data is returned in the string out, at the location loc.

isEqual Functions

The following functions return a boolean value that indicates if two specified names match. Matching also includes case sensitivity for each member. You must implement all of the isEqual functions in your derived namespace. In general, if a name type is not supported in your namespace, the equivalent functions should throw the appropriate exception (for example, if vector names are not supported, throw the exception oacVectorNameInvalid).


oaBoolean       isEqual(const oaNameMem &n1, 	
                        const oaNameMem &n2) 	
			const = 0;

This function returns a boolean value that indicates if the two specified name members are equal in this namespace.


oaBoolean       isEqual(const oaScalarName  &n1,
                        const oaScalarName  &n2)
			const = 0;

This function returns a boolean value that indicates if the two specified scalar names are equal in this namespace.


oaBoolean       isEqual(const oaVectorName  &n1,
                        const oaVectorName  &n2)
			const = 0;

This function returns a boolean value that indicates if the two specified vector names are equal in this namespace.


oaBoolean       isEqual(const oaVectorBitName   &n1,
                        const oaVectorBitName   &n2)
			const = 0;

This function returns a boolean value that indicates if the two specified vector bit names are equal in this namespace.


oaBoolean       isEqual(const oaBundleName  &n1,
                        const oaBundleName  &n2)
			const = 0;

This function returns a boolean value that indicates if the two specified bundle names are equal in this namespace.


oaBoolean       isEqual(const oaSimpleName  &n1,
                        const oaSimpleName  &n2)
			const = 0;

This function returns a boolean value that indicates if the two specified simple names are equal in this namespace.


oaBoolean       isEqual(const oaName    &n1,    
                        const oaName    &n2)    
			const = 0;

This function returns a boolean value that indicates if the two specified names are equal in this namespace.

Return to top of page

Return to Programmers Guide topics