untyped_io(3C++)

Synopsis

   #include <String.h>
   class istream;     // see iostream(3C++)
   class ostream;     // see iostream(3C++)
   //  Navigable syntax trees
   struct G2NODE{
       String name;  // see String(3C++)
       String val;   // see String(3C++)
       G2NODE* child;
       G2NODE* next;
   };
   struct G2BUF{
       ... 
       G2NODE* root;
       ... 
   };
   //  Stream insertion and extraction
   ostream& operator<<(ostream& os,const G2BUF& buf);
   istream& operator>>(istream& is,G2BUF& buf);
   //  Stream searching
   String g2seek(istream& is);
   String g2seek(istream& is,const String& name);

Description

Untyped I/O routines can be used to read, write, and seek G2++ records (see G2++(4C++) without advance knowledge of their structure. The operators map between records in streams and navigable syntax trees of type G2BUF. The structure of a syntax tree is isomorphic to that of the corresponding G2++ record.

Navigable syntax trees

A navigable syntax tree is a dynamically-allocated, linked structure, consisting of one or more nodes of type G2NODE. The root node, which is accessed via G2BUF::root, contains the record name in its name field. If the record is flat, for example,

           id      Bob

           person
                   id      Bob
                   age     11

the value field of the root node will contain the empty String and the child pointer will point to a node containing the name of the first indented group (id). next pointers trace the chain of siblings within an indented group. The client navigates a syntax tree by starting at the root and following child and next pointers.

Stream insertion and extraction

Absolutely no interpretation of names or values is performed by these operators; the ASCII characters making up the names and values are simply copied without truncation between the stream and the nodes of the syntax tree.

ostream& operator<<(ostream& os,const G2BUF& buf); Stream insertion. Starts at buf.root and performs a pre-order, left-to-right traversal of the syntax tree, building a G2++ record as it goes. Inserts the resulting record into the output stream os.

istream& operator>>(istream& is,G2BUF& buf); Stream extraction. Searches input stream is until it encounters the next G2++ record, regardless of type. Reads the record and constructs a syntax tree isomorphic to the record in buf. If the stream is exhausted before a record is found, the return value will test as null.

Stream searching

These operations scan an input stream without actually reading a record. They leave the stream properly positioned for either an untyped extraction (see above) or a typed extraction (see typed_io(3C++)).

String g2seek(istream& is); Searches input stream is until it encounters the next G2++ record, regardless of type. Returns the name of the record as the function result. If the stream is exhausted before another record is found, returns the empty String.

String g2seek(istream& is,const String& name); Searches input stream is until it encounters a record of type name (the type of a record is its highest level name - see G2++(4C++)). Returns the name of the record as the function result. If the stream is exhausted before a record with the desired name is found, returns the empty String.

Bugs

There is currently no way to modify the structure of an navigable syntax tree. Clients may only navigate the trees by following pointers, and they may change the values of name and value fields.

Notes

Untyped I/O is used by applications that lack a priori knowledge of record types. For example, tools that manipulate files of G2++ records must be implemented using untyped I/O. Applications that deal with known record types ordinarily use typed insertion and extraction (see typed_io(3C++)).

References