Syntax

  open stream-reference open-modifiers? as attachment

     where stream-reference is

        stream-name

     or

        new shelf-name ({string-expression})? insertion-point?

Setting a stream to open allows it to be written to and causes previous contents to be lost, just as though the stream had been discarded.

If the second form is used for the stream reference, where the open keyword is followed immediately by the new keyword, a new item is added to the specified stream shelf. The restrictions on this form of the open action are the same as those of the set new action.

A stream can be opened if it is:

• unattached
• closed
• opened, but is not part of current output

The permitted attachments are:

• buffer, which opens the stream as a buffer.
• referent string-expression, which opens the stream as a referent whose name is given by the string expression.
• file string-expression, which opens the stream as a file whose name is given by the string expression. This is the recommended way to open files.
• external-output-function call, which opens 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.

Open modifiers are modifiers that affect how the stream is opened. If more than one open modifier is specified, they must be enclosed in parentheses and separated by "&". Each modifier can be specified only once. The modifiers are:

• element content format modifiers
• append
• binary
• binary-mode
• break-width
• buffered
• domain-free
• referents-allowed
• referents-displayed
• referents-not-allowed
• text-mode
• unbuffered

(Note that for backward compatibility, OmniMark allows the file keyword to be omitted from the file attachment. This practice is deprecated in versions of OmniMark later than V3.)

  local stream x
  ...

  open x with binary-mode as file "y"
  open x with buffered as file "y"
  open x with unbuffered text-mode as file "y"
  open x as binary-mode file "y"
  open x as file binary-mode file "y"

This code fragment includes five different open...as file statements. The first two are equivalent, though the second is the more efficient form of the statement. The third action is different.

The first action opens x in binary mode with the name "y".

The second action opens x as a buffered file with the name "y".

The third action opens x as an unbuffered file in text mode with the name "y".

In the fourth action, note that binary-mode file "y" is a string expression, whose value is the content of the binary file named "y". This is the deprecated form of "open...as file" (with the keyword file omitted), so that x is opened as a file whose name is contained in the binary file "y". On systems where text-mode is the default, x will be opened in text mode; on other systems, it will be opened in binary mode.

The fifth action is a slightly clearer way of doing the same thing as the first action. You are strongly encouraged to use this second form instead of the first.

Related Syntax    file    reopen

Related Concepts    Buffering I/O    Files: binary-mode and text-mode    Output    Variables

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]