starlib: the classes

This document explains the classes used in the starlib.

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 ASTnodes, 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.


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.

Contains:

StarFileNodes contain a single StarFileListNode, which in turn contains the rest of the STAR file in memory.


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.

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


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

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


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.

Contains:

A list of DataNodes


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.


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.

Contains:

This class contains one DataNameNode and one DataValueNode.


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.

Contains:

An IterNode, and a DataLoopDefListNode. The handling of loops is probably the area where 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

Contains:

This class represents one save-frame. It contains a mixed list of DataItemNodes and DataLoopNodes.


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

Contains:

A list of LoopDefListNodes.

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.

Contains:

A list of DataValueNodes, 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 IterNodes. 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.

Contains:

A list of DataNameNodes.

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:


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.


- previous topic - - next topic -