Pipes/Text/IO.hs

   1 {-#LANGUAGE RankNTypes#-}
   2
   3
   4 module Pipes.Text.IO
   5    (
   6    -- * Text IO
   7    -- $textio
   8
   9    -- * Caveats
  10    -- $caveats
  11
  12    -- * Producers
  13    fromHandle
  14    , stdin
  15    , readFile
  16    -- * Consumers
  17    , toHandle
  18    , stdout
  19    , writeFile
  20    ) where
  21
  22 import qualified System.IO as IO
  23 import Control.Exception (throwIO, try)
  24 import Foreign.C.Error (Errno(Errno), ePIPE)
  25 import qualified GHC.IO.Exception as G
  26 import Data.Text (Text)
  27 import qualified Data.Text as T
  28 import qualified Data.Text.IO as T
  29 import Pipes
  30 import qualified Pipes.Safe.Prelude as Safe
  31 import Pipes.Safe (MonadSafe(..))
  32 import Prelude hiding (readFile, writeFile)
  33
  34 {- $textio
  35     Where pipes @IO@ replaces lazy @IO@, @Producer Text IO r@ replaces lazy 'Text'.
  36     This module exports some convenient functions for producing and consuming
  37     pipes 'Text' in @IO@, namely, 'readFile', 'writeFile', 'fromHandle', 'toHandle',
  38     'stdin' and 'stdout'.  Some caveats described below.
  39
  40     The main points are as in
  41     <https://hackage.haskell.org/package/pipes-bytestring-1.0.0/docs/Pipes-ByteString.html Pipes.ByteString>:
  42
  43     A 'Handle' can be associated with a 'Producer' or 'Consumer' according
  44     as it is read or written to.
  45
  46 > import Pipes
  47 > import qualified Pipes.Text as Text
  48 > import qualified Pipes.Text.IO as Text
  49 > import System.IO
  50 >
  51 > main =
  52 >     withFile "inFile.txt"  ReadMode  $ \hIn  ->
  53 >     withFile "outFile.txt" WriteMode $ \hOut ->
  54 >     runEffect $ Text.fromHandle hIn >-> Text.toHandle hOut
  55
  56 To stream from files, the following is perhaps more Prelude-like (note that it uses Pipes.Safe):
  57
  58 > import Pipes
  59 > import qualified Pipes.Text as Text
  60 > import qualified Pipes.Text.IO as Text
  61 > import Pipes.Safe
  62 >
  63 > main = runSafeT $ runEffect $ Text.readFile "inFile.txt" >-> Text.writeFile "outFile.txt"
  64
  65     Finally, you can stream to and from 'stdin' and 'stdout' using the predefined 'stdin'
  66     and 'stdout' pipes, as with the following \"echo\" program:
  67
  68 > main = runEffect $ Text.stdin >-> Text.stdout
  69
  70
  71 -}
  72
  73
  74 {- $caveats
  75
  76     The operations exported here are a convenience, like the similar operations in
  77     @Data.Text.IO@  (or rather, @Data.Text.Lazy.IO@, since, again, @Producer Text m r@ is
  78     'effectful text' and something like the pipes equivalent of lazy Text.)
  79
  80     * Like the functions in @Data.Text.IO@, they attempt to work with the system encoding.
  81
  82     * Like the functions in @Data.Text.IO@, they significantly slower than ByteString operations. Where
  83        you know what encoding you are working with, use @Pipes.ByteString@ and @Pipes.Text.Encoding@ instead,
  84        e.g. @view utf8 Bytes.stdin@ instead of @Text.stdin@
  85
  86     * Like the functions in  @Data.Text.IO@ , they use Text exceptions, not the standard Pipes protocols.
  87
  88    Something like
  89
  90 >  view utf8 . Bytes.fromHandle :: Handle -> Producer Text IO (Producer ByteString m ())
  91
  92    yields a stream of Text, and follows
  93    standard pipes protocols by reverting to (i.e. returning) the underlying byte stream
  94    upon reaching any decoding error. (See especially the pipes-binary package.)
  95
  96   By contrast, something like
  97
  98 > Text.fromHandle :: Handle -> Producer Text IO ()
  99
 100   supplies a stream of text returning '()', which is convenient for many tasks,
 101   but violates the pipes @pipes-binary@ approach to decoding errors and
 102   throws an exception of the kind characteristic of the @text@ library instead.
 103
 104
 105 -}
 106
 107 {-| Convert a 'IO.Handle' into a text stream using a text size
 108     determined by the good sense of the text library. Note with the remarks
 109     at the head of this module that this
 110     is  slower than @view utf8 (Pipes.ByteString.fromHandle h)@
 111     but uses the system encoding and has other nice @Data.Text.IO@ features
 112 -}
 113
 114 fromHandle :: MonadIO m => IO.Handle -> Producer Text m ()
 115 fromHandle h =  go where
 116       go = do txt <- liftIO (T.hGetChunk h)
 117               if T.null txt then return ()
 118                             else do yield txt
 119                                     go
 120 {-# INLINABLE fromHandle#-}
 121
 122 -- | Stream text from 'stdin'
 123 stdin :: MonadIO m => Producer Text m ()
 124 stdin = fromHandle IO.stdin
 125 {-# INLINE stdin #-}
 126
 127
 128 {-| Stream text from a file in the simple fashion of @Data.Text.IO@
 129
 130 >>> runSafeT $ runEffect $ Text.readFile "hello.hs" >-> Text.map toUpper >-> hoist lift Text.stdout
 131 MAIN = PUTSTRLN "HELLO WORLD"
 132 -}
 133
 134 readFile :: MonadSafe m => FilePath -> Producer Text m ()
 135 readFile file = Safe.withFile file IO.ReadMode fromHandle
 136 {-# INLINE readFile #-}
 137
 138
 139 {-| Stream lines of text from a file
 140 -}
 141 readFileLines :: MonadSafe m => FilePath -> Producer Text m ()
 142 readFileLines file = Safe.withFile file IO.ReadMode fromHandleLines
 143   where
 144     fromHandleLines :: MonadIO m => IO.Handle -> Producer Text m ()
 145     fromHandleLines h =  go where
 146           getLine :: IO (Either G.IOException Text)
 147           getLine = try (T.hGetLine h)
 148
 149           go = do txt <- liftIO getLine
 150                   case txt of
 151                     Left e  -> return ()
 152                     Right y -> do yield y
 153                                   go
 154 {-# INLINE readFileLines #-}
 155
 156
 157 {-| Stream text to 'stdout'
 158
 159     Unlike 'toHandle', 'stdout' gracefully terminates on a broken output pipe.
 160
 161     Note: For best performance, it might be best just to use @(for source (liftIO . putStr))@
 162     instead of @(source >-> stdout)@ .
 163 -}
 164 stdout :: MonadIO m => Consumer' Text m ()
 165 stdout = go
 166   where
 167     go = do
 168         txt <- await
 169         x  <- liftIO $ try (T.putStr txt)
 170         case x of
 171             Left (G.IOError { G.ioe_type  = G.ResourceVanished
 172                             , G.ioe_errno = Just ioe })
 173                  | Errno ioe == ePIPE
 174                      -> return ()
 175             Left  e  -> liftIO (throwIO e)
 176             Right () -> go
 177 {-# INLINABLE stdout #-}
 178
 179
 180 {-| Convert a text stream into a 'Handle'
 181
 182     Note: again, for best performance, where possible use
 183     @(for source (liftIO . hPutStr handle))@ instead of @(source >-> toHandle handle)@.
 184 -}
 185 toHandle :: MonadIO m => IO.Handle -> Consumer' Text m r
 186 toHandle h = for cat (liftIO . T.hPutStr h)
 187 {-# INLINABLE toHandle #-}
 188
 189
 190
 191 -- | Stream text into a file. Uses @pipes-safe@.
 192 writeFile :: (MonadSafe m) => FilePath -> Consumer' Text m ()
 193 writeFile file = Safe.withFile file IO.WriteMode toHandle
 194 {-# INLINE writeFile #-}