Links: Next Previous Up Top

# How do I use `push_output`?

The subroutine `push_output(type[,data])` takes two arguments: the type, which is always required, and the data, which is needed for certain types of output. Table 3 lists the different types which you can push onto the output stack.

### Table 3: Types for `push_output`

Type
  `'handle'`
Data
  a filehandle
Description
  Send all output to the supplied filehandle.

Type
  `'file'`
Data
  a filename
Description
  Open the supplied file for writing, erasing its current contents (if any), and send all output to it.

Type
  `'append'`
Data
  a filename
Description
  Open the supplied file for writing and append all output to its current contents.

Type
  `'pipe'`
Data
  a shell command
Description
  Pipe all output to the supplied shell command.

Type
  `'string'`
Data
  a string [optional]
Description
  Append all output to the supplied string, which will be returned by `pop_output`.

Type
  `'nul'`
Data
  [none]
Description
  Ignore all output.

Because the output is stack-based, you do not lose the previous output destination when you push a new one. This is especially convenient for dealing with data in tree-structures, like SGML data -- for example, you can capture the contents of sub-elements as strings, ignore certain types of elements, and split the output from one SGML parse into a series of sub-files. Here are some examples:

    push_output('string');                  # append output to an empty string
    push_output('file','/tmp/foo');         # send output to this file
    push_output('pipe','mail webmaster');   # mail output to 'webmaster' (!!)
    push_output('nul');                     # just ignore all output

Links: Next Previous Up Top