Safe Haskell | Trustworthy |
---|

This module provides `pipes`

utilities for "text streams", which are
streams of `Text`

chunks. The individual chunks are uniformly `strict`

, but
a `Producer`

can be converted to and from lazy `Text`

s, though this is generally
unwise. Where pipes IO replaces lazy IO, 'Producer Text m r' replaces lazy `Text`

.
An `Handle`

can be associated with a `Producer`

or `Consumer`

according as it is read or written to.

To stream to or from `Handle`

s, one can use `fromHandle`

or `toHandle`

. For
example, the following program copies a document from one file to another:

import Pipes import qualified Pipes.Text as Text import qualified Pipes.Text.IO as Text import System.IO main = withFile "inFile.txt" ReadMode $ \hIn -> withFile "outFile.txt" WriteMode $ \hOut -> runEffect $ Text.fromHandle hIn >-> Text.toHandle hOut

To stream from files, the following is perhaps more Prelude-like (note that it uses Pipes.Safe):

import Pipes import qualified Pipes.Text as Text import qualified Pipes.Text.IO as Text import Pipes.Safe main = runSafeT $ runEffect $ Text.readFile "inFile.txt" >-> Text.writeFile "outFile.txt"

You can stream to and from `stdin`

and `stdout`

using the predefined `stdin`

and `stdout`

pipes, as with the following "echo" program:

main = runEffect $ Text.stdin >-> Text.stdout

You can also translate pure lazy `Text`

s to and from pipes:

main = runEffect $ Text.fromLazy (TL.pack "Hello, world!\n") >-> Text.stdout

In addition, this module provides many functions equivalent to lazy
`Text`

functions so that you can transform or fold text streams. For
example, to stream only the first three lines of `stdin`

to `stdout`

you
might write:

import Pipes import qualified Pipes.Text as Text import qualified Pipes.Parse as Parse main = runEffect $ takeLines 3 Text.stdin >-> Text.stdout where takeLines n = Text.unlines . Parse.takeFree n . Text.lines

The above program will never bring more than one chunk of text (~ 32 KB) into memory, no matter how long the lines are.

Note that functions in this library are designed to operate on streams that
are insensitive to text boundaries. This means that they may freely split
text into smaller texts, *discard empty texts*. However, apart from the
special case of `concatMap`

, they will *never concatenate texts* in order
to provide strict upper bounds on memory usage -- with the single exception of `concatMap`

.

