HOME | COMPANY | SOFTWARE | DOCUMENTATION | EDUCATION & TRAINING | SALES & SERVICE
"The Official Guide to Programming with OmniMark"	Site Map | Search:    OmniMark Magazine Developer's Forum
International Edition

OmniMark^® Programmer's Guide Version 3

13. The Current Output Stream Set

Detailed Table of Contents

Previous chapter is Chapter 12, "Functions".

Next chapter is Chapter 14, "SGML Objects".

All output in OmniMark is done through streams. In simpler programs, the streams are transparent: output in the input processor goes to the SGML parser, and output in the output processor goes to the final destination. The primary route of data back into the outside world is through the "current output set", which is represented in OmniMark by #CURRENT-OUTPUT.

OmniMark provides control over the flow of text by providing actions that manipulate the #CURRENT-OUTPUT stream set. Each domain has its own #CURRENT-OUTPUT set. (The streams constituting #CURRENT-OUTPUT are sometimes referred to as the active streams.)

Four actions interact with the #CURRENT-OUTPUT set:

• An OUTPUT action writes to the set of streams that comprise the #CURRENT-OUTPUT set in that action's domain.
• The PUT action:
  • saves the old #CURRENT-OUTPUT set for that domain,
  • establishes a new set of streams as the #CURRENT-OUTPUT set,
  • writes to them,
  • and then restores the old #CURRENT-OUTPUT set.

  Any rule which is performed as a result of a "%c" or a "%v" in the text being written uses the #CURRENT-OUTPUT set established by the PUT.

• The OUTPUT-TO action replaces the #CURRENT-OUTPUT stream set with a new set of streams.
• The prefix "USING OUTPUT AS" temporarily associates a new set of streams with #CURRENT-OUTPUT for the duration of the following action.

  PUT is equivalent to "USING OUTPUT AS" followed by OUTPUT.

The "USING OUTPUT AS" prefix (described in Section 13.3, "Temporarily Changing the Current Output Set"), can be used to change the current output set for several consecutive actions by preceding a DO-DONE block. (See Chapter 8, "Variable Scopes".)

A stream cannot be closed or discarded as long as it is part of any #CURRENT-OUTPUT set. Even if a #CURRENT-OUTPUT set is "buried" due to intervening PUT or "USING OUTPUT AS" actions, eventually it will be reinstated, and OmniMark may try to write to its streams again.

13.1 The Output Action

Syntax

   OUTPUT string-expression

The OUTPUT action writes the specified string-expression to the set of streams that are currently in the #CURRENT-OUTPUT set. As a consequence, the following two actions are equivalent:

Example A

   OUTPUT "Some data.%n"

Example B

   PUT #CURRENT-OUTPUT "Some data.%n"

