aboutsummaryrefslogtreecommitdiffhomepage
path: root/Pipes
diff options
context:
space:
mode:
Diffstat (limited to 'Pipes')
-rw-r--r--Pipes/Text.hs49
1 files changed, 32 insertions, 17 deletions
diff --git a/Pipes/Text.hs b/Pipes/Text.hs
index e027d00..254b76a 100644
--- a/Pipes/Text.hs
+++ b/Pipes/Text.hs
@@ -2,9 +2,24 @@
2 2
3 3
4module Pipes.Text ( 4module Pipes.Text (
5 -- * Introduction 5 -- * Effectful Text
6 -- $intro 6 -- $intro
7 7
8 -- * Lenses
9 -- $lenses
10
11 -- ** @view@ \/ @(^.)@
12 -- $view
13
14 -- ** @over@ \/ @(%~)@
15 -- $over
16
17 -- ** @zoom@
18 -- $zoom
19
20 -- * Special types: @Producer Text m (Producer Text m r)@ and @FreeT (Producer Text m) m r@
21 -- $special
22
8 -- * Producers 23 -- * Producers
9 fromLazy 24 fromLazy
10 25
@@ -134,9 +149,6 @@ import Prelude hiding (
134 writeFile ) 149 writeFile )
135 150
136{- $intro 151{- $intro
137
138 * /I. Effectful Text/
139
140 This package provides @pipes@ utilities for /text streams/ or /character streams/, 152 This package provides @pipes@ utilities for /text streams/ or /character streams/,
141 realized as streams of 'Text' chunks. The individual chunks are uniformly /strict/, 153 realized as streams of 'Text' chunks. The individual chunks are uniformly /strict/,
142 and thus you will generally want @Data.Text@ in scope. But the type 154 and thus you will generally want @Data.Text@ in scope. But the type
@@ -178,8 +190,8 @@ import Prelude hiding (
178 The above program will never bring more than one chunk of text (~ 32 KB) into 190 The above program will never bring more than one chunk of text (~ 32 KB) into
179 memory, no matter how long the lines are. 191 memory, no matter how long the lines are.
180 192
181 * /II. Lenses/ 193-}
182 194{- $lenses
183 As this example shows, one superficial difference from @Data.Text.Lazy@ 195 As this example shows, one superficial difference from @Data.Text.Lazy@
184 is that many of the operations, like 'lines', are \'lensified\'; this has a 196 is that many of the operations, like 'lines', are \'lensified\'; this has a
185 number of advantages (where it is possible); in particular it facilitates their 197 number of advantages (where it is possible); in particular it facilitates their
@@ -197,7 +209,7 @@ import Prelude hiding (
197 209
198 > view (splitAt 17) producer 210 > view (splitAt 17) producer
199 211
200 or 212 or equivalently
201 213
202 > producer ^. splitAt 17 214 > producer ^. splitAt 17
203 215
@@ -216,8 +228,10 @@ import Prelude hiding (
216 our lenses, are @view@ \/ @(^.)@), @over@ \/ @(%~)@ , and @zoom@. 228 our lenses, are @view@ \/ @(^.)@), @over@ \/ @(%~)@ , and @zoom@.
217 229
218 One need only keep in mind that if @l@ is a @Lens' a b@, then: 230 One need only keep in mind that if @l@ is a @Lens' a b@, then:
219 231
220 - @view l@ is a function @a -> b@ . Thus @view l a@ (also written @a ^. l@ ) 232-}
233{- $view
234 @view l@ is a function @a -> b@ . Thus @view l a@ (also written @a ^. l@ )
221 is the corresponding @b@; as was said above, this function will be exactly the 235 is the corresponding @b@; as was said above, this function will be exactly the
222 function you think it is, given its name. Thus to uppercase the first n characters 236 function you think it is, given its name. Thus to uppercase the first n characters
223 of a Producer, leaving the rest the same, we could write: 237 of a Producer, leaving the rest the same, we could write:
@@ -225,9 +239,9 @@ import Prelude hiding (
225 239
226 > upper n p = do p' <- p ^. Text.splitAt n >-> Text.toUpper 240 > upper n p = do p' <- p ^. Text.splitAt n >-> Text.toUpper
227 > p' 241 > p'
228 242-}
229 243{- $over
230 - @over l@ is a function @(b -> b) -> a -> a@. Thus, given a function that modifies 244 @over l@ is a function @(b -> b) -> a -> a@. Thus, given a function that modifies
231 @b@s, the lens lets us modify an @a@ by applying @f :: b -> b@ to 245 @b@s, the lens lets us modify an @a@ by applying @f :: b -> b@ to
232 the @b@ that we can \"see\" through the lens. So @over l f :: a -> a@ 246 the @b@ that we can \"see\" through the lens. So @over l f :: a -> a@
233 (it can also be written @l %~ f@). 247 (it can also be written @l %~ f@).
@@ -237,8 +251,10 @@ import Prelude hiding (
237 > stripLines = Text.lines %~ maps (>-> Text.stripStart) 251 > stripLines = Text.lines %~ maps (>-> Text.stripStart)
238 > stripLines = over Text.lines (maps (>-> Text.stripStart)) 252 > stripLines = over Text.lines (maps (>-> Text.stripStart))
239 > upper n = Text.splitAt n %~ (>-> Text.toUpper) 253 > upper n = Text.splitAt n %~ (>-> Text.toUpper)
240 254
241 - @zoom l@, finally, is a function from a @Parser b m r@ 255-}
256{- $zoom
257 @zoom l@, finally, is a function from a @Parser b m r@
242 to a @Parser a m r@ (or more generally a @StateT (Producer b m x) m r@). 258 to a @Parser a m r@ (or more generally a @StateT (Producer b m x) m r@).
243 Its use is easiest to see with an decoding lens like 'utf8', which 259 Its use is easiest to see with an decoding lens like 'utf8', which
244 \"sees\" a Text producer hidden inside a ByteString producer: 260 \"sees\" a Text producer hidden inside a ByteString producer:
@@ -278,9 +294,8 @@ import Prelude hiding (
278 in <http://hackage.haskell.org/package/pipes-parse-3.0.1/docs/Pipes-Parse-Tutorial.html Pipes.Parse.Tutorial> 294 in <http://hackage.haskell.org/package/pipes-parse-3.0.1/docs/Pipes-Parse-Tutorial.html Pipes.Parse.Tutorial>
279 and to some extent in the @Pipes.Text.Encoding@ module here. 295 and to some extent in the @Pipes.Text.Encoding@ module here.
280 296
281 297-}
282 * /III. Special types:/ @Producer Text m (Producer Text m r)@ /and/ @FreeT (Producer Text m) m r@ 298{- $special
283
284 These simple 'lines' examples reveal a more important difference from @Data.Text.Lazy@ . 299 These simple 'lines' examples reveal a more important difference from @Data.Text.Lazy@ .
285 This is in the types that are most closely associated with our central text type, 300 This is in the types that are most closely associated with our central text type,
286 @Producer Text m r@. In @Data.Text@ and @Data.Text.Lazy@ we find functions like 301 @Producer Text m r@. In @Data.Text@ and @Data.Text.Lazy@ we find functions like