aboutsummaryrefslogtreecommitdiffhomepage
path: root/Pipes/Text
diff options
context:
space:
mode:
authormichaelt <what_is_it_to_do_anything@yahoo.com>2014-02-15 15:00:07 -0500
committermichaelt <what_is_it_to_do_anything@yahoo.com>2014-02-15 15:00:07 -0500
commit327be7638ab8de6c0589b5fcb9177f5186ace4de (patch)
tree2c2294012a0c14c8da0ad5950d8b513357fa09a6 /Pipes/Text
parent89d805572083581a9c90c517351196fcc648485a (diff)
downloadtext-pipes-327be7638ab8de6c0589b5fcb9177f5186ace4de.tar.gz
text-pipes-327be7638ab8de6c0589b5fcb9177f5186ace4de.tar.zst
text-pipes-327be7638ab8de6c0589b5fcb9177f5186ace4de.zip
improve documentation Pipes.Text.IO
Diffstat (limited to 'Pipes/Text')
-rw-r--r--Pipes/Text/IO.hs54
1 files changed, 43 insertions, 11 deletions
diff --git a/Pipes/Text/IO.hs b/Pipes/Text/IO.hs
index 3c9ac98..92500c3 100644
--- a/Pipes/Text/IO.hs
+++ b/Pipes/Text/IO.hs
@@ -1,11 +1,41 @@
1{-#LANGUAGE RankNTypes#-} 1{-#LANGUAGE RankNTypes#-}
2-- | The operations exported here are a convenience, like the similar operations in
3-- @Data.Text.IO@ , or rather, @Data.Text.Lazy.IO@, since @Producer Text m r@ is
4-- 'effectful text' and something like the pipes equivalent of lazy Text.
5--
6-- * Like the functions in @Data.Text.IO@, they attempt to work with the system encoding.
7--
8-- * Like the functions in @Data.Text.IO@, they are slower than ByteString operations. Where
9-- you know what encoding you are working with, use @Pipes.ByteString@ and @Pipes.Text.Encoding@ instead,
10-- e.g. @view utf8 Bytes.stdin@ instead of @Text.stdin@
11--
12-- * Like the functions in @Data.Text.IO@ , they use Text exceptions.
13--
14-- Something like
15--
16-- > view utf8 . Bytes.fromHandle :: Handle -> Producer Text IO (Producer ByteString m ())
17--
18-- yields a stream of Text, and follows
19-- standard pipes protocols by reverting to (i.e. returning) the underlying byte stream
20-- upon reaching any decoding error. (See especially the pipes-binary package.)
21--
22-- By contrast, something like
23--
24-- > Text.fromHandle :: Handle -> Producer Text IO ()
25--
26-- supplies a stream of text returning '()', which is convenient for many tasks,
27-- but violates the pipes @pipes-binary@ approach to decoding errors and
28-- throws an exception of the kind characteristic of the @text@ library instead.
2 29
3module Pipes.Text.IO 30module Pipes.Text.IO
4 ( stdin 31 (
5 , stdout 32 -- * Producers
6 , fromHandle 33 fromHandle
7 , toHandle 34 , stdin
8 , readFile 35 , readFile
36 -- * Consumers
37 , toHandle
38 , stdout
9 , writeFile 39 , writeFile
10 ) where 40 ) where
11 41
@@ -22,15 +52,12 @@ import qualified Pipes.Safe as Safe
22import Pipes.Safe (MonadSafe(..), Base(..)) 52import Pipes.Safe (MonadSafe(..), Base(..))
23import Prelude hiding (readFile, writeFile) 53import Prelude hiding (readFile, writeFile)
24 54
25-- | Stream text from 'stdin'
26stdin :: MonadIO m => Producer Text m ()
27stdin = fromHandle IO.stdin
28{-# INLINE stdin #-}
29 55
30{-| Convert a 'IO.Handle' into a text stream using a text size 56{-| Convert a 'IO.Handle' into a text stream using a text size
31 determined by the good sense of the text library; note that this 57 determined by the good sense of the text library. Note with the remarks
32 is distinctly slower than @decideUtf8 (Pipes.ByteString.fromHandle h)@ 58 at the head of this module that this
33 but uses the system encoding and has other `Data.Text.IO` features 59 is slower than @view utf8 (Pipes.ByteString.fromHandle h)@
60 but uses the system encoding and has other nice @Data.Text.IO@ features
34-} 61-}
35 62
36fromHandle :: MonadIO m => IO.Handle -> Producer Text m () 63fromHandle :: MonadIO m => IO.Handle -> Producer Text m ()
@@ -41,6 +68,11 @@ fromHandle h = go where
41 go 68 go
42{-# INLINABLE fromHandle#-} 69{-# INLINABLE fromHandle#-}
43 70
71-- | Stream text from 'stdin'
72stdin :: MonadIO m => Producer Text m ()
73stdin = fromHandle IO.stdin
74{-# INLINE stdin #-}
75
44 76
45{-| Stream text from a file in the simple fashion of @Data.Text.IO@ 77{-| Stream text from a file in the simple fashion of @Data.Text.IO@
46 78