PCLParseTreeNode -- Object Serialization Parse Tree

The PCLParseTreeNode class is the base class of a family of classes used to represent different data items that form a hierarchical tree of named and typed data items. Such parse trees are typically used to hold an inmemory format of objects being serialized, or de-serialized.

The PCL parse tree classes include methods for conveniently reading parse tree's from a text file, and writing them to a parse tree. They are used by the JOLTObject/JOLTRegistry classes as a standard means of serializing and deserializing objects. The use of the PCL parse tree was pioneered by the Visual Modeller, and the text file format is currently used to hold all module definitions for the modeller, and to hold the persistant format of models.

The PCLParseTreeNode class itself is pure virtual. It serves only as a base class for the various particular types of nodes. The PCLParseTreeNode is derived from PCLObject.

See the JOLT topics for further information on how to utilize PCLParseTreeNodes for a standard approach to object serialization.

GetName()

const char *GetName();

The GetName() method returns a pointer to an internal string containing the name of the node.

SetName()

void SetName( pszNewName );

const char * pszNewName;
           The new name to apply to the node.

Update the name of a node.

GetAsString()

char *GetAsString() const;

The GetAsString() method will return the value contents of a node in a string representation. The returned string becomes the responsibility of the caller and should be freed with HFree().

PTNSubTree

The PTNSubTree class is a special parse tree node which has no intrinsic value itself, but just acts as a container for zero or more children PCLParseTreeNode's. The PTNSubTree class also has a number of helper methods related to reading a parse tree from a file, or writing one to a file.

The PTNSubTree class is derived from PCLParseTreeNode. Destroying a PTNSubTree will also destroy all its children.

PTNSubTree()

PTNSubTree::PTNSubTree( pszName );

const char * pszName;
               The name for the new node.

This constructor will create a new PTNSubTree node with no children.

GetChildren()

PCLArray *GetChildren();

The GetChildren() returns a pointer to an internal PCLArray container containing all the children nodes of this node. This container should not be directly modified. All the children in PCLArray will be objects of classes derived from PCLParseTreeNode.

AddChild()

void   AddChild( poNode );

PCLParseTreeNode *poChild;
               The new child to add to this target PTNSubTree.

GetChild()

PCLParseTreeNode *GetChild( pszName, pszClass );

const char *pszName;
               The name of the requested child node.

const char *pszClass;
               The class of the desired child node.  May be omitted for any
               class.  The class would match the return result of
               GetClassName(), for instance "PTNString".

The GetChild() method will search the immediate children of the current node for a child matching the passed criteria. If one is found it will be returned, otherwise NULL is returned.

Example:

    if ( poTree->GetChild( "XSize" ) && poTree->GetChild( "YSize" ) )
        poGeoref->SetXYSize( poTree->GetChildAsInteger( "XSize" ),
                             poTree->GetChildAsInteger( "YSize" ) );

GetChildAsString()

const char *GetChildAsString( pszName );

const char *pszName;
               Name of desired child node.

This method will fetch the value string from a PTNString child node named pszName. It is illegal to request a child which doesn't exists, or which is of the incorrect type. A check for existance can be done with the GetChild() method. The returned string should not be modified or freed.

GetChildAsInteger()

int GetChildAsInteger( pszName );

const char *pszName;
               Name of desired child node.

This method will fetch the value from a PTNInteger child node named pszName. It is illegal to request a child which doesn't exists, or which is of the incorrect type. A check for existance can be done with the GetChild() method.

GetChildAsDouble()

double GetChildAsDouble( pszName );

const char *pszName;
               Name of desired child node.

BuildFromFile()

void   BuildFromFile( fp );

FILE   *fp;
           An open text file to be read.

This method will read an entire text file, and add all the first level nodes defined in the file as children of the current (root) node.

Example:

The following code reads a model file, and builds a PCLParseTreeNode tree with the precreated poPTNRoot object as the root.

    FILE        *fp;
    PTNSubTreeNode *poPTNRoot = HNew PTNSubTree( "Root" );
    
    fp = DKOpen( pszFilename, FL_TXT, "r" );
    poPTNRoot->BuildFromFile( fp );
    DKClose( fp );

