output-to - OmniMark Keyword

output-to
Full Description

Syntax

  output-to stream-name indexer? open-modifiers? (& stream-name indexer? open-modifiers?)*

Purpose

You can use output-to to change the current output.

  global stream mary

  process
     open mary as file "mary.txt"
     output-to mary

Unlike using output as, which changes output destinations by creating a new current output scope for the duration of the code block that follows, output-to changes the destinations of the current current output scope. The original destinations of the current output are lost and cannot be restored.

To add a new output destination to the current output, use #current-output:

  global stream mary

  process
     open mary as file "mary.txt"
     output-to mary and #current-output

Note that since output-to changes the destinations of the current scope, it follows that, if it is used in a current output scope created by a using output as, the original scope will be restored when the block affected by using output as ends:

  global stream mary
  global stream lamb

  process
     output "This goes to #main-output%n"
     open lamb as buffer
     using output as lamb
     do
        output "This goes to lamb%n"
        open mary as file "mary.txt"
        output-to mary
        output "This goes to mary.txt%n"
     done
     output "This goes to #main-output%n"

It is particularly important to understand how output-to behaves in the markup processor where every parse continuation operator (%c or suppress) creates a new current output scope.

Consider this XML fragment:

  <icecream>
  <flavor>vanilla</flavor>
  <calories>150</calories>
  <price>$1.50</price>
  </icecream>

and this program fragment:

  global stream mary
  global stream lamb

  element icecream
     output "This goes to #main-output%n"
     output "%c"
     output "This goes to #main-output%n"

  element flavor
     output "This goes to #main-output%n"
     output-to mary
     output "%c"
     output "This goes to mary%n"

  element calories
     output "This goes to mary%n"
     output "%c"
     output "This goes to mary%n"

  element price
     output "This goes to mary%n"
     using output as lamb
     do
        output "%c"
        output "This goes to lamb%n"
     done
     output "This goes to mary%n"

The output-to in the flavor element rule changes the destinations of the current output scope created by the last parse continuation operator, in this case the "%c" in the icecream element rule. Thus mary is the current output for all the rest of the subelements of icecream since they are all parsed as part of the parsing initiated by the "%c" in the icecream element rule, except for the content of price, which is directed to lamb by the using output as in the price element rule. How do you decide when to use output-to and when to use using output as? Treat output-to as an advanced feature. If you can solve your problem with using output as, do so. Your code will be easier to understand and maintain. Use output-to where using output as will not work.