Pipes.Text.IO

The operations exported here are a convenience, like the similar operations in Data.Text.IO , or rather, Data.Text.Lazy.IO, since Producer Text m r is 'effectful text' and something like the pipes equivalent of lazy Text.

• Like the functions in Data.Text.IO, they attempt to work with the system encoding.
• Like the functions in Data.Text.IO, they are slower than ByteString operations. Where you know what encoding you are working with, use Pipes.ByteString and Pipes.Text.Encoding instead, e.g. view utf8 Bytes.stdin instead of Text.stdin
• Like the functions in Data.Text.IO , they use Text exceptions.

Something like

  view utf8 . Bytes.fromHandle :: Handle -> Producer Text IO (Producer ByteString m ()) 

yields a stream of Text, and follows standard pipes protocols by reverting to (i.e. returning) the underlying byte stream upon reaching any decoding error. (See especially the pipes-binary package.)

By contrast, something like

 Text.fromHandle :: Handle -> Producer Text IO () 

supplies a stream of text returning '()', which is convenient for many tasks, but violates the pipes pipes-binary approach to decoding errors and throws an exception of the kind characteristic of the text library instead.

Producers

fromHandle :: MonadIO m => Handle -> Producer Text m ()

Convert a Handle into a text stream using a text size determined by the good sense of the text library. Note with the remarks at the head of this module that this is slower than view utf8 (Pipes.ByteString.fromHandle h) but uses the system encoding and has other nice Data.Text.IO features

stdin :: MonadIO m => Producer Text m ()

Stream text from stdin

readFile :: MonadSafe m => FilePath -> Producer Text m ()

Stream text from a file in the simple fashion of Data.Text.IO

>>> runSafeT $ runEffect $ Text.readFile "hello.hs" >-> Text.map toUpper >-> hoist lift Text.stdout
MAIN = PUTSTRLN "HELLO WORLD"

Consumers

toHandle :: MonadIO m => Handle -> Consumer' Text m r

Convert a text stream into a Handle

Note: again, for best performance, where possible use (for source (liftIO . hPutStr handle)) instead of (source >-> toHandle handle).

stdout :: MonadIO m => Consumer' Text m ()

Stream text to stdout

Unlike toHandle, stdout gracefully terminates on a broken output pipe.

Note: For best performance, it might be best just to use (for source (liftIO . putStr)) instead of (source >-> stdout) .

writeFile :: MonadSafe m => FilePath -> Consumer' Text m ()

Stream text into a file. Uses pipes-safe.