oaLibDefList Class Reference

Inheritance diagram for oaLibDefList:

oaSessionObject oaObject


Public Methods

void open ()
void save ()
void saveAs (const oaString &path)
void getPath (oaString &path) const
void getFullPath (oaString &path) const
oaChar getMode () const
void destroy ()
oaCollection< oaLibDefListMem, oaLibDefList > getMembers () const

Static Public Methods

void openLibs ()
void openLibs (const oaString &path)
oaLibDefList * getTopList ()
void getDefaultPath (oaString &path)
void getDefaultFileName (oaString &libDefName)
oaLibDefList * create (const oaString &filePath)
oaLibDefList * get (const oaString &filePath, oaChar mode)
oaLibDefList * find (const oaString &filePath)
oaCollection< oaLibDefList, oaLibDefList > getLibDefLists ()

Detailed Description

The oaLibDefList class contains functions that let an application use and manage a library definition file or a hierarchy of library definition files.

The oaLibDefList class provides functions for:

An oaLibDefList object is associated with one library definition files. For each session, there is a top-level oaLibDef object, and possibly one or more lower-level library definition objects that are referenced by an oaLibDefListRef member in the list. In the library definition file representation this hierarchy is represented by the INCLUDE statement in the library definition files.

By default, the top-level library definition file name and path are defined by the LibDef plug-in and can be obtained by the ILibDef::getDefaultFileName and ILibDef::getDefaultPath respectively. A specific file name can be specified to the oaLibDefList.

It is important for any application using oaLibDefList::open() or oaLibDefList::get() to declare an observer derived from oaObserver<oaLibDefList> so that it will be notified of ILibDef::open() errors through the oaLibDefList observer's onLoadWarnings function. Failures related to library definition file can be very hard to diagnose without the use of this observer. For a simple code example of the use of an oaLibDefList observer, see oaLibDefList Observer Example.

An oaLibDefList object contains an ordered collection of oaLibDefListMem objects This includes two types of objects derived from the oaLibDefListMem:

In effect, library definition files can be nested by including a reference to another list as a list member. Multiple levels of references result in a hierarchy of oaLibDefLists.

The order of the oaLibDefListMem objects in an oaLibDefList is meaningful, and it is used by oaLibDefList::openLibs to resolve conflicts among library definitions included in an oaLibDefList hierarchy.

To add new members to an oaLibDefList object, use oaLibDef::create() or oaLibDefListRef::create(). To remove members, use oaLibDefListMem::destroy().

Sample Usage

For a sample user routine that gets and iterates through all the oaLibDefListMems in an oaLibDefList, see oaLibDefList::getMembers.

For a sample routine that appends a new library definition to the library definition file associated with the session's oaLibDefList, see oaLibDefList::getTopList.

Member Function Documentation

oaLibDefList * oaLibDefList::create (  const oaString &    filePath )  [static]
 

This function creates an new library definition file at the specified full path (including the filename).

void oaLibDefList::destroy (    ) 
 

This function destroys this oaLibDefList object. No files are deleted from disk.

oaLibDefList * oaLibDefList::find (  const oaString &    filePath )  [static]
 

This function finds the oaLibDefList object associated with the specified filePath. A NULL pointer is returned if the list is not found.

Parameters:
filePath The complete relative or absolute path to the file associated with this oaLibDefList. Relative paths are relative to the current working directory.

oaLibDefList * oaLibDefList::get (  const oaString &    filePath,
oaChar    mode
)  [static]
 

This function finds, or creates, the library definition list associated with an oaLibDefList object according to the specified filePath and mode. This function returns a pointer to the oaLibDefList, which can be a new oaLibDefList parsed from the library definition file or pre-existing one.

If an existing list is not found, this function constructs a new list of the library definitions (oaLibDefs) and library definition file references (oaLibDefListRefs) found in the specified library definition file only. It does not traverse the library definition list hierarchy and add library definitions contained in other referenced files to the list. For a sample user routine that gets and iterates through all the oaLibDefListMems listed in and referenced by an oaLibDefList object, see oaLibDefList::getMembers.

The filePath specifies a library definition file to be associated with the returned list object. The library definition list will be read in from the file in 'r'ead-only or 'a'ppend mode, or an empty list will be created in 'w'rite mode. The list can later be saved to the file (with an oaLibDefList::save) only if the preceding get() specified the 'a'ppend' or 'w'rite mode.

