diff options
Diffstat (limited to 'Pipes/Text/IO.hs')
-rw-r--r-- | Pipes/Text/IO.hs | 104 |
1 files changed, 77 insertions, 27 deletions
diff --git a/Pipes/Text/IO.hs b/Pipes/Text/IO.hs index 92500c3..45a1467 100644 --- a/Pipes/Text/IO.hs +++ b/Pipes/Text/IO.hs | |||
@@ -1,34 +1,14 @@ | |||
1 | {-#LANGUAGE RankNTypes#-} | 1 | {-#LANGUAGE RankNTypes#-} |
2 | -- | The operations exported here are a convenience, like the similar operations in | 2 | |
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. | ||
29 | 3 | ||
30 | module Pipes.Text.IO | 4 | module Pipes.Text.IO |
31 | ( | 5 | ( |
6 | -- * Text IO | ||
7 | -- $textio | ||
8 | |||
9 | -- * Caveats | ||
10 | -- $caveats | ||
11 | |||
32 | -- * Producers | 12 | -- * Producers |
33 | fromHandle | 13 | fromHandle |
34 | , stdin | 14 | , stdin |
@@ -52,6 +32,76 @@ import qualified Pipes.Safe as Safe | |||
52 | import Pipes.Safe (MonadSafe(..), Base(..)) | 32 | import Pipes.Safe (MonadSafe(..), Base(..)) |
53 | import Prelude hiding (readFile, writeFile) | 33 | import Prelude hiding (readFile, writeFile) |
54 | 34 | ||
35 | {- $textio | ||
36 | Where pipes IO replaces lazy IO, @Producer Text m r@ replaces lazy 'Text'. | ||
37 | This module exports some convenient functions for producing and consuming | ||
38 | pipes 'Text' in IO, with caveats described below. The main points are as in | ||
39 | <https://hackage.haskell.org/package/pipes-bytestring-1.0.0/docs/Pipes-ByteString.html @Pipes.ByteString@> | ||
40 | |||
41 | An 'IO.Handle' can be associated with a 'Producer' or 'Consumer' according as it is read or written to. | ||
42 | |||
43 | To stream to or from 'IO.Handle's, one can use 'fromHandle' or 'toHandle'. For | ||
44 | example, the following program copies a document from one file to another: | ||
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 | 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 | {- $caveats | ||
74 | |||
75 | The operations exported here are a convenience, like the similar operations in | ||
76 | @Data.Text.IO@ (or rather, @Data.Text.Lazy.IO@, since, again, @Producer Text m r@ is | ||
77 | 'effectful text' and something like the pipes equivalent of lazy Text.) | ||
78 | |||
79 | * Like the functions in @Data.Text.IO@, they attempt to work with the system encoding. | ||
80 | |||
81 | * Like the functions in @Data.Text.IO@, they are slower than ByteString operations. Where | ||
82 | you know what encoding you are working with, use @Pipes.ByteString@ and @Pipes.Text.Encoding@ instead, | ||
83 | e.g. @view utf8 Bytes.stdin@ instead of @Text.stdin@ | ||
84 | |||
85 | * Like the functions in @Data.Text.IO@ , they use Text exceptions. | ||
86 | |||
87 | Something like | ||
88 | |||
89 | > view utf8 . Bytes.fromHandle :: Handle -> Producer Text IO (Producer ByteString m ()) | ||
90 | |||
91 | yields a stream of Text, and follows | ||
92 | standard pipes protocols by reverting to (i.e. returning) the underlying byte stream | ||
93 | upon reaching any decoding error. (See especially the pipes-binary package.) | ||
94 | |||
95 | By contrast, something like | ||
96 | |||
97 | > Text.fromHandle :: Handle -> Producer Text IO () | ||
98 | |||
99 | supplies a stream of text returning '()', which is convenient for many tasks, | ||
100 | but violates the pipes @pipes-binary@ approach to decoding errors and | ||
101 | throws an exception of the kind characteristic of the @text@ library instead. | ||
102 | |||
103 | |||
104 | -} | ||
55 | 105 | ||
56 | {-| Convert a 'IO.Handle' into a text stream using a text size | 106 | {-| Convert a 'IO.Handle' into a text stream using a text size |
57 | determined by the good sense of the text library. Note with the remarks | 107 | determined by the good sense of the text library. Note with the remarks |