Streams: attachments

A stream is always opened with a destination, called an attachment. There are three kinds of stream attachments:

Buffers, which serve a function analogous to string variables in other programming languages. They are used to store the results of string expressions for use later within the program.

Files, which OmniMark can create and write to files in the external file system. This is a useful way of saving information that can be used by applications that will run at a later time.

Referents, which are a feature designed specifically for hypertext applications. They are used to resolve forward references (references into a part of the document that has not been processed yet). Briefly put:

• When the target of a reference is found, the programmer creates a referent and writes information to it.
• When a reference to the target is found, the programmer outputs the referent.

These operations can be done in any order; OmniMark will remember where the referents have been written to, and will replace the referent with its final contents when the referent resolution is complete.

Referent resolution is usually performed after the program completes. The programmer can also define nested referent scopes. The referents created and written in a nested referent scope will be resolved when the scope completes.

Streams are initially unattached.

You can test a stream to determine the type of object it is attached to. A stream whose contents have been discarded is not attached. If a stream is attached, it is either open or closed.

A stream is:

• a buffer if the stream is attached to a buffer
• a file if the stream is attached to a file
• a referent if the stream is attached to a referent
• either an sgml-parser or an xml-parser if the stream is the #markup-parser stream
• an external stream if the stream is attached to an externally defined output stream
• attached if any of the above are true