Note:
To change the mode of an existing oaLibDefList object, call get() with the libDefList's filePath and the new mode.
Parameters:
filePath The complete absolute or relative path to the file associated with this oaLibDefList. A relative path is relative to the current working directory.
mode The mode in which the oaLibDefList is accessed, which is one of the following:
  • 'r': read-only mode - The list is constructed by reading in the contents of the specified file. An exception is thrown if that file cannot be found or read.

  • 'a': append mode - The list is constructed by reading in the contents of the specified file. The list can be subsequently saved. An exception is thrown if the file exists and is not writable or if the file exists and is a symbolic link.

  • 'w': write mode - An empty list is constructed and returned. If the file at the specified path exists, it is truncated during a subsequent save() call (an exception is thrown if that file exists but is not writable). If the file does not exist, it is created when this list is saved.

Example

Suppose the library definition listed in the file specified by filePath has already been constructed through a previous oaLibDefList::openLibs(filePath) call. Then, calling oaLibDefList::get(filePath, 'r') or oaLibDefList::get(filePath, 'a') will only affect the mode of the existing list, while oaLibDefList::get(filePath, 'w') also will truncate the list.

Exceptions:
oacLibDefListFileNotReadable 
oacLibDefListFileNotWritable 
oacUndefinedLibDefListMode 
oacLibDefFileCannotAppendSymbolicLink 

void oaLibDefList::getDefaultFileName (  oaString &    libDefName )  [static]
 

This function returns the default name for a library definition file when none is specified. For example the native OpenAccess library definition file name is "libs.def".

Parameters:
libDefName The returned default file name.

void oaLibDefList::getDefaultPath (  oaString &    filePath )  [static]
 

This function returns the path for the default library definition file. This path is defined by the LibDef plug-in.

Parameters:
filePath Complete path, including filename, to the found default library definition file. The complete path can be an absolute path or a relative path.

void oaLibDefList::getFullPath (  oaString &    fullPath )  const
 

This function returns the full path to the file associated with this oaLibDefList object.

Parameters:
fullPath Returned full absolute path, including filename, of the lib.defs file associated with this oaLibDefList object.

oaCollection< oaLibDefList, oaLibDefList > oaLibDefList::getLibDefLists (    )  [static]
 

This function returns a collection of all the oaLibDefList objects in this session.

oaCollection< oaLibDefListMem, oaLibDefList > oaLibDefList::getMembers (    )  const
 

This function returns a collection of the oaLibDefList members in this library definition file. Note that the oaLibDefList members are ordered, which means the order of the oaLibDefListMem objects returned from the iterator is meaningful and persistent.

Below is a sample recursive routine that gets and iterates through all the oaLibDefListMems in an oaLibDefList passed to the routine. The purpose of the routine is to process all the library definitions found in the user's library definition file hierarchy at and below the level of the oaLibDefList passed to the routine. 

walkLibDefList(oaLibDefList *list)
{
   oaType memType;
   oaScalarName libName;
   oaString tempString;
   oaIter<oaLibDefListMem> listIter(list->getMembers());
   while (oaLibDefListMem *listMem = listIter.getNext()) 
   { 
       switch (memType = listMem->getType()) {
         case oacLibDefType :
           ((oaLibDef *)(listMem))->getLibName(libName);
           libName.get(tempString);
           cout << "Got Lib Def: Logical Library Name = "<< tempString << endl; 
           //process lib def ...           
           break;

         case oacLibDefListRefType :
           ((oaLibDefListRef *)(listMem))->getRefListPath(tempString);
           oaLibDefList *nextList = oaLibDefList::get(tempString,'r');
           walkLibDefList(nextList);
           break;

       }
   }
}

oaChar oaLibDefList::getMode (    )  const
 

This function returns the mode of this oaLibDefList object, which can be one of 'r'ead, 'a'ppend, or 'w'rite (see oaLibDefList::get() for a description of each mode).

void oaLibDefList::getPath (  oaString &    filePath )  const
 

This function returns the path to the file associated with this oaLibDefList object.

Parameters:
filePath Returned complete path, including filename, of the library definition file associated with this oaLibDefList object. The complete path can be an absolute path or a relative path.

oaLibDefList * oaLibDefList::getTopList (    )  [static]
 

This function gets the current top oaLibDefList for this session. The current top oaLibDefList for this session is established by the top-level oaLibDefList used in the most recent successful oaLibDefList::openLibs() call. If the openLibs() function has not been called in this session, or if the last call of this function failed this function returns NULL.

Below is a sample routine that gets the top list for an oaLibDefList, changes its mode to append, creates a new library definition (which adds the new library definition to the end of the oaLibDefList object), then saves the updated list to the file on disk associated with the list. 

 
oaLibDefList::openLibs("myLibDefFile")

