class ASTnode

ASTnode class (base class for all other kinds of nodes)

Public Classes

enum ASTtype
Whenever a new class derived from ASTnode is added to ast
ASTNODE
BLOCKNODE
DATABLOCKNODE
DATAFILENODE
DATAHEADINGNODE
DATAITEMNODE
DATALISTNODE
DATALOOPNAMELISTNODE
DATALOOPDEFLISTNODE
DEPRECIATED - Do not use:
DATALOOPNODE
DATALOOPVALLISTNODE
DATANAMENODE
DATANODE
DATAVALUENODE
GLOBALBLOCKNODE
GLOBALHEADINGNODE
HEADINGNODE
LOOPROWNODE
ITERNODE
DEPRECIATED - Do not use:
LOOPNAMELISTNODE
LOOPDEFLISTNODE
DEPRECIATED - Do not use:
LOOPTABLENODE
LOOPITER
DEPRECIATED - Do not use:
LOOPVALLISTNODE
DEPRECIATED - Do not use:
SAVEFRAMELISTNODE
SAVEFRAMENODE
SAVEHEADINGNODE
STARLISTNODE
STARFILENODE

Public Methods

ASTnode ( const ASTnode ©FromMe )
The copy constructor:
ASTnode ( void )
Sets the parent pointer to be null by default
virtual void copyFrom ( const ASTnode ©FromMe )
The routine that copies low-level values from one ASTnode to another - used by the copy constructor
virtual bool isOfType ( ASTtype T )
Call this function when you want to know whether or not a particular ASTnode object is of a certain type
virtual ASTnode* myParent (void)
Return the parent of this ASTnode
virtual ASTtype myType (void)
Return the type of this ASTnode
bool NotVirtualIsOfType ( ASTtype T )
This function should always be identical to isOfType except that it is not a virtual function
virtual bool removeChild ( ASTnode *child )
Removes the given ASTnode from this ASTnode, assuming that the given ASTnode is an immediate child of this ASTnode
virtual bool removeMe ( void )
Remove me from my parent ASTnode by calling my parent's removeChild() on me
virtual List <ASTnode*> * searchByTag ( char *searchFor)
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchByTag ( const string &searchFor)
Given a tag name, find the AST object it resides in
virtual List <ASTnode*> * searchForType ( ASTtype type, int delim = -1)
This method returns a list of all the nodes of the given type
virtual void setParent ( const ASTnode *p )
Set the parent of this node to a new value
virtual bool unlinkChild ( ASTnode *child )
unlinks the given ASTnode from this ASTnode, assuming that the given ASTnode is a child of this ASTnode
virtual bool unlinkMe ( void )
Remove me from my parent ASTnode, but do not delete me from the universe
virtual void Unparse (int indent)
Every subtype must provide an unparse operation that outputs the node to a global output stream called "os"
virtual ~ASTnode ( void )
The destructor:

Public


virtual int getLineNum ( void ) const
virtual void setLineNum ( const int num )

These functions return the line number and set the line number on which this node was found in the STAR file

const bool& getIsCache ( void )
void setIsCache ( bool isIt )

virtual List <ASTnode*> * searchForTypeByTag ( ASTtype type, const string &tag)
Overloaded Version
virtual List <ASTnode*> * searchForTypeByTag ( ASTtype type, char *tag)
Overloaded Version

This method is exactly the same as 'searchByTag()', except that it tries to return an object of the type given

virtual List <ASTnode*> * searchForTypeByTagValue ( ASTtype type, const string &tag, const string &value)
Overloaded Version
virtual List <ASTnode*> * searchForTypeByTagValue ( ASTtype type, const string &tag, char *value )
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchForTypeByTagValue ( ASTtype type, char *tag, const string &value)
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchForTypeByTagValue ( ASTtype type, char *tag, char *value )
Overloaded Version Just calls the above version of this function

This method is exactly like 'searchByTag()', except that it tries to return an object of the type given

virtual ASTnode* myParallelCopy ( void )
void setPeer ( const ASTnode *)

This method returns a pointer to an ASTnode

virtual List <ASTnode*> * searchByTagValue ( const string &tag, const string &value)
Given a tag name and a value, find the AST object that that particular tag and value pair resides in
virtual List <ASTnode*> * searchByTagValue ( const string &tag, char *value)
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchByTagValue ( char *tag, const string &value)
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchByTagValue ( char *tag, char *value)
Overloaded Version Just calls the above version of this function

virtual int getColNum ( void ) const
virtual void setColNum ( const int num )

These functions return the column number and set the column number on which this node was found in the STAR file

virtual const string& getPreComment ( void )
virtual void setPreComment ( const string &cmt )

