This interface provides a facility that makes it easy to write Cedar programs that can process Tioga documents in all their glory, i.e., including the node properties and looks. To this end it defines a record type CharWithLooks that is just what it sounds like — an 8-bit character code together with a boolean array of looks for that character. It also defines a Reader type and a Writer type, analogous to an input and output stream, respectively, but trafficing in objects of type CharWithLooks instead of CHAR. There is a special value of type CharWithLooks that is used to delimit tioga nodes. The extra information about nodes (format, comment flag, level, property list) are made available via the NodeInfo type and its associated operations GetNodeInfo and PutNodeInfo. There a a collection of operations for creating Readers from a variety of sources, and for writing the contents of a Writer to a variety of destinations. Among these possible sources and destinations are a file, the current (primary) selection, and the contents of a Tioga viewer.

The emphasis for this interface is to make it as easy as possible for the client to deal with all the richness of Tioga's document structure; to this end, some efficency concessions have been made. A reader works by making a copy of the source and holding onto it; however only the node structure has to be copied, thanks to the fact that ROPEs and the run structures of looks are immutable. A writer works by constructing a new document structure in virtual memory; this may cause some problems for very large documents. If much of the document is being passed unaltered, consider using CopyNode instead of Gets and Puts; this will increase the sharing of structures, and so decrease the load on VM. There is a Buffer type defined, analogous to an unbounded REF TEXT, but for CharWithLooks. Don't use this to gain efficiency, but only where it fits your needs.

Operations that read and write the selection are atomic, so nothing will break if you do no extra locking. This is the best course of action to take while you are debugging, since it is hard to debug while the selection is locked. However, if your program both reads and writes the selection, use TiogaOps.CallWithLocks to keep the selection from changing during your computation. If you do this, be sure to try and catch all errors that might be caused by bad user input or missing files, etc. It's also a good idea to put a catch phrase as in the example below, to pick up anything you might have missed; this way you won't lock up the user's world with one of your bugs.