Data.Enumerator.Text

Character-oriented alternatives to Data.Enumerator.List. Note that the enumeratees in this module must unpack their inputs to work properly. If you do not need to handle leftover input on a char-by-char basis, the chunk-oriented versions will be much faster.

This module is intended to be imported qualified:

 import qualified Data.Enumerator.Text as ET

Since: 0.2

IO

enumHandle :: MonadIO m => Handle -> Enumerator Text m b

Read lines of text from a handle, and stream them to an Iteratee. If an exception occurs during file IO, enumeration will stop and Error will be returned. Exceptions from the iteratee are not caught.

The handle should be opened with an appropriate text encoding, and in ReadMode or ReadWriteMode.

This function may be significantly slower than using Data.Enumerator.Binary.enumHandle, due to the additional overhead of decoding input data to Unicode. Users who can depend on their input files being in a certain encoding (such as UTF8) are encouraged to use binary input and decode.

Changed in 0.4.18: Lines streamed from enumHandle and enumFile now include their trailing newline.

Since: 0.2

enumFile :: FilePath -> Enumerator Text IO b

Read lines of text from a file, and stream them to an Iteratee. If an exception occurs during file IO, enumeration will stop and Error will be returned. Exceptions from the iteratee are not caught.

The file will be opened in text mode, and will be closed when the Iteratee finishes.

This function may be significantly slower than using Data.Enumerator.Binary.enumFile, due to the additional overhead of decoding input data to Unicode. Users who can depend on their input files being in a certain encoding (such as UTF8) are encouraged to use binary input and decode.

Changed in 0.4.18: Lines streamed from enumHandle and enumFile now include their trailing newline.

Since: 0.2

iterHandle :: MonadIO m => Handle -> Iteratee Text m ()

Read text from a stream and write it to a handle. If an exception occurs during file IO, enumeration will stop and Error will be returned.

The handle should be opened with an appropriate text encoding, and in WriteMode or ReadWriteMode.

Since: 0.2

List analogues

Folds

fold :: Monad m => (b -> Char -> b) -> b -> Iteratee Text m b

Consume the entire input stream with a strict left fold, one character at a time.

Since: 0.4.8

foldM :: Monad m => (b -> Char -> m b) -> b -> Iteratee Text m b

Consume the entire input stream with a strict monadic left fold, one character at a time.

Since: 0.4.8

Maps

map :: Monad m => (Char -> Char) -> Enumeratee Text Text m b

map f applies f to each input character and feeds the resulting outputs to the inner iteratee.

Since: 0.4.8

mapM :: Monad m => (Char -> m Char) -> Enumeratee Text Text m b

mapM f applies f to each input character and feeds the resulting outputs to the inner iteratee.

Since: 0.4.8

mapM_ :: Monad m => (Char -> m ()) -> Iteratee Text m ()

mapM_ f applies f to each input character, and discards the results.

Since: 0.4.11

concatMap :: Monad m => (Char -> Text) -> Enumeratee Text Text m b

concatMap f applies f to each input character and feeds the resulting outputs to the inner iteratee.

Since: 0.4.8

concatMapM :: Monad m => (Char -> m Text) -> Enumeratee Text Text m b

concatMapM f applies f to each input character and feeds the resulting outputs to the inner iteratee.

Since: 0.4.8

Accumulating maps

mapAccum :: Monad m => (s -> Char -> (s, Char)) -> s -> Enumeratee Text Text m b

Similar to map, but with a stateful step function.

Since: 0.4.9

mapAccumM :: Monad m => (s -> Char -> m (s, Char)) -> s -> Enumeratee Text Text m b

Similar to mapM, but with a stateful step function.

Since: 0.4.9

concatMapAccum :: Monad m => (s -> Char -> (s, Text)) -> s -> Enumeratee Text Text m b

Similar to concatMap, but with a stateful step function.

Since: 0.4.11

concatMapAccumM :: Monad m => (s -> Char -> m (s, Text)) -> s -> Enumeratee Text Text m b

Similar to concatMapM, but with a stateful step function.

Since: 0.4.11

Infinite streams

iterate :: Monad m => (Char -> Char) -> Char -> Enumerator Text m b

iterate f x enumerates an infinite stream of repeated applications of f to x.

Analogous to iterate.

Since: 0.4.8

iterateM :: Monad m => (Char -> m Char) -> Char -> Enumerator Text m b

Similar to iterate, except the iteration function is monadic.

Since: 0.4.8

repeat :: Monad m => Char -> Enumerator Text m b

Enumerates an infinite stream of a single character.

Analogous to repeat.

Since: 0.4.8

repeatM :: Monad m => m Char -> Enumerator Text m b

Enumerates an infinite stream of characters. Each character is computed by the underlying monad.

Since: 0.4.8

Bounded streams

replicate :: Monad m => Integer -> Char -> Enumerator Text m b

replicate n x enumerates a stream containing n copies of x.

Since: 0.4.8

replicateM :: Monad m => Integer -> m Char -> Enumerator Text m b

replicateM n m_x enumerates a stream of n characters, with each character computed by m_x.

Since: 0.4.8

generateM :: Monad m => m (Maybe Char) -> Enumerator Text m b

Like repeatM, except the computation may terminate the stream by returning Nothing.

Since: 0.4.8

unfold :: Monad m => (s -> Maybe (Char, s)) -> s -> Enumerator Text m b

Enumerates a stream of characters by repeatedly applying a function to some state.

Similar to iterate.

Since: 0.4.8

unfoldM :: Monad m => (s -> m (Maybe (Char, s))) -> s -> Enumerator Text m b

Enumerates a stream of characters by repeatedly applying a computation to some state.

Similar to iterateM.

Since: 0.4.8

Dropping input

drop :: Monad m => Integer -> Iteratee Text m ()