These functions are used to some nodes in the AST tree the ability to remember a comment to be pasted into the file in front of that node

Documentation

ASTnode class (base class for all other kinds of nodes). -------------------------------------------------------- This class defines nothing but the Unparse function, which all AST types must have. When the root of the AST tree has its Unparse() function called, it will cause a percolation through all the Unparse() functions of all the nodes in the tree.
Unparse simply writes the tree out in star format to a file. The file is hardcoded to be the stream called (*os).
enum ASTtype
Whenever a new class derived from ASTnode is added to ast.h, it needs to have a name for it added to this enumerated type.

ASTNODE

BLOCKNODE

DATABLOCKNODE

DATAFILENODE

DATAHEADINGNODE

DATAITEMNODE

DATALISTNODE

DATALOOPNAMELISTNODE

DATALOOPDEFLISTNODE
DEPRECIATED - Do not use:

DATALOOPNODE

DATALOOPVALLISTNODE

DATANAMENODE

DATANODE

DATAVALUENODE

GLOBALBLOCKNODE

GLOBALHEADINGNODE

HEADINGNODE

LOOPROWNODE

ITERNODE
DEPRECIATED - Do not use:

LOOPNAMELISTNODE

LOOPDEFLISTNODE
DEPRECIATED - Do not use:

LOOPTABLENODE

LOOPITER
DEPRECIATED - Do not use:

LOOPVALLISTNODE
DEPRECIATED - Do not use:

SAVEFRAMELISTNODE

SAVEFRAMENODE

SAVEHEADINGNODE

STARLISTNODE

STARFILENODE

ASTnode( void )
Sets the parent pointer to be null by default

ASTnode( const ASTnode ©FromMe )
The copy constructor:

virtual void copyFrom( const ASTnode ©FromMe )
The routine that copies low-level values from one ASTnode to another - used by the copy constructor

virtual ~ASTnode( void )
The destructor:

virtual void Unparse(int indent)
Every subtype must provide an unparse operation that outputs the node to a global output stream called "os". The collection of all the unparses of all the nodes is used to print the star file. If you call the Unparse() of a particular level of nesting, it is supposed to in turn call the Unparse()'s of its children, and thus you can print the entire star file by calling the StarFileNode's Unparse(), or you can print out just one saveframe by calling the saveframe's Unparse(), or you can print out just one loop by calling the DataLoopNode's Unparse(), and so on.
Parameters:
indent - - the Indent level to start printing at. Zero means up agaisnt the left margin.

virtual ASTtype myType(void)
Return the type of this ASTnode. (this function is overridden for each type derived from ASTnode)

virtual ASTnode* myParent(void)
Return the parent of this ASTnode. In other words, return the ASTnode object in which this ASTnode is inserted. The exact type of this object can then be determined by calling its myType() function, at which point it can be casted to the proper type.

virtual void setParent( const ASTnode *p )
Set the parent of this node to a new value. Needed when you move this node into a new structure elsewhere.

virtual bool isOfType( ASTtype T )
Call this function when you want to know whether or not a particular ASTnode object is of a certain type

virtual List <ASTnode*> * searchByTag( const string &searchFor)
Given a tag name, find the AST object it resides in. It returns a list of pointers to the lowest level AST objects that the tag resides in.

This search is case-insensitive. The names of things, according to the STAR specification, are supposed to be case-insensitive. This is being applied not only to tag names but also to saveframe names and datablock names.

The caller of this function needs to use the isOfType() and/or myType() methods to determine what type to cst the object. Returns a NULL if nothing was found.

Parameters:
searchFor - - Look for this string as the tag name

virtual List <ASTnode*> * searchByTag( char *searchFor)
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.
Parameters:
searchFor - - Look for this string as the tag name.

virtual List <ASTnode*> * searchByTagValue( const string &tag, const string &value)
Given a tag name and a value, find the AST object that that particular tag and value pair resides in. This is like performing an SQL search: WHERE tag = value.

Only searches starting at the node it was called from, and its children. Recurses downward, but does not recurse upward. This function is only capable of returning one answer, so it cannot be called at the same levels where searchByTag() can be called (see above).

This search is case-insensitive. The names of things, according to the STAR specification, are supposed to be case-insensitive. This is being applied not only to tag names but also to saveframe names and datablock names.

(However, the values are case-sensitive. A search for a tag of _t1 is identical to a search for a tag of _T1, but a search for a value of "V1" is different from a search for a value of "v1".)

WARNING: The list returned is allocated in heap space. It is the caller's responsibility to delete the list after it is no longer needed.

Parameters:
tag - - Look for this tag...
value - - Where it has this value.

virtual List <ASTnode*> * searchByTagValue( const string &tag, char *value)
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.

