System.Process.Streaming.Text

This module re-exports the entirety of Pipes.Transduce.Text from the pipes-transduce package. It provides functions useful for treating the stdout and stderr streams as text.

It is better to import it qualified:

>>> import qualified System.Process.Streaming.Text as PT

Examples

To process a standard stream as text, use the utf8 or utf8x Transducers, applying them with transduce1 to a Fold1 that accepts text.

The result will be a a Fold1 that accepts raw ByteStrings:

>>> execute (piped (shell "echo foo")) (foldOut (transduce1 PT.utf8x PT.intoLazyText))
"foo\n"   

The difference between utf8 and utf8x is that the former uses an Either to signal encoding errors, while the latter uses an exception.

>>> executeFallibly (piped (shell "echo foo")) (foldOut (transduce1 PT.utf8 PT.intoLazyText))
Right "foo\n"   

foldedLines lets you consume the lines that appear in a stream as lazy Texts. Here we collect them in a list using the list Fold from the foldl package:

>>> :{
      execute (piped (shell "{ echo foo ; echo bar ; }"))
    . foldOut
    . transduce1 PT.utf8x 
    . transduce1 PT.foldedLines 
    $ withFold L.list
    :}
["foo","bar"]

Sometimes we want to consume the lines in stdout and stderr as a single stream. We can do this with foldOutErr and the combined function.

combined takes one Transducer for stdout and another for stderr, that know how to decode each stream into text, then break the text into lines.

The resulting lines are consumed using a Fold1:

>>> :{
      execute (piped (shell "{ echo ooo ; sleep 1 ; echo eee 1>&2 ; }"))  
    . foldOutErr
    . combined (PT.lines PT.utf8x) (PT.lines PT.utf8x)
    $ intoLazyText
    :}
"ooo\neee\n"

We can also tag each line with its provenance, using groups:

>>> :{
    let tag prefix = groups (\producer -> Pipes.yield prefix *> producer)
    in
      execute (piped (shell "{ echo ooo ; sleep 1 ; echo eee 1>&2 ; }"))  
    . foldOutErr
    . combined (tag "+" (PT.lines PT.utf8x)) (tag "-" (PT.lines PT.utf8x))
    $ intoLazyText
    :}
"+ooo\n-eee\n"