reopen stream-name indexer? open-modifier? (as attachment)?

The reopen action is used to open an existing or new stream object so that text can be appended to it. Unlike with the function open, the contents of the attached object are not erased when it is reopened.

For example, the first output action in the following process rule will output "of our discontent", and the second output action will output "Now is the winter of our discontent":

  process
     local stream foo
     local stream bar

     open foo as buffer
     put foo "Now is the winter "
     close foo

     open bar as buffer
     put bar "Now is the winter "
     close bar

     open foo as buffer
     put foo "of our discontent"
     close foo

     reopen bar
     put bar "of our discontent"
     close bar

     output foo || "%n"
     output bar || "%n"

The modifiers available for reopen depend on whether the attachment is specified.

The permitted attachments for reopen are similar to the ones for open:

• referent. Reopens the stream as a referent whose name is given by a string expression.
• file. Reopens the stream as a file whose name is given by a string expression. This is the recommended way to open files.
• external-output-function-call. Reopens the stream as a "connection" to an external output function. When data is written to the stream, it is processed by the external output function. This extends the ways in which OmniMark interacts with the external environment simply by adding external function libraries.

Note that reopening a stream as a buffer (for example, reopen foo as buffer) is deprecated. If you want to append information to a stream that has been previously opened as a buffer, simply use the reopen action without using the as buffer suffix.

When the attachment is specified, all of the open modifiers available for the open action are available for reopen. This is because, if the stream is currently bound to a buffer, reopen as buffer is the same as reopen. If the stream is not bound to a buffer, then reopen as buffer is the same as open as buffer.

When the attachment is not specified, all of the open modifiers available for the open action are available for reopen except text-mode, binary-mode, buffered, and unbuffered.

When the attachment is specified, the reopen action behaves as follows:

• If the named stream is already open, then it is closed first.
• The object specified in the attachement is then opened in "append" mode. Any text written to the stream will be written at the end of the object.
• Unless specified otherwise, the attachment object is reopened with the default (text-mode) open modifiers.

When the attachment is not specified:

• If the stream was already open, it remains open.
• If the stream is closed, then whatever attachment it had when it was closed is reused.
• If the stream was not attached, OmniMark reports an error.
• The element content modifiers are processed in two ways. If they are specified, the specified modifiers are applied to the stream; if they are not specified, the format modifiers that previously applied to the stream are retained. To turn off all format modifiers, use the empty string: reopen s with "".
• The break-width and binary modifiers are treated in two ways. If the modifier is specified, then it is applied to the stream; if the modifier is not specified, the default value is used. The previous settings are not retained.