OUTPUT can be used in a rule triggered by the "%c" in a PUT action, to write to the #CURRENT-OUTPUT set established by the PUT. In the following example, the element sec1 is subordinate to the element chapter and the only stream in the current output set when the chapter element begins is assumed to be the #MAIN-OUTPUT stream:

   ELEMENT chapter
     OUTPUT "Starting a chapter.%n"
     PUT (#CURRENT-OUTPUT & aux) "%c%n"
     OUTPUT "Ending a chapter.%n"

   ELEMENT sec1
     OUTPUT "In a sec1.%n"
     OUTPUT "%c%n"

This example behaves as follows:

1. The first OUTPUT action in the chapter element rule will write the string "Starting a chapter%n" to the #MAIN-OUTPUT stream.
2. The PUT action will write the content of the chapter element to the streams #MAIN-OUTPUT and aux. These streams remain the #CURRENT-OUTPUT set streams until all of the chapter's content is completely processed.
3. The "%c" format item causes the content of the chapter to be processed, triggering the ELEMENT rule for sec1.
4. The OUTPUT action writes text to the #CURRENT-OUTPUT set, which is still the one established by the PUT in the ELEMENT rule for chapter. Therefore, the text written by OUTPUT also goes to the streams #MAIN-OUTPUT and aux.
5. Eventually, all of the content of the chapter element is processed, and the PUT completes, discarding the #CURRENT-OUTPUT set that it created, and restoring the one that was in effect previously.

13.2 Changing the Current Output Set

Syntax

   OUTPUT-TO stream-name indexer? open-modifiers?
       (& stream-name indexer? open-modifiers?)*

The OUTPUT-TO action can be used to change the #CURRENT-OUTPUT set.

Only the following open modifiers can be applied to streams referenced in the OUTPUT-TO action.

1. A string expression containing the element content format modifiers.
2. The BINARY open modifier.

The name #CURRENT-OUTPUT can be used in place of a stream-name. This allows new streams to be added to the streams which are already part of #CURRENT-OUTPUT, instead of replacing them entirely. However, #CURRENT-OUTPUT may not have any open modifiers attached to it.

The following small OmniMark program fragment can be used to convert an up-translation to what effectively becomes a cross-translation. It serves to satisfy the input requirements of the SGML parser in a FIND-START rule prior to executing any FIND rules.

   UP-TRANSLATE

   FIND-START
      OUTPUT-TO #SGML
      OUTPUT "<!doctype noop [<!element noop - o empty>]><noop>"
      OUTPUT-TO #MAIN-OUTPUT

   FIND ....

The first OUTPUT-TO action makes the #SGML stream the only active stream. The OUTPUT action writes a small document into the SGML parser, satisfying its input requirements. The second OUTPUT-TO action makes the #MAIN-OUTPUT stream the only active stream, which is the default situation in a cross-translation.

The following syntactic variations are permitted:

• The keyword AND can be used in place of "&".

     OUTPUT-TO #MAIN-OUTPUT & #ERROR
  

• The list of stream-names may be enclosed in parentheses to improve readability.

  Example A

     OUTPUT-TO (#MAIN-OUTPUT & #ERROR)
  
  

  Example B

     OUTPUT-TO (#MAIN-OUTPUT & #ERROR)
  

13.3 Temporarily Changing the Current Output Set

Syntax

   USING OUTPUT AS stream-name indexer? open-modifiers?
      (& stream-name indexer? open-modifiers?)*
      action

The "USING OUTPUT AS" prefix causes the named streams to be the new current output set during the action contained by the prefix.

Only the following open modifiers are permitted with OUTPUT-TO:

1. A string expression containing the element content format modifiers.
2. The BINARY open modifier.

Finally, action is the action that falls under the control of the using-prefix. If the action contains a "%c" format item, all the element content indicated by the "%c" is written to the named streams unless a PUT action, SET action, or "USING OUTPUT AS" prefix is encountered.

The following two actions are equivalent:

Example A

   USING OUTPUT AS title OUTPUT "title text"

Example B

   PUT title "title text"

"USING OUTPUT AS" is more useful when a number of actions all write to the same streams, as in the following example:

   LOCAL STREAM title
   LOCAL STREAM verbatim
   ...
   USING OUTPUT AS (title with "l" & verbatim with "zh" & #MAIN-OUTPUT)
   DO
     OUTPUT "Title text = %""
     OUTPUT name of title
     OUTPUT "%"%n%c%n"
   DONE

Several actions are needed in this example in order to access the name of stream 'title', as it cannot be expressed as a format item.

The following syntactic variations are permitted:

• The keyword AND can be used in place of "&".

     OUTPUT-TO #MAIN-OUTPUT & #ERROR
  

• The list of stream-names may be enclosed in parentheses to improve readability.

  Example A

     OUTPUT-TO (#MAIN-OUTPUT & #ERROR)
  
  

  Example B

     OUTPUT-TO (#MAIN-OUTPUT & #ERROR)
  

13.4 Establishing a Current Output Set

#CURRENT-OUTPUT sets are established by:

• Actions which write to streams:
  • PUT establishes the specified set of streams as the new set of current output streams.
  • The SET (or "SET STREAM") applied to a stream, establishes a temporary buffer as the new set of current output streams. (The contents of the temporary buffer are copied to the specified stream after the string expression has been fully evaluated. This allows the string expression to incorporate the contents of the target stream.)

  These actions establish a #CURRENT-OUTPUT set for the duration of the write. The new #CURRENT-OUTPUT set is used for:

  • Any STREAM-returning function whose return value is a component of the string expression being written.
  • Any external output function whose result is a component of the string expression being written.
  • Any rule performed as a result of a "%c" format item in the string expression in these actions.
• "USING OUTPUT AS".

  "USING OUTPUT AS" establishes a new #CURRENT-OUTPUT set for the duration of the following action.

• "DO SGML-PARSE"

  "DO SGML-PARSE" has its own rules for establishment and inheritance of the current output set (see Chapter 17, "SGML Document and Subdocument Parsing").

• all other actions:

  All other actions simply inherit the current output set from the context in which they are performed. At the top-most level of the input processor and output processors, the current output set is established by the type of the translation being performed by the OmniMark program.

• the body of an EXTERNAL-TEXT-ENTITY rule:

  The body of an EXTERNAL-TEXT-ENTITY rule uses the #SGML stream as the #CURRENT-OUTPUT set.

  The conditions in the rule header use the #CURRENT-OUTPUT set currently established for the output processor.

• In a condition at the head of any other rule, the current output set is that which the rule would have if the rule was selected.
• In a pattern at the head of a FIND, TRANSLATE, or PROCESSING-INSTRUCTION rule, the current output set is also that which the rule would have if the rule was selected.

13.5 Changing the Current Output Stream Set in the Output Processor

The OUTPUT-TO action only affects the active current output set. Any saved #CURRENT-OUTPUT sets are unaffected. This has an important implication for rules in the output processor (like ELEMENT rules).

Each time a SUPPRESS action or "%c" format item is encountered, a the old current output stream set is saved and a new one is created. When an OUTPUT-TO action is used to change the current output stream set, the new current output stream set is in effect only until the old output stream set is restored (or another OUTPUT-TO is encountered).

For instance, consider a chapter that contains paragraph elements. If an OUTPUT-TO is executed in a paragraph (without being inside a "USING OUTPUT AS"), it will affect all subsequent OUTPUT statements in that element rule, and all OUTPUT actions in succeeding paragraphs as well. The new current output set remains in affect until the end of the chapter, or until another OUTPUT-TO is encountered.

When the chapter ends, the current output stream set is discarded, and the old one restored. After this point, the OUTPUT-TO will no longer have an effect. It will not affect any paragraphs in the following chapters.

OUTPUT-TO can be useful when part of an element must go to one destination and other part must go somewhere else.

13.5.1 Changing the Current Output Stream Set in TRANSLATE Rules.

TRANSLATE rules are a special case of output processor rule. They an be turned off for particular streams by setting the "z" open modifier.

Thus, TRANSLATE rules do not necessarily operate on all of the streams in the current output set. Instead, when a TRANSLATE rule is triggered, the current output set is partitioned into two sets: the set of streams that the TRANSLATE rule can affect, and the set which is unaffected. When the TRANSLATE rule completes, the current output set is unpartitioned.

Because a TRANSLATE rule does not affect the entire current output set, the effect of any OUTPUT-TO action is limited to the TRANSLATE rule in which it occurs.

In other words, it is as if the actions in each TRANSLATE rule were wrapped in a USING OUTPUT AS #CURRENT-OUTPUT DO ... DONE.

Next chapter is Chapter 14, "SGML Objects".

Copyright © OmniMark Technologies Corporation, 1988-1997. All rights reserved.
EUM27, release 2, 1997/04/11.