Data.Enumerator.Text

enumerator-0.4.20: Reliable, high-performance processing with left-fold enumerators

Copyright | 2010-2011 John Millikin
License | MIT
Maintainer | jmillikin@gmail.com
Portability | portable
Safe Haskell | None
Language | Haskell98

Data.Enumerator.Text

Contents

- IO
- List analogues
  - Folds
  - Maps
  - Accumulating maps
  - Infinite streams
  - Bounded streams
  - Dropping input
  - Consumers
  - Zipping
  - Unsorted
- Text codecs

Description

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

Synopsis

- enumHandle :: MonadIO m => Handle -> Enumerator Text m b
- enumFile :: FilePath -> Enumerator Text IO b
- iterHandle :: MonadIO m => Handle -> Iteratee Text m ()
- fold :: Monad m => (b -> Char -> b) -> b -> Iteratee Text m b
- foldM :: Monad m => (b -> Char -> m b) -> b -> Iteratee Text m b
- map :: Monad m => (Char -> Char) -> Enumeratee Text Text m b
- mapM :: Monad m => (Char -> m Char) -> Enumeratee Text Text m b
- mapM_ :: Monad m => (Char -> m ()) -> Iteratee Text m ()
- concatMap :: Monad m => (Char -> Text) -> Enumeratee Text Text m b
- concatMapM :: Monad m => (Char -> m Text) -> Enumeratee Text Text m b
- mapAccum :: Monad m => (s -> Char -> (s, Char)) -> s -> Enumeratee Text Text m b
- mapAccumM :: Monad m => (s -> Char -> m (s, Char)) -> s -> Enumeratee Text Text m b
- concatMapAccum :: Monad m => (s -> Char -> (s, Text)) -> s -> Enumeratee Text Text m b
- concatMapAccumM :: Monad m => (s -> Char -> m (s, Text)) -> s -> Enumeratee Text Text m b
- iterate :: Monad m => (Char -> Char) -> Char -> Enumerator Text m b
- iterateM :: Monad m => (Char -> m Char) -> Char -> Enumerator Text m b
- repeat :: Monad m => Char -> Enumerator Text m b
- repeatM :: Monad m => m Char -> Enumerator Text m b
- replicate :: Monad m => Integer -> Char -> Enumerator Text m b
- replicateM :: Monad m => Integer -> m Char -> Enumerator Text m b
- generateM :: Monad m => m (Maybe Char) -> Enumerator Text m b
- unfold :: Monad m => (s -> Maybe (Char, s)) -> s -> Enumerator Text m b
- unfoldM :: Monad m => (s -> m (Maybe (Char, s))) -> s -> Enumerator Text m b
- drop :: Monad m => Integer -> Iteratee Text m ()
- dropWhile :: Monad m => (Char -> Bool) -> Iteratee Text m ()
- filter :: Monad m => (Char -> Bool) -> Enumeratee Text Text m b
- filterM :: Monad m => (Char -> m Bool) -> Enumeratee Text Text m b
- head :: Monad m => Iteratee Text m (Maybe Char)
- head_ :: Monad m => Iteratee Text m Char
- take :: Monad m => Integer -> Iteratee Text m Text
- takeWhile :: Monad m => (Char -> Bool) -> Iteratee Text m Text
- consume :: Monad m => Iteratee Text m Text
- zip :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m (b1, b2)
- zip3 :: Monad m => Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m (b1, b2, b3)
- 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)
- 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)
- 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)
- 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)
- zipWith :: Monad m => (b1 -> b2 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m c
- zipWith3 :: Monad m => (b1 -> b2 -> b3 -> c) -> Iteratee Text m b1 -> Iteratee Text m b2 -> Iteratee Text m b3 -> Iteratee Text m c
- 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
- 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
- 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
- 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
- require :: Monad m => Integer -> Iteratee Text m ()
- isolate :: Monad m => Integer -> Enumeratee Text Text m b
- isolateWhile :: Monad m => (Char -> Bool) -> Enumeratee Text Text m b
- splitWhen :: Monad m => (Char -> Bool) -> Enumeratee Text Text m b
- lines :: Monad m => Enumeratee Text Text m b
- data Codec
- encode :: Monad m => Codec -> Enumeratee Text ByteString m b
- decode :: Monad m => Codec -> Enumeratee ByteString Text m b
- utf8 :: Codec
- utf16_le :: Codec
- utf16_be :: Codec
- utf32_le :: Codec
- utf32_be :: Codec
- ascii :: Codec
- iso8859_1 :: Codec

# 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