Syntax

  output-to modified-sink (& modified-sink)*

Argument definitions

modified-sink

stream-indexer? (with open-modifiers)? or attachment (with open-modifiers)?

You can use output-to to change the current output scope. If a sink expression is a stream, it must be open. If a modified sink expression is an attachment, it will be opened for the duration of the output scope. The following attachments are permitted for output-to:

• referent string-expression, which attaches the output scope to a referent whose name is given by a string expression.
• file string-expression, which attaches the output scope to a file whose name is given by a string expression.
• an external output function call, which attaches the output scope to 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.

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 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    #current-output    binary

Related Concepts    Output

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