- fromLazy :: Monad m => Text -> Producer' Text m ()
- map :: Monad m => (Char -> Char) -> Pipe Text Text m r
- concatMap :: Monad m => (Char -> Text) -> Pipe Text Text m r
- take :: (Monad m, Integral a) => a -> Pipe Text Text m ()
- drop :: (Monad m, Integral a) => a -> Pipe Text Text m r
- takeWhile :: Monad m => (Char -> Bool) -> Pipe Text Text m ()
- dropWhile :: Monad m => (Char -> Bool) -> Pipe Text Text m r
- filter :: Monad m => (Char -> Bool) -> Pipe Text Text m r
- scan :: Monad m => (Char -> Char -> Char) -> Char -> Pipe Text Text m r
- pack :: Monad m => Pipe String Text m r
- unpack :: Monad m => Pipe Text String m r
- toCaseFold :: Monad m => Pipe Text Text m ()
- toLower :: Monad m => Pipe Text Text m ()
- toUpper :: Monad m => Pipe Text Text m ()
- stripStart :: Monad m => Pipe Text Text m r
- toLazy :: Producer Text Identity () -> Text
- toLazyM :: Monad m => Producer Text m () -> m Text
- foldChars :: Monad m => (x -> Char -> x) -> x -> (x -> r) -> Producer Text m () -> m r
- head :: Monad m => Producer Text m () -> m (Maybe Char)
- last :: Monad m => Producer Text m () -> m (Maybe Char)
- null :: Monad m => Producer Text m () -> m Bool
- length :: (Monad m, Num n) => Producer Text m () -> m n
- any :: Monad m => (Char -> Bool) -> Producer Text m () -> m Bool
- all :: Monad m => (Char -> Bool) -> Producer Text m () -> m Bool
- maximum :: Monad m => Producer Text m () -> m (Maybe Char)
- minimum :: Monad m => Producer Text m () -> m (Maybe Char)
- find :: Monad m => (Char -> Bool) -> Producer Text m () -> m (Maybe Char)
- index :: (Monad m, Integral a) => a -> Producer Text m () -> m (Maybe Char)
- count :: (Monad m, Num n) => Text -> Producer Text m () -> m n
- nextChar :: Monad m => Producer Text m r -> m (Either r (Char, Producer Text m r))
- drawChar :: Monad m => Parser Text m (Maybe Char)
- unDrawChar :: Monad m => Char -> Parser Text m ()
- peekChar :: Monad m => Parser Text m (Maybe Char)
- isEndOfChars :: Monad m => Parser Text m Bool
- splitAt :: (Monad m, Integral n) => n -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- span :: Monad m => (Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- break :: Monad m => (Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- groupBy :: Monad m => (Char -> Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- group :: Monad m => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- word :: Monad m => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- line :: Monad m => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))
- chunksOf :: (Monad m, Integral n) => n -> Lens' (Producer Text m r) (FreeT (Producer Text m) m r)
- splitsWith :: Monad m => (Char -> Bool) -> Producer Text m r -> FreeT (Producer Text m) m r
- splits :: Monad m => Char -> Lens' (Producer Text m r) (FreeT (Producer Text m) m r)
- groupsBy :: Monad m => (Char -> Char -> Bool) -> Lens' (Producer Text m x) (FreeT (Producer Text m) m x)
- groups :: Monad m => Lens' (Producer Text m x) (FreeT (Producer Text m) m x)
- lines :: Monad m => Iso' (Producer Text m r) (FreeT (Producer Text m) m r)
- words :: Monad m => Iso' (Producer Text m r) (FreeT (Producer Text m) m r)
- intersperse :: Monad m => Char -> Producer Text m r -> Producer Text m r
- packChars :: Monad m => Iso' (Producer Char m x) (Producer Text m x)
- intercalate :: Monad m => Producer Text m () -> FreeT (Producer Text m) m r -> Producer Text m r
- unlines :: Monad m => FreeT (Producer Text m) m r -> Producer Text m r
- unwords :: Monad m => FreeT (Producer Text m) m r -> Producer Text m r
- type Lens' a b = forall f. Functor f => (b -> f b) -> a -> f a
- type Iso' a b = forall f p. (Functor f, Profunctor p) => p b (f b) -> p a (f a)
- module Data.ByteString
- module Data.Text
- module Data.Profunctor
- module Pipes.Parse
- module Pipes.Group

# Producers

# Pipes

map :: Monad m => (Char -> Char) -> Pipe Text Text m rSource

Apply a transformation to each `Char`

in the stream

concatMap :: Monad m => (Char -> Text) -> Pipe Text Text m rSource

Map a function over the characters of a text stream and concatenate the results

take :: (Monad m, Integral a) => a -> Pipe Text Text m ()Source

`(take n)`

only allows `n`

individual characters to pass;
contrast `Pipes.Prelude.take`

which would let `n`

chunks pass.

takeWhile :: Monad m => (Char -> Bool) -> Pipe Text Text m ()Source

Take characters until they fail the predicate

dropWhile :: Monad m => (Char -> Bool) -> Pipe Text Text m rSource

Drop characters until they fail the predicate

filter :: Monad m => (Char -> Bool) -> Pipe Text Text m rSource

Only allows `Char`

s to pass if they satisfy the predicate

scan :: Monad m => (Char -> Char -> Char) -> Char -> Pipe Text Text m rSource

Strict left scan over the characters

stripStart :: Monad m => Pipe Text Text m rSource

Remove leading white space from an incoming succession of `Text`

s

# Folds

foldChars :: Monad m => (x -> Char -> x) -> x -> (x -> r) -> Producer Text m () -> m rSource

Reduce the text stream using a strict left fold over characters

length :: (Monad m, Num n) => Producer Text m () -> m nSource

Count the number of characters in the stream

maximum :: Monad m => Producer Text m () -> m (Maybe Char)Source

Return the maximum `Char`

within a text stream

minimum :: Monad m => Producer Text m () -> m (Maybe Char)Source

Return the minimum `Char`

within a text stream (surely very useful!)

find :: Monad m => (Char -> Bool) -> Producer Text m () -> m (Maybe Char)Source

Find the first element in the stream that matches the predicate

index :: (Monad m, Integral a) => a -> Producer Text m () -> m (Maybe Char)Source

Index into a text stream

count :: (Monad m, Num n) => Text -> Producer Text m () -> m nSource

Store a tally of how many segments match the given `Text`

# Primitive Character Parsers

peekChar :: Monad m => Parser Text m (Maybe Char)Source

`peekChar`

checks the first `Char`

in the stream, but uses `unDrawChar`

to
push the `Char`

back

peekChar = do x <- drawChar case x of Left _ -> return () Right c -> unDrawChar c return x

isEndOfChars :: Monad m => Parser Text m BoolSource

Check if the underlying `Producer`

has no more characters

Note that this will skip over empty `Text`

chunks, unlike
`isEndOfInput`

from `pipes-parse`

, which would consider
an empty `Text`

a valid bit of input.

isEndOfChars = liftM isLeft peekChar

# Parsing Lenses

splitAt :: (Monad m, Integral n) => n -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))Source

