These classes very closely mirror the BNF grammar for parsing STAR files. There is almost a one-to-one mapping of rules in the BNF grammar to classes in the library. Therfore, each class represents a "piece" of the STAR file.
ASTnode. (from "astnode.h")
ASTnode
is a base class from which all other
classes are derived. It is a pure virtual class, so you
cannot have an object of type ASTnode
. However,
you can have pointers to ASTnode
s, and often
this is useful for keeping a reference to some item from
a STAR tree that you do not know what it is yet. This is
often used throughout the starlib functions.
While ASTnode
is not a final class, it contains
many functions that will be useful in their overridden forms
in other classes derived from ASTnode
. Any time
there is a function at the generic ASTnode
level
to achieve a task, it is preferable to use that function
instead of using a more specialized function.
Here are the the important parts of ASTnode
. For
the full details, see the header file "astnode.h"
.
This list attempts to describe what the methods can be used for,
rather than describing their exact prototypes. In the future there
are plans to make use of a tool like
noweb to eliminate
the need for this split documentation.
ASTtype
: This is an enumerated type used
to help identify the different types of classes that are
derived from ASTnode. Each kind of class that is derived
from ASTnode has an identifier in this enumerated type.
Each ASTnode object has a member of this type that it
uses to flag what kind of ASTnode it is. There are
various methods of ASTnode
that use this
type to communicate information to the caller.
constructors
: For all derived classes
of ASTnode
, there exist deep-copy constructors
that will make copies of the entire STAR syntax tree from
the point at which the constructor is called downward.
To make a copy of a saveframe, simply use the copy constructor
of SaveFrameNode
, to
copy an entire STAR file, use the copy constructor of
StarFileNode
, and so on.
destructors
: For some derived classes of
ASTnode
, the destructors are laid out
such that they will properly remove themselves from
their parent node. See the deletion
example to see which classes can be deleted safely
with this technique.
Unparse()
: All ASTnode
-derived
classes have a method called Unparse()
that will
write out the node (and all things inside it) to an output
file in legal STAR syntax. This method takes one parameter,
which is an indentation level determining how many spaces
to indent the output (normally, it is just set to zero).
The output file is determined by a global C++
ofstream
variable called os
, meaning
"output stream". How to set up this variable is explained
in the document about making a simple main
program.
myType()
: This method simply returns a
ASTtype
enum
that tells exactly what kind of class this object is.
This is useful if you have a generic pointer to an
ASTnode
and you want to know the type to
which it should be casted.
myParent()
: This method gives a pointer
to the parent object that this object is inside. Repetative
calls to this method in a loop can be used to "walk" up the
tree, eventually reaching the
StarFileNode
that this item is inside.
If this object is not inside another object, this method
returns NULL
. It is guarnateed that the
"parent chain" will not loop. Sucessive calls to
myParent()
should eventually reach a NULL.
isOfType()
: This method is similar in
purpose to myType()
,
except that it can make use of the class derivation
hierarchy to determine if this object is of the type
mentioned, by virtue of object inheritence. For example, a
DataItemNode
is a kind of
DataNode
, which in turn is a kind of
ASTnode
. If you had an object of type
DataItemNode
, and called its
isofType()
method with an argument of
ASTnode::DATANODE
, the result would be
true.
searchByTag()
: This method allows the
caller to search for a particular piece of STAR file by
name. It can be used to find any part of a STAR file.
For example, you could search for a saveframe called
save_author_details
, or for a data item
called _author_first_name
. Note that you must
include the whole name of the tag, including the leading
underscore, or other prefix (like "save_", or "data_")
To search in an entire STAR file, use the
StarFileNode
's searchByTag()
function. To search just one saveframe, use that saveframe's
searchByTag()
method, and so on.
The result that is returned is a list of pointers to matching
nodes. To see the layout of the List class, see the explanation
in the list documentation. The reason
it is a list is that there can theoretically be more than
one hit if searching an entire STAR file for a tag. Even
in places where it is known that there can only be one
hit (such as searching a save frame for a tag), the method
still returns a list, even though it should never have moreu
than one thing in it. This is to preserve consistency
throughout all the ASTnode
classes. If you
have a pointer to an ASTnode
, you do not need
to know what kind of ASTnode
it is in order to
call its searchByTag()
function.
There are overloaded versions of this function to handle
being called via a char *
or a string
.
searchByTagValue()
: This method is
identical to
searchByTag()
shown above, but with
an extra parameter. This method will only return a match
if the given tag has a particular value. For example,
instead of just searching for "_some_tag", you can search
for places where "_some_tag" has a value of "X". This works
for both
DataItemNode
s, and loops. In a loop,
if any of the values for the tag are a match, then a match
is returned. For loops, the value from within the loop where
the match occurred is what is returned.
There are overloaded versions of this function to handle
being called via a char *
or a string
.
searchForTypeByTag()
: This method is
identical to
searchByTag
shown above, but with
an extra parameter. This method will return a match only
if it is of the given type. This method can be used to
search only for saveframes, or only for loops, and so on.
If a match is not of the right type, this method will "walk up the parent list" until it finds one that is, or it hits NULL and gives up. Thus, this method will return a parent of a match if the parent is of the right type. Thus you can use this function to do things like "search for the saveframe in which there is a tag named such-and-such."
There are overloaded versions of this function to handle
being called via a char *
or a string
.
searchForTypeByTagValue()
: This method is
identical to
searchByTagValue()
, except that it
searches only for specific types, and it walks up the
"parent list", as describe above for
searchForTypeByTag()
.
myParallelCopy()
: This method is
used only when making use of a parallel-copy of a tree with
peer links. This is a rather unusual thing to do, and might
not be useful to most users. See the
parallel-copy documentation for an explanation.
StarFileNode. (from "ast.h")
StarFileNode
is derived from
ASTnode
This is the mother of all ASTnode objects. Literally. Thinking
of the STAR file as a tree of nodes, this object is the root
parent of all the other objects in an in-memory STAR file. If
you start with any object in the STAR file, and walk up the parent
chain long enough, your should eventually end up at the
StarFileNode
that starts the tree.
StarFileNode
s contain a single
StarFileListNode
,
which in turn contains the rest of the STAR file in memory.
ASTnode
and are kept
only for historical reasons. Don't rely on their continued
existence in the future:
ReturnDataBlockNode
:
Antiquated by
searchByTag
.
RemoveSaveFrame
:
Antiquated by using SaveFrameNode
s
destructor instead.
GiveMyDataBlockList
: This method
returns the list of datablocks (and a globalblock if
it exists) that make up the STAR file. This list is
directly manipulatable. (You can use the
list primitives on it directly to
add new blocks or iterate over the datablocks.)
These functions are all adequetely explained in the
header file "ast.h"
:
AddSaveFrameToDataBlock()
AddDataBlock()
AddSaveFrame()
AddSaveFrameDataItem()
AddSaveFrameLoop()
AddSaveFrameLoopDataName()
AddSaveFrameLoopDataValue()
HeadingNode. (from "ast.h")
HeadingNode
is derived from
ASTnode
.
HeadingNode
is a type that holds a simple header for
one of the other types of nodes. It has several subtypes depending
on what kind of heading it is. Typically a heading is just a string.
HeadingNode
s are typically used only for labelling
large things in the STAR syntax. For example, if a saveframe
is named "save_example_frame", then the "save_example_frame" string
would be stored in a HeadingNode
of some sort.
myName()
: This method returns the C++ string
that is the name of this heading.
changeName()
: This method changes the name
of this heading.
GlobalHeadingNode. (from "ast.h")
GlobalHeadingNode
is derived from
HeadingNode
.
This is just a special case of
HeadingNode
, used to label global_ blocks.
DataHeadingNode. (from "ast.h")
DataHeadingNode
is derived from
HeadingNode
.
This is just a special case of
HeadingNode
, used to label data_ blocks.
SaveHeadingNode. (from "ast.h")
SaveHeadingNode
is derived from
HeadingNode
.
This is just a special case of
HeadingNode
, used to label save frames.
DataValueNode. (from "ast.h")
DataValueNode
is derived from
ASTnode
DataValueNode
s are used in any place where a value is
held in the STAR syntax. This includes individual data items and
values in the bodies of loops.
ValType
: This enumerated type is used to
keep track of what kind of delimiter this data value node
uses when it is printed in a STAR file. All kinds of
values are represented by this one type. Note that the
delimiter is not a part of the actual value. It is added
when printing the valueto a file.
myDelimType()
: This method returns the
delimiter type that this value will use when it is
printed via Unparse
.
setDelimType()
: This method sets the
delimiter type that this value will use when it is
printed via Unparse
.
BE CAREFUL! There are no checks to ensure that this change
is syntacticly correct in a STAR file. For example, if you
take a value that originally had multiple lines, and you
change it from a semicolon-delimited string into a single-quote
delimited string, that will produce a STAR file with invalid
syntax when it is printed. (Due to the line-breaks in the
middle of the single-quote string.)
myValue()
: This method returns the string
value stored in this object. The delimiter characters are
not part of this string.
setValue()
: This method sets the string
value stored in this object. Do not include the delimiter
characters in this string. BE CAREFUL! There are no checks
to ensure that what you do is syntacticly correct. For
example, you could change the string of a single-quoted
value to a multiple-line string without changing its
delimiter type to a semicolon-delimited string, which will
cause the output file to be invalid STAR syntax when you
print it out.
myName()
: This method is a duplicate
of myValue
kept mostly for historical reasons.
operator ==
: The '==' operator has been
overloaded for DataValueNode such that when you compare a
DataValueNode to a string that has delimiters such as
quotation marks or semicolons, the delimiters are ignored
in the comparasin.
BlockNode. (from "ast.h")
BlockNode
is derived from
ASTnode
This is a base class for holding "blocks" of "stuff". It has two
derivations: DataBlockNode
and GlobalBLockNode
. Both
data blocks and global blocks are similar enough that they can be
handled the same way using this one class.
DataNode
s
ASTnode
and are kept
only for historical reasons. Don't rely on their continued
existence in the future:
ReturnDataBlockDataNode
:
Antiquated by
searchByTag
.
RemoveSaveFrame
:
Antiquated by using SaveFrameNode
s
destructor instead.
GiveMyDataList()
: This method returns
a list of the DataNode
s
in the block. This list is directly manipulatable.
You can use the list primitives to
directly add things to the block and iterate over its items.
myName()
: This method returns the name
of this data block: for example,
"data_sample_values"
, or "global_"
These functions are all adequetely explained in the
header file "ast.h"
:
StarListNode. (from "ast.h")
StarListNode
is derived from
ASTnode
This class holds the list of items in the STAR file. You should
never have to use it directly. You should be able to get everything
done using the methods in the StarFileNode
that contains an object of this class.
GlobalBlockNode. (from "ast.h")
GlobalBlockNode
is derived from
BlockNode
This class is just a special case of
BlockNode
that is used for global_ blocks as opposed
to data_ blocks.
DataBlockNode. (from "ast.h")
DataBlockNode
is derived from
BlockNode
This class is just a special case of
BlockNode
that is used for data_ blocks as opposed
to global_ blocks.
DataNameNode. (from "ast.h")
DataNameNode
is derived from
ASTnode
This class is used to hold the tag name of some data. It is used by both single-item data tags and in loops.
myName()
: This method returns the string
for this name.
setName()
: This method sets the string
for this name. Be sure to make it a name that begins with
an underscore, as all legal names should. As of now, there
is no check to verify that the name is syntacticly valid.
This might change in the future.
DataItemNode. (from "ast.h")
DataItemNode
is derived from
DataNode
This class is used to store a single data item, such as this:
_tag_name "value"The tag/value pair is kept together in this class.
DataNameNode
and one DataValueNode
.
constructors
: There exist several
constructors for DataItemNode
s that will
create a new data item given a string for the tag name
and a string for the value, and the value's delimiter
type. If the value's delimiter type is left off, then
a non-quoted string is assumed.
myName()
: This method will return
the string name of the tag for this data item.
setName()
: This method will change
the string name of the tag for this data item. BE CAREFUL -
make sure you use a value with a leading underscore. There
is no check to ensure that you do this at the moment.
myValue()
: This method will return
the string value of this data item.
setValue()
: This method will change
the string value of this data item. BE CAREFUL! It is
possible to change the string value such that the
delimiter type is not correct anymore. (For example,
you could take a non-quoted value and change it to a
string that has some spaces, and forget to change the
delimiter type.)
myDelimType()
: This method will return
the delimiter type of the value of this data item. See
DataValueNode::ValType
for more details about what this means.
setDelimType()
: This method will change
the delimiter type of the value of this data item. See
DataValueNode::ValType
for more details about what this means. BE CAREFUL!
There is no check to ensure that your changing of the delimiter
type is syntacticly correct. For example, you could take a
quoted value with spaces in it and change it so it is no
longer quoted, which will cause an invalid STAR file to be
created if this is printed out.
DataLoopNode. (from "ast.h")
DataLoopNode
is derived from
DataNode
This class holds a loop. The interior of it is rather complex, to handle the different kinds of nested loops that exist in STAR files. Most of the time, you should only need to use the methods in this class, and not concern yourself with the classes inside this class.
IterNode
, and a
DataLoopDefListNode
.
myName()
: Although loops don't really
have names, for the sake of having a consistent
convention, all DataNode
s need to have
a method called myName()
, and
DataLoopNode
is a DataNode
.
This method will actually return the name of the first
tag inside the loop.
FlattenNestedLoop()
: This method
returns two lists. One is a list of of the tag names
for this loop and one is the list of the data values.
(This method only returns the singly-nested outermost
loop.) These two lists can be used to iterate over
the values in the loop. The value list is a flat
list of all the elements of the loop in row-major
order. So to visit the values of the 3rd column of
a loop that has 5 columns, you would first move to
the 3rd element of the value list, then look at every
fifth element of the list thereafter.
returnLoopValues()
: This method
returns a list of the values for a column of the
loop, given the name of one of the tags of the loop.
This method is only capable of getting values from
the outermost singly-nested loop. Example: You have the
following loop:
loop_ _tag1 _tag2 _tag3 _tag4 "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" stop_In this case, if you call
returnLoopValues
with an argument of "_tag2"
, you will get
a list back containing "B", "F", and "J".
Note that this list contains the actual values in the loop, so you can change the values in the list, and it will cause the values in the loop to change.
tagPositionDeep()
: This method returns
the position at which a tag name is located in the loop.
It returns the nesting level, and the column of the tag.
For example, if the tag being queried is at the 3rd column
of the 2nd nested loop, the returned values will be
nestLevel = 1, column = 2 (starts counting at zero). If
the tag name in question is not in the loop, negative values
are returned.
RemoveColumn()
: This method deletes
a column from the outermost loop given the tagname.
For example, if there was a loop like this...
loop_ _tag1 _tag2 _tag3 _tag4 "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" stop_...calling that loop's
RemoveColumn
method
with a parameter of "_tag3"
would result
in a loop like this:
loop_ _tag1 _tag2 _tag4 "A" "B" "D" "E" "F" "H" "I" "J" "L" stop_
ChangeName()
: This method changes one
of the tag names in the loop. It takes two parameters:
the original name, and the name to which it should be changed.
constructors
: There is currently no
way to make signifigant additions to a loop once it has
been parsed into memory. The only way to do so is to
use the constructors to create a new loop from scratch.
There are several forms of the constructor for doing
this. Improvements to this technique are planned in
future versions of starlib.
starlib
could stand to use the most improvement. Suggestions for
improvements to the API for DataLoopNode are welcome.
SaveFrameNode. (from "ast.h")
SaveFrameNode
is derived from
DataNode
myName()
: This method will return
the string name of this save frame.
setName()
: This method will change
the string name of this save frame. CAUTION! Be sure to
use a string beginning with "save_"
.
AddItemToSaveFrame()
: Given a pointer
to a newly created DataNode
object, this method adds that object to the end of the
save frame. Note: Do not delete the object after adding
it - it is linked into the save frame, not copied. This
same method can be used to add either loops or data items.
GiveMyDataList()
: returns a list of
the DataNode
s that
are in this save frame. This is a directly manipulatable
list. Deleting, adding, or changing the items in this
list will make changes to the actual save frame.
ReturnLoopValues()
: Returns a list
of values for a given tag, assuming that that tag is
inside a loop in the saveframe somewhere. See
DataLoopNode::ReturnLoopValues()
for more details.
AddDataItem()
: Adds a new data
item to the end of the save frame, given its tag name,
string value, and delimiter type.
DataLoopDefListNode. (from "ast.h")
DataLoopDefListNode
is derived from
ASTnode
This class holds a list of the tag names that label a loop. (Actually, in order to handle nested loops, this class actually holds a list of lists of tag names.)
LoopDefListNode
s.
For the most part, you should not need to manipulate objects of this
class directly. You should be able to achive the functionality you
need using the methods in the
DataLoopNode
object that contains
this class.
IterNode. (from "ast.h")
IterNode
is derived from
ASTnode
This class holds the values of one row of a loop, and if that row has an inner loop 'hanging' off if it, it contains a pointer to that loop.
DataValueNode
s, and a
pointer to an innner loop (a LoopIter
).
You should not need to manipulate this class directly. You should
be able to get all the needed functionality out of the
DataLoopNode
that contains
this object.
LoopIter. (from "ast.h")
LoopIter
is derived from
ASTnode
This class holds a list of IterNode
s.
This class represents one "table" in a loop. Each IterNode
is one row of the 'table'. Each row of the table can also have
another LoopIter
in it, representing another "table"
of values at a deeper nesting level.
You should not need to manipulate this class directly. You should
be able to get all the needed functionality out of the
DataLoopNode
that contains
this object.
LoopDefListNode. (from "ast.h")
LoopDefListNode
is derived from
ASTnode
This class holds the tag names associated with a loop. In the case of a nested loop, there will be a different one of these for each level of nesting.
DataNameNode
s.
You should not need to manipulate this class directly. You should
be able to get at all needed functinality using the
DataLoopDefListNode
that contains this object.
DataLoopValListNode. (from "ast.h")
DataLoopValListNode
is derived from
ASTnode
This class holds a list of values for the body of the loop.
NOTE: This class is only used when first building a new loop. Once the loop has been constructed, this class is no longer used. (The loop transforms this format into its own internal representation.)
The only thing in this class that you should need to know is that there is an enumerated type that is used as a return value for some of the methods in other classes:
Status
: This enumerated type holds
one of three values: END, STOP, or CONTINUE. It is
used in certain iteration functions that manipulate
this class as a means of communicating what is left in
the loop:
stop_
keyword
was seen in the STAR file at this point, so
the next values (if there are any) will be
at one nesting level "further up".
LoopValListNode. (from "ast.h")
LoopValListNode
is derived from
ASTnode
This class is used internally by loops. You should not need to manipulate this class directly.
NOTE: This class is only used when first building a new loop. Once the loop has been constructed, this class is no longer used. (The loop transforms this format into its own internal representation.)
DataListNode. (from "ast.h")
DataListNode
is derived from
ASTnode
This generic class contains a list of data. It is used inside of several other classes and you will probably never need to deal directly with it.
DataNode. (from "ast.h")
DataNode
is derived from
ASTnode
This is not a complete class. it is a pure virtual class
that serves only as a stub placeholder for
DataItemNode
, and
DataLoopNode
, and
SaveFrameNode
.
SaveFrameListNode. (from "ast.h")
SaveFrameListNode
is derived from
ASTnode
This class contains a list of the things that can be allowed in
a save-frame (Data Items and Data Loops). It is used inside of
SaveFrameNode
and you
will probably never need to deal directly with it.