WARNING: The list returned is allocated in heap space. It is the caller's responsibility to delete the list after it is no longer needed.

virtual List <ASTnode*> * searchByTagValue( char *tag, const string &value)
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.

virtual List <ASTnode*> * searchByTagValue( char *tag, char *value)
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.

virtual List <ASTnode*> * searchForType( ASTtype type, int delim = -1)
This method returns a list of all the nodes of the given type. It is much like searchByTag() in that it heirarchically walks the STAR tree and calls the searchForType() functions of the subtrees within the tree. In this way it is possible to call this function at any level of the STAR file.

The second parameter is optional and is only useful when you are searching for DATAVALUENODEs. It determines the kind of DATAVALUENODE you are searching for, by delimiter type. For example, you could search for only those DATAVALUENODEs that are semicolon-delimited by passing DataValueNode::SEMICOLON as the second argument. Or you could look for just framecodes by passing DataValueNode::FRAMECODE as the second parameter. Passing a negative number says you want all the DataValueNodes, regardless of their delimiter type.

Although the second parameter is an integer, think of it as the enum DataValueNode::ValType. The only reason it is shown as an integer in the prototype here is that this class (ASTnode) needs to be defined before the class "DataValueNode" can be defined, and thus at this point the compiler has no clue what "DataValueNode::ValType" means yet.

If the search is for some ASTtype other than DATAVALUENODE, then it is irrelevant what the second parameter of this function is, as it will never be used - You can just leave it off and accept the default.

Parameters:
type - - type to search for
delim - - DataValueNode::ValType to look for. Default = "dont-care".

virtual List <ASTnode*> * searchForTypeByTag( ASTtype type, const string &tag)
Overloaded Version

virtual List <ASTnode*> * searchForTypeByTag( ASTtype type, char *tag)
Overloaded Version

This method is exactly the same as 'searchByTag()', except that it tries to return an object of the type given. What it does is this: it calls searchByTag(), then it 'walks' up the parent list until it finds an ASTnode-derived object that is of the type given. Thus if you search for a ASTnode::SAVEFRAMENODE type of object with this function, it will return the save frame in which the match was found, rather than the match itself. Also note that this method will consider derived subtypes of a class as valid 'hits' as well. For example, you could search for an ASTnode::DATANODE and if a DATAITEMNODE or DATALOOPNODE or SAVEFRAMENODE were found, they would be returned as valid hits. If an empty list is returned, that could be either because no matching tags were found OR because there were matches found, but they were not inside any objects of the requested type.

This search is case-insensitive. The names of things, according to the STAR specification, are supposed to be case-insensitive. This is being applied not only to tag names but also to saveframe names and datablock names.

(However, the values are case-sensitive. A search for a tag of _t1 is identical to a search for a tag of _T1, but a search for a value of "V1" is different from a search for a value of "v1".)

YOU NEVER NEED TO OVERRIDE THESE FUNCTIONS IN ANY OF THE SUBCLASSES OF ASTNODE! THEY OPERATE THE SAME WAY IN ALL THE SUBCLASSES. THEY MAKE ALL THEIR CALLS THROUGH THE EXISTING searchByTag() calls.

Parameters:
type - - the type to search for.
tab - - the tag (name) to search for.

virtual List <ASTnode*> * searchForTypeByTagValue( ASTtype type, const string &tag, const string &value)
Overloaded Version

virtual List <ASTnode*> * searchForTypeByTagValue( ASTtype type, const string &tag, char *value )
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.

WARNING: The list returned is allocated in heap space. It is the caller's responsibility to delete the list after it is no longer needed.

virtual List <ASTnode*> * searchForTypeByTagValue( ASTtype type, char *tag, const string &value)
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.

virtual List <ASTnode*> * searchForTypeByTagValue( ASTtype type, char *tag, char *value )
Overloaded Version Just calls the above version of this function. There is no need to override this function in subclasses of ASTnode.

This method is exactly like 'searchByTag()', except that it tries to return an object of the type given. Other than the fact that it calls searchByTagValue() instead of searchByTag(), it behaves exactly as searchForTypeByTag() (see above).

YOU NEVER NEED TO OVERRIDE THESE FUNCTIONS IN ANY OF THE SUBCLASSES OF ASTNODE! THEY OPERATE THE SAME WAY IN ALL THE SUBCLASSES. THEY MAKE ALL THEIR CALLS THROUGH THE EXISTING searchByTag() calls.

Parameters:
type - - type to search for
tag - - tag name to search for
value - - where it has this value