Splits a `Producer`

after the given number of characters

span :: Monad m => (Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))Source

Split a text stream in two, producing the longest consecutive group of characters that satisfies the predicate and returning the rest

break :: Monad m => (Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))Source

Split a text stream in two, producing the longest consecutive group of characters that don't satisfy the predicate

groupBy :: Monad m => (Char -> Char -> Bool) -> Lens' (Producer Text m r) (Producer Text m (Producer Text m r))Source

Improper lens that splits after the first group of equivalent Chars, as defined by the given equivalence relation

group :: Monad m => Lens' (Producer Text m r) (Producer Text m (Producer Text m r))Source

Improper lens that splits after the first succession of identical `Char`

s

# FreeT Splitters

chunksOf :: (Monad m, Integral n) => n -> Lens' (Producer Text m r) (FreeT (Producer Text m) m r)Source

Split a text stream into `FreeT`

-delimited text streams of fixed size

splitsWith :: Monad m => (Char -> Bool) -> Producer Text m r -> FreeT (Producer Text m) m rSource

Split a text stream into sub-streams delimited by characters that satisfy the predicate

splits :: Monad m => Char -> Lens' (Producer Text m r) (FreeT (Producer Text m) m r)Source

Split a text stream using the given `Char`

as the delimiter

groupsBy :: Monad m => (Char -> Char -> Bool) -> Lens' (Producer Text m x) (FreeT (Producer Text m) m x)Source

lines :: Monad m => Iso' (Producer Text m r) (FreeT (Producer Text m) m r)Source

Split a text stream into `FreeT`

-delimited lines

words :: Monad m => Iso' (Producer Text m r) (FreeT (Producer Text m) m r)Source

Split a text stream into `FreeT`

-delimited words

# Transformations

packChars :: Monad m => Iso' (Producer Char m x) (Producer Text m x)Source

Improper isomorphism between a `Producer`

of `ByteString`

s and `Word8`

s

# Joiners

intercalate :: Monad m => Producer Text m () -> FreeT (Producer Text m) m r -> Producer Text m rSource

`intercalate`

concatenates the `FreeT`

-delimited text streams after
interspersing a text stream in between them

unlines :: Monad m => FreeT (Producer Text m) m r -> Producer Text m rSource

Join `FreeT`

-delimited lines into a text stream

unwords :: Monad m => FreeT (Producer Text m) m r -> Producer Text m rSource

Join `FreeT`

-delimited words into a text stream

# Re-exports

type Iso' a b = forall f p. (Functor f, Profunctor p) => p b (f b) -> p a (f a)Source

module Data.ByteString

module Data.Text

module Data.Profunctor

module Pipes.Parse

module Pipes.Group