EDU.bmrb.starlibj
Class StarNode

java.lang.Object
  |
  +--EDU.bmrb.starlibj.StarNode
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
BlockNode, DataItemNode, DataLoopNameListNode, DataLoopNode, DataNameNode, DataValueNode, LoopNameListNode, LoopRowNode, LoopTableNode, SaveFrameNode, StarFileNode

public class StarNode
extends java.lang.Object
implements java.lang.Cloneable

StarNode is the generic class on which every other node in the STAR file tree is based. All nodes in the STAR tree are derived from StarNode. Some of the functionality is described in StarNode so that it can be guaranteed to always be there even when the type of StarNode is unknown. (You can searchByTag on any StarNode, whether you cast it to a specific type or not.)


Field Summary
protected  int colNum
           
protected  int lineNum
           
protected  StarNode parent
           
protected  java.lang.String preComment
           
 
Constructor Summary
StarNode()
          Default Constructor.
StarNode(StarNode copyMe)
          Copy Constructor - deep copy.
 
Method Summary
 java.lang.Object clone()
          Allocates a new copy (clone) of this StarNode and returns a reference to it.
 int getColNum()
          Get the column number that this node was on in the original file.
 int getLineNum()
          Get the line number that this node was on in the original file.
 StarNode getParallelCopy()
          get parallelCopy is not really implemented yet.
 StarNode getParent()
          Return the parent of this StarNode.
 java.lang.String getPreComment()
          This 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.
 VectorCheckType searchByName(java.lang.String searchFor)
          searchByName() will generate a list of all the places a particular name exists in this AST object.
 VectorCheckType searchByTagValue(java.lang.String tag, java.lang.String value)
          Given a tag name and a value, find the AST object that that particular tag and value pair resides in.
 VectorCheckType searchForType(java.lang.Class type, short delim)
          This method returns a vector of all the nodes of the given type.
 VectorCheckType searchForTypeByName(java.lang.Class type, java.lang.String name)
          Find all the occurrances where there is a node of the given type containing something with the given name.
 VectorCheckType searchForTypeByTagValue(java.lang.Class type, java.lang.String tag, java.lang.String value)
          This is much like searchForTypeByTagValue() above, except that it looks for places where the given tag/value matches, and it contains the given value, then it looks to find a node of the given type that the match is inside of.
 void setColNum(int num)
          setColNum sets the column number from the text file for this node.
 void setLineNum(int num)
          setLineNum sets the line number from the text file for this node.
protected  void setParent(StarNode p)
           
 void setPeer(StarNode peer)
          setPeer is not really implemented yet.
 void setPreComment(java.lang.String cmt)
           
 void Unparse(int indent)
          Unparse prints the contents of the StarNode object out to the given stream.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

parent

protected StarNode parent

lineNum

protected int lineNum

colNum

protected int colNum

preComment

protected java.lang.String preComment
Constructor Detail

StarNode

public StarNode()
Default Constructor.

StarNode

public StarNode(StarNode copyMe)
Copy Constructor - deep copy. This simply copies the node given, deeply down to the leaf nodes.
Method Detail

Unparse

public void Unparse(int indent)
Unparse prints the contents of the StarNode object out to the given stream. This is essentially the inverse of the CS term to "parse", hence the name "Unparse". The parameter given is the indentation level to print things.

getParent

public StarNode getParent()
Return the parent of this StarNode. In other words, return the StarNode object in which this StarNode is inserted.

searchByName

public VectorCheckType searchByName(java.lang.String searchFor)
searchByName() will generate a list of all the places a particular name exists in this AST object. This name will match tag names or saveframe names or data block names. Note that the full string name must be passed, so to look for a tag called foo, you need to use the underscore in the name: "_foo". Also, to look for a saveframe called foo, you need the save_ prefix, like this: "save_foo". This search is an exact string match, and it is case-sensitive.

