The Textual Output Format

Let us now examine the format of the textual output produced by writing an ObjectObject to a basic ChannelChannel (§15.3). To give a concrete example, suppose the Object in question is a SkyFrameSkyFrame, written out as follows:


\begin{terminalv}
AstSkyFrame *skyframe;
\par
...
\par
nobj = astWrite( channel, skyframe );
\end{terminalv}

The output should then look like the following:


\begin{terminalv}
Begin SkyFrame  ...

You will notice that this output is designed both for a human reader, in that it is formatted, and also to be read back by a computer in order to reconstruct the SkyFrame. In fact, this is precisely the way that astShowastShow works (§4.4), this function being roughly equivalent to the following use of a Channel:


\begin{terminalv}
channel = astChannel( NULL, NULL, '''' );
(void) astWrite( channel, object );
channel = astAnnul( channel );
\end{terminalv}

Some lines of the output start with a “#” comment character, which turns the rest of the line into a comment. These lines will be ignored when read back in by astReadastRead. They typically contain default values, or values that can be derived in some way from the other data present, so that they do not actually need to be stored in order to reconstruct the original Object. They are provided purely for human information. The same comment character is also used to append explanatory comments to most output lines.

It is not sensible to attempt a complete description of this output format because every class of Object is potentially different and each can define how its own data should be represented. However, there are some basic rules, which mean that the following common features will usually be present:

  1. Each Object is delimited by matching “Begin” and “End” lines, which also identify the class of Object involved.

  2. Within each Object description, data values are represented by a simple “keyword $=$ value” syntax, with one value to a line.

  3. Lines beginning “IsA” are used to mark the divisions between data belonging to different levels in the class hierarchy (Appendix A). Thus, “IsA FrameFrame” marks the end of data associated with the Frame class and the start of data associated with some derived class (a SkyFrame in the above example). “IsA” lines may be omitted if associated data values are absent and no confusion arises.

  4. Objects may contain other Objects as data. This is indicated by an absent value, with the description of the data Object following on subsequent lines.

  5. Indentation is used to clarify the overall structure.

Beyond these general principles, the best guide to what a particular line of output represents will generally be the comment which accompanies it together with a general knowledge of the class of Object being described.