The primary data type for this library; an iteratee consumes chunks of input from a stream until it either yields a value or encounters an error.

Compatibility note: Iteratee will become abstract in enumerator_0.5. If you depend on internal implementation details, please import Data.Enumerator.Internal.

Enumerators are sources of data, to be consumed by iteratees. Enumerators typically read from an external source (parser, handle, random generator, etc), then feed chunks into an tteratee until:

• The input source runs out of data.
• The iteratee yields a result value.
• The iteratee throws an exception.

An enumeratee acts as a stream adapter; place one between an enumerator and an iteratee, and it changes the type or contents of the input stream.

Most users will want to combine enumerators, enumeratees, and iteratees using the stream combinators joinI and joinE, or their operator aliases (=$) and ($=). These combinators are used to manage how left-over input is passed between elements of the data processing pipeline.

Run an iteratee until it finishes, and return either the final value (if it succeeded) or the error (if it failed).

 import Data.Enumerator
 import Data.Enumerator.List as EL

 main = do
     result <- run (EL.iterate succ 'A' $$ EL.take 5)
     case result of
         Left exc -> putStrLn ("Got an exception: " ++ show exc)
         Right chars -> putStrLn ("Got characters: " ++ show chars)

Like run, except errors are converted to exceptions and thrown. Primarily useful for small scripts or other simple cases.

 import Data.Enumerator
 import Data.Enumerator.List as EL

 main = do
     chars <- run_ (EL.iterate succ 'A' $$ EL.take 5)
     putStrLn ("Got characters: " ++ show chars)

Since: 0.4.1

The most primitive stream operator. iter >>== enum returns a new iteratee which will read from enum before continuing.

(==<<) = flip (>>==)

($$) = (==<<)

This is somewhat easier to read when constructing an iteratee from many processing stages. You can treat it like ($), and read the data flow from left to right.

Since: 0.1.1

(>==>) enum1 enum2 step = enum1 step >>== enum2

The moral equivalent of (>=>) for iteratees.

Since: 0.1.1

(<==<) = flip (>==>)

Since: 0.1.1

“Wraps” an iteratee inner in an enumeratee wrapper. The resulting iteratee will consume wrapper’s input type and yield inner’s output type.

Note: if the inner iteratee yields leftover input when it finishes, that extra will be discarded.

As an example, consider an iteratee that converts a stream of UTF8-encoded bytes into a single Text:

 consumeUTF8 :: Monad m => Iteratee ByteString m Text

It could be written with either joinI or (=$):

 import Data.Enumerator.Text as ET

 consumeUTF8 = joinI (decode utf8 $$ ET.consume)
 consumeUTF8 = decode utf8 =$ ET.consume

Since: 0.4.9

“Wraps” an enumerator inner in an enumeratee wrapper. The resulting enumerator will generate wrapper’s output type.

As an example, consider an enumerator that yields line character counts for a text file (e.g. for source code readability checking):

 enumFileCounts :: FilePath -> Enumerator Int IO b

It could be written with either joinE or ($=):

 import Data.Text as T
 import Data.Enumerator.List as EL
 import Data.Enumerator.Text as ET

 enumFileCounts path = joinE (enumFile path) (EL.map T.length)
 enumFileCounts path = enumFile path $= EL.map T.length

Compatibility note: in version 0.4.15, the associativity of ($=) was changed from infixr 0 to infixl 1.

Since: 0.4.9

Composes two enumeratees.

Note that if the inner enumeratee yields left-over input, this will be discarded.

Example: converting bytes into lower-case text:

 import Data.ByteString
 import Data.Text
 import Data.Enumerator.List as EnumList
 import Data.Enumerator.Text

 decodeAndLower :: Monad m => Enumeratee ByteString Text m b
 decodeAndLower = decode utf8 =$= EnumList.map toLower

Since: 0.4.17

The moral equivalent of throwIO for iteratees.

Runs the iteratee, and calls an exception handler if an Error is returned. By handling errors within the enumerator library, and requiring all errors to be represented by SomeException, libraries with varying error types can be easily composed.

