class ASTnode

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

Inheritance:


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 ( string &searchFor)
Given a tag name, find the AST object it resides in
virtual List <ASTnode*> * searchByTag ( char *searchFor)
Overloaded Version Just calls the above version of this function
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 ( ASTnode *p )
Set the parent of this node to a new value
virtual size_t sizeOfMe (void)
Returns the size in bytes of this node and all nodes under it
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 ASTnode* myParallelCopy ( void )
void setPeer ( ASTnode *)

This method returns a pointer to an ASTnode

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

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

virtual List <ASTnode*> * searchForTypeByTag ( ASTtype type, 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, string &tag, string &value)
Overloaded Version
virtual List <ASTnode*> * searchForTypeByTagValue ( ASTtype type, string &tag, char *value )
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchForTypeByTagValue ( ASTtype type, char *tag, 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 List <ASTnode*> * searchByTagValue ( string &tag, 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 ( string &tag, char *value)
Overloaded Version Just calls the above version of this function
virtual List <ASTnode*> * searchByTagValue ( char *tag, 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

int getLineNum ( void )
void setLineNum ( int num )

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

int getColNum ( void )
void setColNum ( int num )

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

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( 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( 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( string &tag, 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( 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, 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, 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, string &tag, string &value)
Overloaded Version

virtual List <ASTnode*> * searchForTypeByTagValue( ASTtype type, 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, 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( 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.

int getLineNum( void )

void setLineNum( 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.

int getColNum( void )

void setColNum( 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.

const string& getPreComment( void )

void setPreComment( const string &cmt )

These functions are used to give each node in the AST tree the ability to remember a comment to be pasted into the file in front of that node. This is useful if you want to insert header comments of some sort into the output produced by Unparse(). As of this writing, no provisions are being made to handle the parsing of comments from the original file and storing them via these functions. The grammar to do that would be rather convoluted. These functions are only intended to be used by programs insterting their own comments after the file has been read.

The string must contain the comment characters embedded inside, like so: "# this is a\n# multiline comment.", not like this: "this is a\nmultiline comment." This is so that the caller is allowed to have the comment contain blank lines like this:

# This is an example comment.

# The comment has some blank

# lines in it.
If the Unparse() function were designed to insert the comment characters (#) itself, then such a comment block would be impossible to create.

Note that the comment lines are not syntax-checked in any way, so using these functions it is entirely possible to create invalid STAR files, since these "comments" can really be strings with anything at all in them - so be careful.

To get rid of the preComment if you change your mind, set it to a zero-length string with setPreComment().

virtual size_t sizeOfMe(void)
Returns the size in bytes of this node and all nodes under it. this is mostly a debugging routine for internal use at BMRB, but there is no harm in making it public, so it was made public. (calling the sizeOfMe() of the StarFileNode will calculate the memory usage of the whole tree, calling the sizeOfMe() of a DataLoopNode calculates the memory usage of that DataLoopNode, and so on.)

Each subtype of ASTnode must implement its own sizeOfMe() that exhibits the following behaviour:
   The returned size is:

  • the size of the node itself
    plus
  • the size of all the things pointed to or referenced by the node. For each thing pointed to or referenced,
    • If it is a normal C type, use sizeof().
    • If it is another ASTnode, call its sizeOfMe() method. As long as each ASTnode subtype does this, it will recursively walk the whole subtree.


Direct child classes:
StarListNode
StarFileNode
StarFileNode
SaveFrameListNode
LoopTableNode
LoopRowNode
LoopNameListNode
HeadingNode
DataValueNode
DataNode
DataNameNode
DataLoopNameListNode
DataListNode
BlockNode

alphabetic index hierarchy of classes


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

generated by doc++