pipes-text-0.0.0.7: Text pipes.

Safe HaskellNone
LanguageHaskell2010

Pipes.Text.IO

Contents

Description

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.

Synopsis

Producers

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

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 () Source

Stream text from stdin

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

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 Source

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 () Source

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 () Source

Stream text into a file. Uses pipes-safe.