WARNING: Within the error handler, it is difficult or impossible to know how much input the original iteratee has consumed. Users are strongly advised to wrap all uses of catchError with an appropriate isolation enumeratee, such as Data.Enumerator.List.isolate or Data.Enumerator.Binary.isolate, which will handle input framing even in the face of unexpected errors.

Since: 0.1.1

Compose a list of Enumerators using (>==>).

“Wraps” an iteratee inner in an enumeratee wrapper. The resulting iteratee will consume wrapper’s input type and yield inner’s output type.

See the documentation for (=$).

joinI (enum $$ iter) = enum =$ iter

“Wraps” an enumerator inner in an enumeratee wrapper. The resulting enumerator will generate wrapper’s output type.

See the documentation for ($=).

joinE enum enee = enum $= enee

Since: 0.4.5

Feeds outer input elements into the provided iteratee until it yields an inner input, passes that to the inner iteratee, and then loops.

Check whether a stream has reached EOF. Note that if the stream is not at EOF, isEOF may cause data to be read from the enumerator.

Try to run an IO computation. If it throws an exception, the exception is caught and passed to throwError.

Since: 0.4.9

Lift an Iteratee onto a monad transformer, re-wrapping its inner monadic values.

Since: 0.1.1

Print chunks as they're received from the enumerator, optionally printing empty chunks.

enumList n xs enumerates xs as a stream, passing n inputs per chunk. This is primarily useful for testing, debugging, and REPL exploration.

Compatibility note: In version 0.5, enumList will be changed to the type:

 enumList :: Monad m => [a] -> Enumerator a m b

enumLists xs enumerates xs as a stream, where each element is a separate chunk. This is primarily useful for testing and debugging.

Since: 0.4.15

Run an iteratee with the given input, and return either the final value (if it succeeded) or the error (if it failed).

Since: 0.4.15

Like runLists, except errors are converted to exceptions and thrown.

Since: 0.4.15

Peek at the next element in the stream, or Nothing if the stream has ended.

Get the last element in the stream, or Nothing if the stream has ended.

Consumes the entire stream.

Get how many elements remained in the stream.

Consumes the entire stream.

Deprecated in 0.4.5: use continue instead

Deprecated in 0.4.5: use head instead

Deprecated in 0.4.5: use drop instead

Deprecated in 0.4.5: use dropWhile instead

Deprecated in 0.4.5: use takeWhile instead

Deprecated in 0.4.5: use takeWhile instead

Deprecated in 0.4.5: use consume instead

Deprecated in 0.4.8: use fold instead

Since: 0.4.5

Deprecated in 0.4.8: use fold instead

Since: 0.4.5

Deprecated in 0.4.8: use foldM instead

Since: 0.4.5

Deprecated in 0.4.8: use iterate instead

Since: 0.4.5

Deprecated in 0.4.8: use iterateM instead

Since: 0.4.5

Deprecated in 0.4.8: use repeat instead

Since: 0.4.5

Deprecated in 0.4.8: use repeatM instead

Since: 0.4.5

Deprecated in 0.4.8: use replicate instead

Since: 0.4.5

Deprecated in 0.4.8: use replicateM instead

Since: 0.4.5

Deprecated in 0.4.8: use generateM instead

Since: 0.4.5

Deprecated in 0.4.8: use map instead

Deprecated in 0.4.8: use mapM instead

Since: 0.4.3

Deprecated in 0.4.8: use concatMap instead

Since: 0.4.3

Deprecated in 0.4.8: use concatMapM instead

Since: 0.4.5

Deprecated in 0.4.8: use filter instead

Since: 0.4.5

Deprecated in 0.4.8: use filterM instead

Since: 0.4.5

Deprecated in 0.4.5: use fold instead

Since: 0.1.1

Deprecated in 0.4.5: use fold instead

Since: 0.1.1

Deprecated in 0.4.5: use foldM instead

Since: 0.1.1