All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class EDU.bmrb.starlibj.StarNode

java.lang.Object
   |
   +----EDU.bmrb.starlibj.StarNode

public class StarNode
extends Object
implements 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.)


Variable Index

 o colNum
 o lineNum
 o parent
 o preComment

Constructor Index

 o StarNode()
Default Constructor.
 o StarNode(StarNode)
Copy Constructor - deep copy.

Method Index

 o clone()
Allocates a new copy (clone) of this StarNode and returns a reference to it.
 o getColNum()
Get the column number that this node was on in the original file.
 o getLineNum()
Get the line number that this node was on in the original file.
 o getParallelCopy()
get parallelCopy is not really implemented yet.
 o getParent()
Return the parent of this StarNode.
 o 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.
 o searchByName(String)
searchByName() will generate a list of all the places a particular name exists in this AST object.
 o searchByTagValue(String, String)
Given a tag name and a value, find the AST object that that particular tag and value pair resides in.
 o searchForType(Class, short)
This method returns a vector of all the nodes of the given type.
 o searchForTypeByName(Class, String)
Find all the occurrances where there is a node of the given type containing something with the given name.
 o searchForTypeByTagValue(Class, String, String)
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.
 o setColNum(int)
setColNum sets the column number from the text file for this node.
 o setLineNum(int)
setLineNum sets the line number from the text file for this node.
 o setParent(StarNode)
 o setPeer(StarNode)
setPeer is not really implemented yet.
 o setPreComment(String)
 o Unparse(int)
Unparse prints the contents of the StarNode object out to the given stream.

Variables

 o parent
 protected StarNode parent
 o lineNum
 protected int lineNum
 o colNum
 protected int colNum
 o preComment
 protected String preComment

Constructors

 o StarNode
 public StarNode()
Default Constructor.

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

Methods

 o 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.

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

 o searchByName
 public VectorCheckType searchByName(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.
 o searchByTagValue
 public VectorCheckType 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).

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.
 o searchForType
 public VectorCheckType searchForType(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.
 o searchForTypeByName
 public VectorCheckType searchForTypeByName(Class type,
                                            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.
 o searchForTypeByTagValue
 public VectorCheckType searchForTypeByTagValue(Class type,
                                                String tag,
                                                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.
 o getParallelCopy
 public StarNode getParallelCopy()
get parallelCopy is not really implemented yet. It is here as a stub.

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

 o 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.

 o 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.

 o 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.

 o 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.

 o getPreComment
 public 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().

 o setPreComment
 public void setPreComment(String cmt)
 o clone
 public 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 Object
See Also:
StarFileNode
 o setParent
 protected void setParent(StarNode p)

All Packages  Class Hierarchy  This Package  Previous  Next  Index