OmniMark distinguishes the act of creating output from the act of selecting the output destination, meaning that the stream that receives the output data does not have to be lexically in scope for you to output to it. Instead, a stream or a string sink can be placed in an output execution scope. While a stream is in the current output scope, all output statements will output to it regardless of the lexical scope they occur in.

You can use the keywords using output as to create an output scope and to place a stream variable into that output scope. Like any other kind of scope, output scopes can be nested:

  process
      local stream foo
      open foo as file "foo.txt"
      using output as foo
      do
          output "<rhyme>"
          submit "Mary had a little lamb"
          output "</rhyme>"
      done
      
  find ("Mary" | "lamb") => person
      local stream foo
      reopen foo as file "foo2.txt"
      using output as foo
        output "<person>" || person || "</person>"    

Here a new output scope is established in the find rule, causing the material output in the find rule to be sent to a different destination. This output scope is nested inside the output scope created in the process rule. This scope becomes the current output scope again as soon as the find rule exits.

You can also place a stream into the current output scope, without creating a new output scope, using output-to:

  global stream foo 
  global stream bar
      
  process
      open foo as buffer
      open bar as buffer
      using output as foo
          submit "Mary had a little lamb"
      close foo
      close bar
      output "Foo contains: " || foo
      output "%nBar contains: " || bar
          
  find " a "
      output-to bar

This program outputs the following:

  Foo contains: Mary had
  Bar contains: little lamb

The output-to in the find rule resets the destination of the output scope established by the using output as in the process rule. Thus the rest of the text goes to the new destination.

In general, you should use using output as rather then output-to, but output-to is useful in certain situations, especially when the destination of data is determined by examining the data itself.

Consider a piece of XML that might be used to send files across a network. It encapsulates the name of the file and its contents inside "name" and encapsulates "data" elements inside a "file" element:

  <file>
  <name>myfile.txt</name>
  <data>The content of the file.</data>
  </file>

We can process this with the following program:

  global stream file-data
  process 
      do xml-parse document
          scan file "files.xml"
          suppress
      done
      
  element file
      suppress
      close file-data
      
  element name
      open file-data as file "%c"
      output-to file-data
      
  element data
      output "%c"

Here the entire processing of the XML is done in a single output scope, but every time we find a filename in the input we change the destination of the current output scope. It would be difficult to do the same thing with using output as, because the "data" element is not nested inside the "filename" element, so an output scope established in the "name" element would have expired before the "data" element was processed.

(By the way, the example shows poor XML language design. It would have been better to make the filename an attribute of the "file" element. But you can't always control the format of the data you have to process.)

If you use output-to, note that placing a stream into an output scope does not exempt it from the rules of lexical scoping when it comes to the life span of variables. Local variables are created when their lexical scope enters execution scope and destroyed when their lexical scope leaves execution scope. It is an error to allow a local variable to go out of execution scope while it is still in an output scope. You will avoid this problem if you stick to using using output as to create output scopes.

Prerequisite Concepts Output Scope of execution

Related Syntax using output as

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