This search is fully recursive. All the parts of the star tree that exist below this point will also be searched. Therefore if you call a StarFileNode's searchByName(), you search the whole star file, while if you call a SaveFrameNode's searchByName() you search just that saveframe.

It should be noted that this algorithm, and the other search algorithms that follow, are simple linear searches with no indexing. So they are computationally slow. So far the need has not yet surfaced for a faster indexed search technique, although one could be added behind the scenes without changing the interface.

The search for names is case-insensitive.

Parameters:
searchFor - the string name to look for.
Returns:
A VectorCheckType containing the StarNodes that matched. This vector will have a size of zero if there are no matches.

searchByTagValue

public VectorCheckType searchByTagValue(java.lang.String tag,
                                        java.lang.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).

The search for tag names is case-insensitive.

The search for values, however is case-sensitive.

Parameters:
tag - - Look for this tag...
value - - Where it has this value.
Returns:
A java.util.vector containing the matching StarNodes. This vector will have a size of zero if there are no matches.

searchForType

public VectorCheckType searchForType(java.lang.Class type,
                                     short delim)
This method returns a vector of all the nodes of the given type. It is much like searchByName() 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.

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".
Returns:
A java.util.vector containing the matching StarNodes. This vector will have a size of zero if there are no matches.

searchForTypeByName

public VectorCheckType searchForTypeByName(java.lang.Class type,
                                           java.lang.String name)
Find all the occurrances where there is a node of the given type containing something with the given name.

First, this method searches for the given string name, just like searchForName() does. Then looks to see if that node is of the type requested. If not, it looks at the parent node to see if it is of the type given. If not that, then it looks at the grandparent node, and so on up until it hits the root of the tree.

In general, this method can be thought of as meaning, "Search for the nodes of such-and-such a type that contain this name."

If a name is matched, but it is not contained in a node of the specified type, then that is not considered a match, and it is not returned.

The search for names is case-insensitive.

Parameters:
type - - the type to search for.
name - - the name to search for.
Returns:
A VectorCheckType containing the StarNode objects that were matched. If nothing matched, an empty vector is returned.

searchForTypeByTagValue

public VectorCheckType searchForTypeByTagValue(java.lang.Class type,
                                               java.lang.String tag,
                                               java.lang.String value)
This is much like searchForTypeByTagValue() above, except that it looks for places where the given tag/value matches, and it contains the given value, then it looks to find a node of the given type that the match is inside of.

The search for tag names is case-insensitive.

The search for values, however is case-sensitive.

Parameters:
type - - the type to search for.
tag - - the tag name to search for.
value - - the value to search for.
Returns:
A VectorCheckType containing the StarNode objects that were matched. If nothing matched, an empty vector is returned.

getParallelCopy

public StarNode getParallelCopy()
get parallelCopy is not really implemented yet. It is here as a stub.

setPeer

public void setPeer(StarNode peer)
setPeer is not really implemented yet. It is here as a stub.

getLineNum

public int getLineNum()
Get the line number that this node was on in the original file. Returns -1 if this node was added programmatically and therefore was not actually on a line number in any original file.

setLineNum

public void setLineNum(int num)
setLineNum sets the line number from the text file for this node. This really only has meaningful purpose for the parser.

getColNum

public int getColNum()
Get the column number that this node was on in the original file. Returns -1 if this node was added programmatically and therefore was not actually on a column number in any original file.

setColNum

public void setColNum(int num)
setColNum sets the column number from the text file for this node. This really only has meaningful purpose for the parser.

getPreComment

public java.lang.String getPreComment()
This 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().


setPreComment

public void setPreComment(java.lang.String cmt)

clone

public java.lang.Object clone()
Allocates a new copy (clone) of this StarNode and returns a reference to it. The copy is deep, meaning that the children are also copied (rather than linked). Thus copying a StarFileNode results in a new copy of the whole treee.
Overrides:
clone in class java.lang.Object
See Also:
StarFileNode

setParent

protected void setParent(StarNode p)