virtual bool removeChild( ASTnode *child )
Removes the given ASTnode from this ASTnode, assuming that the given ASTnode is an immediate child of this ASTnode. (Does not recurse down to grandchildren). If the given ASTnode is not a child of this ASTnode, then nothing happens and no error is reported. Also calls the destructor of the child node. This function does NOT need to be overridden for subclasses of ASTnode. The default ASTnode removeChild() will call unlinkChild(), and if that is successful, it will delete the child pointer. This should be correct behaviour most of the time for any subclass of ASTnode, assuming that the subclass has defined its unlinkChild() properly.
Returns:
true if the child was removed. false if the given ASTnode was not even in this class anywhere, and therefore nothing was done.

virtual bool unlinkChild( ASTnode *child )
unlinks the given ASTnode from this ASTnode, assuming that the given ASTnode is a child of this ASTnode. Does NOT call the destructor of the child node!! Use this function to remove the child from this ASTnode but not free its space.

This function MUST be overridden for each subclass of ASTnode.

Returns:
true if the child was unlinked. false if the given ASTnode was not even in this class anywhere, and therefore nothing was done.

virtual bool removeMe( void )
Remove me from my parent ASTnode by calling my parent's removeChild() on me. Deletes me as well, so I can't be used after this call anymore. I am gone. This function does NOT need to be overridden for each ASTnode derivative. It is very generic.
Returns:
true if this ASTnode was successfully removed. false if this ASTnode was not removed, usually this is not fatal - it is just that this node's parent has disowned this node and has no idea what it is. This usually happens when this ASTnode is a copy of another ASTnode such that it's parent pointer points at the same place as the original ASTnode's parent pointer.

virtual bool unlinkMe( void )
Remove me from my parent ASTnode, but do not delete me from the universe. I still exist after this call. This function does NOT need to be overridden for each ASTnode derivative. It is very generic. #@return true if this ASTnode was successfully removed. false if this ASTnode was not removed, usually this is not fatal - it is just that this node's parent has disowned this node and has no idea what it is. This usually happens when this ASTnode is a copy of another ASTnode such that it's parent pointer points at the same place as the original ASTnode's parent pointer.

virtual ASTnode* myParallelCopy( void )

void setPeer( const ASTnode *)

This method returns a pointer to an ASTnode. The ASTnode returned is the parallel 'other' version of this node in the parallel tree. Incedentally, since the two parallel trees are aware of each other, the parallel copy of the parallel copy is the orginial node, so this function is self-inverting, like this: foo->myParallelCopy()->myParallelCopy() == foo If there is no parallel node corresponding to this node, then this method will return a NULL pointer. This can happen if a node in the parallel tree was deleted after the parallel copy was made.

bool NotVirtualIsOfType( ASTtype T )
This function should always be identical to isOfType except that it is not a virtual function. This means that you can call it by casting the ASTnode class to the specific type you want, and you will get a call that does not nessacerliy go down to the deepest level of descendency, like a virtual function would.

virtual int getLineNum( void ) const

virtual void setLineNum( const int num )

These functions return the line number and set the line number on which this node was found in the STAR file. Note that a negative number is an indicator that the node was not in the original file when it was parsed, and hence has no line number.

These functions start counting at 1, not zero.

These functions actually give the location where the particular part of speech ENDED, not where it started. For example, with a DataLoopNode, the location given is the location of the closing "stop_" keyword, not the opening "loop_" keyword. This is an unfortunate neccessity due to the way the parser reads the data. It doesn't know whether or not it has encountered a complete grammatical construct until it reaches the end of the construct, at which point it has lost track of what the location was at the start of the grammatical construct.

virtual int getColNum( void ) const

virtual void setColNum( const int num )

These functions return the column number and set the column number on which this node was found in the STAR file. Note that a negative number is an indicator that the node was not in the original file when it was parsed, and hence has no column number.

These functions start counting at 1, not zero.

These functions actually give the location where the particular part of speech ENDED, not where it started. For example, with a DataLoopNode, the location given is the location of the closing "stop_" keyword, not the opening "loop_" keyword. This is an unfortunate neccessity due to the way the parser reads the data. It doesn't know whether or not it has encountered a complete grammatical construct until it reaches the end of the construct, at which point it has lost track of what the location was at the start of the grammatical construct.

virtual const string& getPreComment( void )

virtual void setPreComment( const string &cmt )

These functions are used to some nodes in the AST tree the ability to remember a comment to be pasted into the file in front of that node.

In the interest of saving memory, these functions are not implemented at all levels of the tree, although for orthogonality they exist in the generic ASTnode parent class, for most classes calling them will have no effect, or will always return an empty string.

const bool& getIsCache( void )

void setIsCache( bool isIt )


This class has no child classes.

alphabetic index hierarchy of classes


Starlib is a creation of BioMagResBank: bmrb.wisc.edu starlib banner

generated by doc++