drop n ignores n characters of input from the stream.

Since: 0.4.5

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

dropWhile p ignores input from the stream until the first character which does not match the predicate.

Since: 0.4.5

filter :: Monad m => (Char -> Bool) -> Enumeratee Text Text m b

Applies a predicate to the stream. The inner iteratee only receives characters for which the predicate is True.

Since: 0.4.8

filterM :: Monad m => (Char -> m Bool) -> Enumeratee Text Text m b

Applies a monadic predicate to the stream. The inner iteratee only receives characters for which the predicate returns True.

Since: 0.4.8

Consumers

head :: Monad m => Iteratee Text m (Maybe Char)

Get the next character from the stream, or Nothing if the stream has ended.

Since: 0.4.5

head_ :: Monad m => Iteratee Text m Char

Get the next element from the stream, or raise an error if the stream has ended.

Since: 0.4.14

take :: Monad m => Integer -> Iteratee Text m Text

take n extracts the next n characters from the stream, as a lazy Text.

Since: 0.4.5

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

takeWhile p extracts input from the stream until the first character which does not match the predicate.

Since: 0.4.5

consume :: Monad m => Iteratee Text m Text

consume = takeWhile (const True)

Since: 0.4.5

Zipping

zip :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m (b1, b2)

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee.

Analogous to zip.

Since: 0.4.14

zip3 :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m (b1, b2, b3)

Pass input from a stream through three iteratees at once. Excess input is yielded if it was not consumed by any iteratee.

Analogous to zip3.

Since: 0.4.14

zip4 :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m (b1, b2, b3, b4)

Pass input from a stream through four iteratees at once. Excess input is yielded if it was not consumed by any iteratee.

Analogous to zip4.

Since: 0.4.14

zip5 :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m b5 -> Iteratee Text m (b1, b2, b3, b4, b5)

Pass input from a stream through five iteratees at once. Excess input is yielded if it was not consumed by any iteratee.

Analogous to zip5.

Since: 0.4.14

zip6 :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m b5 -> Iteratee Text m b6 -> Iteratee Text m (b1, b2, b3, b4, b5, b6)

Pass input from a stream through six iteratees at once. Excess input is yielded if it was not consumed by any iteratee.

Analogous to zip6.

Since: 0.4.14

zip7 :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m b5 -> Iteratee Text m b6 -> Iteratee Text m b7 -> Iteratee Text m (b1, b2, b3, b4, b5, b6, b7)

Pass input from a stream through seven iteratees at once. Excess input is yielded if it was not consumed by any iteratee.

Analogous to zip7.

Since: 0.4.14

zipWith :: Monad m => (b1 -> b2 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m c

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee. Output from the iteratees is combined with a user-provided function.

Analogous to zipWith.

Since: 0.4.14

zipWith3 :: Monad m => (b1 -> b2 -> b3 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m c

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee. Output from the iteratees is combined with a user-provided function.

Analogous to zipWith3.

Since: 0.4.14

zipWith4 :: Monad m => (b1 -> b2 -> b3 -> b4 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m c

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee. Output from the iteratees is combined with a user-provided function.

Analogous to zipWith4.

Since: 0.4.14

zipWith5 :: Monad m => (b1 -> b2 -> b3 -> b4 -> b5 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m b5 -> Iteratee Text m c

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee. Output from the iteratees is combined with a user-provided function.

Analogous to zipWith5.

Since: 0.4.14

zipWith6 :: Monad m => (b1 -> b2 -> b3 -> b4 -> b5 -> b6 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m b5 -> Iteratee Text m b6 -> Iteratee Text m c

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee. Output from the iteratees is combined with a user-provided function.

Analogous to zipWith6.

Since: 0.4.14

zipWith7 :: Monad m => (b1 -> b2 -> b3 -> b4 -> b5 -> b6 -> b7 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m b4 -> Iteratee Text m b5 -> Iteratee Text m b6 -> Iteratee Text m b7 -> Iteratee Text m c

Pass input from a stream through two iteratees at once. Excess input is yielded if it was not consumed by either iteratee. Output from the iteratees is combined with a user-provided function.

Analogous to zipWith7.

Since: 0.4.14

Unsorted

require :: Monad m => Integer -> Iteratee Text m ()

require n buffers input until at least n characters are available, or throws an error if the stream ends early.

Since: 0.4.5

isolate :: Monad m => Integer -> Enumeratee Text Text m b

isolate n reads at most n characters from the stream, and passes them to its iteratee. If the iteratee finishes early, characters continue to be consumed from the outer stream until n have been consumed.

Since: 0.4.5

isolateWhile :: Monad m => (Char -> Bool) -> Enumeratee Text Text m b

isolateWhile p reads characters from the stream until p is false, and passes them to its iteratee. If the iteratee finishes early, characters continue to be consumed from the outer stream until p is false.

Since: 0.4.16

splitWhen :: Monad m => (Char -> Bool) -> Enumeratee Text Text m b

Split on characters satisfying a given predicate.

Since: 0.4.8

lines :: Monad m => Enumeratee Text Text m b

lines = splitWhen (== '\n')

Since: 0.4.8

Text codecs

data Codec

Instances

Show Codec

encode :: Monad m => Codec -> Enumeratee Text ByteString m b

Convert text into bytes, using the provided codec. If the codec is not capable of representing an input character, an error will be thrown.

Since: 0.2

decode :: Monad m => Codec -> Enumeratee ByteString Text m b

Convert bytes into text, using the provided codec. If the codec is not capable of decoding an input byte sequence, an error will be thrown.

Since: 0.2

utf8 :: Codec

utf16_le :: Codec

utf16_be :: Codec

utf32_le :: Codec

utf32_be :: Codec

ascii :: Codec

iso8859_1 :: Codec