oaString     libraryPath("./DesignLib"); 
oaString     library("DesignLib");
oaScalarName libraryName(oaNs,library);

oaLibDefList *list = oaLibDefList::getTopList();

if (list) {
    oaString    topListPath;    
    list->getPath(topListPath);
    list->get(topListPath,'a');
    oaLibDef *newLibDef = oaLibDef::create(list,libraryName,libraryPath);
    list->save();
}

void oaLibDefList::open (    ) 
 

This function opens all the libraries in this library definition file. If a library with the same name as one in the list but with a different definition is already open, the opened library is closed and the new definition is used to open a new library.

This function issues onPreOpenLibs and onPostOpenLibs observer notifications.

Failure to open specific libraries in the list results in onLoadWarnings notifications. However, such failure to open a particular library does not abort the operation.

Exceptions:
oacLibDefFileRecursiveInclude 

void oaLibDefList::openLibs (  const oaString &    filePath )  [static]
 

This function loads the library definition file specified by filePath. If a relative path is specified, it should be relative to the current working directory. If the file is not found or cannot be read, an oacLibDefListFileNotReadable error is thrown.

If the library definition is found, this function reads the library definitions listed in the file and any definitions listed in other library definition files included in the file and creates new oaLibDefList and oaLibDefListMem objects. If reading the library definition file was successful, the function then sets the topList and opens all the libraries based on the listed definitions. If a library with the same name as one in the list but with a different definition is already open, the open library is closed and the new definition is used to open the library.

No libraries are opened if the plug-in ILibDef::open() function reports an error in reading and parsing the library definition file(s). In this case, oaObserver<oaLibDefList>::onLoadWarnings() are triggered by the plug-in to notify the application of the errors encountered while reading the file. Note: It is important for any application using openLibs() to declare an observer derived from oaObserver<oaLibDefList> so that it can receive notification of errors through the oaLibDefList observer's onLoadWarnings function. Library-related failures can be very hard to diagnose without the use of this observer. For a simple code example of the use of an oaLibDefList observer, see oaLibDefList Observer Example.

Parameters:
filePath An absolute or relative path, including the file name. A relative path is relative to the current working directory.
Exceptions:
oacLibDefListFileNotReadable oacPlugInInterfaceException

void oaLibDefList::openLibs (    )  [static]
 

This function searches for a default library definition file in the default library definition path as defined by the LibDef plug-in. If the file is not found or cannot be read, an oacLibDefListFileNotReadable error is thrown.

If the library definition is found, this function reads the library definitions listed in the file and any definitions listed in other library definition files included in the file and creates new oaLibDefList and oaLibDefListMem objects. If reading the library definition file was successful, the function then sets the topList and opens all the libraries based on the listed definitions. If a library with the same name as one in the list but with a different definition is already open, the open library is closed and the new definition is used to open the library.

No libraries are opened if the plug-in ILibDef::open() function reports an error in reading and parsing the library definition file(s). In this case, oaObserver<oaLibDefList>::onLoadWarnings() are triggered by the plug-in to notify the the application of the errors encountered while reading the file.

Note: It is important for any application using openLibs() to declare an observer derived from oaObserver<oaLibDefList> so that it can receive notification of errors through the oaLibDefList observer's onLoadWarnings function. Library-related failures can be very hard to diagnose without the use of this observer. For a simple code example of the use of an oaLibDefList observer, see oaLibDefList Observer Example.

void oaLibDefList::save (    ) 
 

This function saves this oaLibDefList object to the file associated with it. Note that this oaLibDefList object must be in a 'w'rite or 'a'ppend mode.

This function issues onPreSave and onPostSave notifications to oaLibDefList observers.

Exceptions:
oacSaveReadOnlyLibDefList 
oacLibDefListFileNotWritable 
oacLibDefListDirNotWritable 

void oaLibDefList::saveAs (  const oaString &    filePath ) 
 

This function saves this oaLibDefList object to the file specified by the path. Note that this oaLibDefList object must be in a 'w'rite or 'a'ppend mode.

This function issues onPreSaveAs and onPostSaveAs notifications to oaLibDefList observers.

Parameters:
filePath Input parameter - absolute or relative path, including filename. A relative path should be specified relative to the current working directory.
Exceptions:
oacLibDefListFileNotWritable 
oacLibDefListDirNotWritable 

The documentation for this class was generated from the following files:

Return to top of page




Copyright © 2002 - 2010 Cadence Design Systems, Inc.
All Rights Reserved.