WriteToFile()

void   WriteToFile( fp );

FILE   *fp;
           An open text file to be written to.

This method will write an entire PCLParseTree to a text file in a human readable hierarchical format.

Example:

The following code serializes the contents of a model into a PCL parse tree, and then writes this to a text file. The parse tree is then destroyed.

    fp = DKOpen( pszFilename, FL_TXT, "w" );
    poSubTree = (PTNSubTree *) poModel->SerializeTree();
    
    poSubTree->WriteToFile( fp );
    HDelete poSubTree;
    
    DKClose( fp );

PTNString

The PTNString class holds a parse tree entry with a string value. The PTNStringList class is derived from PCLParseTreeNode.

PTNString()

PTNString::PTNString( pszName, pszValue );

const char     *pszName;
                   The name to be assigned to this node.

const char     *pszValue;
                   The string value to be assigned to this node.

This method creates a new PTNString node, and assigns an initial value.

GetValue()

const char *GetValue();

The GetValue() method returns a pointer to the internal string representation for this node. The returned value is never NULL, and should never be modified.

SetAsString()

void SetAsString( pszNewValue );

const char *pszNewValue;
               The new value to assign to this node.

PTNStringList

The PTNStringList class holds a parse tree entry with a list of strings as a value. This is a StringList in the sense managed by the StringList functions. The PTNStringList class is derived from PCLParseTreeNode.

PTNStringList()

PTNStringList::PTNStringList( pszName, papszValue );

const char *pszName;
               The name to be assigned to this node.

char   **papszValue;
               The string list value to be assigned to this node.  A copy
               of the passed string list is made.

This method creates a new PTNStringList node, and assigns an initial value.

GetValue()

char   **GetValue() const;

The GetValue() method returns a pointer to the internal string list representation for this node. The returned value is never NULL, and should never be modified.

PTNInteger

The PTNInteger class holds a parse tree entry with a string value. The PTNInteger class is derived from PCLParseTreeNode.

PTNInteger()

PTNInteger::PTNInteger( pszName, nValue );

const char     *pszName;
                   The name to be assigned to this node.

int            nValue;
                   The integer value to be assigned to the node.

This method creates a new PTNInteger node, and assigns an initial value.

GetValue()

int    GetValue();

The GetValue() method returns a integer which is the value of this PTNInteger node.

SetValue()

void SetValue( nNewValue );

int    nNewValue;
           The new value to assign to this node.

SetAsString()

void SetAsString( pszNewValue );

const char *pszNewValue;
           The new value to assign to this node.  It will be converted from
           string to integer with atoi().

PTNDouble

The PTNDouble class holds a parse tree entry with a string value. The PTNDouble class is derived from PCLParseTreeNode.

PTNDouble()

PTNDouble::PTNDouble( pszName, dfValue );

const char     *pszName;
                   The name to be assigned to this node.

double         dfValue;
                   The floating point value to be assigned to the node.

This method creates a new PTNDouble node, and assigns an initial value.

GetValue()

double GetValue();

The GetValue() method returns a the value of this PTNDouble node.

SetValue()

void SetValue( dfNewValue );

double dfNewValue;
           The new value to assign to this node.

SetAsString()

void SetAsString( pszNewValue );

const char *pszNewValue;
           The new value to assign to this node.  It will be converted from
           string to integer with atof().

PTNBool

The PTNBool class holds a parse tree entry with a TBool value. The PTNBool class is derived from PCLParseTreeNode.

PTNTBool()

PTNBool::PTNBool( pszName, bValue );

const char     *pszName;
                   The name to be assigned to this node.

TBool          bValue;
                   The value to be assigned to the node.

This method creates a new PTNBool node, and assigns an initial value.

GetValue()

TBool  GetValue();

The GetValue() method returns a the value of this node. node.

SetValue()

void SetValue( bNewValue );

TBool  bNewValue;
           The new value to assign to this node.

SetAsString()

void SetAsString( pszNewValue );

const char *pszNewValue;
           The new value to assign to this node.

The value "TRUE" will be converted to the contant TRUE, and all other values are converted to FALSE.

About PCI Help Gateway