output-to

action

Syntax

output-to destination modifiers? (& destination modifiers?)*

Argument definitions

destination: An output destination such as an open stream or an expression that returns a output destination (the file or referent keywords or an external string sink function)

modifiers: Modifiers the affect how data is written to the destination

Purpose

You can use output-to to change the destination of the current output scope.

     process
        output-to file "mary.txt" & #current-output

You can direct output to a file, as above, or to a stream, a referent, or an external string sink function as in the next three examples:

  process
     local stream foo
     open foo as buffer
     output-to foo
        submit file "in.txt"

  process
     output-to referent "foo"
        submit file "in.txt"

  process
     local xslt.stylesheet stylesheet initial { xslt.compile file "stylesheet1.xsl" }
  
     output-to xslt.writer with stylesheet into file "input1.out"
      submit file "input1.xml"

If you use output-to to direct output to a stream, that stream must be open:

  process
     local stream out-file
     open out-file as file "out.txt"
    output-to out-file
        submit file "in.txt"

If you use output-to with a stream, you can apply the following modifiers:

a string expression containing element content modifiers
the binary open modifier

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

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

     process
        output-to file "mary.txt" & #current-output

Note that since output-to changes the destination of the current output scope, it follows that if it is used in an output scope created by 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 markup rules, where every parse continuation operator (%c or suppress) creates a new 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"
            || "%c"
            || "This goes to #main-output%n"
  
     element "flavor"
        output "This goes to #main-output%n"
        output-to mary
        output "%c"
            || "This goes to mary%n"
  
     element "calories"
        output "This goes to mary%n"
            || "%c"
            || "This goes to mary%n"
  
     element "price"
        output "This goes to mary%n"
        using output as lamb
           output "%c"
               || "This goes to lamb%n"
        output "This goes to mary%n"

The output-to in the flavor element rule changes the destinations of the 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 the rest of the subelements of icecream since they are handled 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.

Related Syntax

Related Concepts

Output