Portability  portable 

Maintainer  jmillikin@gmail.com 
Core enumerator types, and some useful primitives.
Be careful when using the functions defined in this module, as they will allow you to create iteratees which violate the monad laws.
 data Stream a
 newtype Iteratee a m b = Iteratee {
 runIteratee :: m (Step a m b)
 data Step a m b
 type Enumerator a m b = Step a m b > Iteratee a m b
 type Enumeratee ao ai m b = Step ai m b > Iteratee ao m (Step ai m b)
 returnI :: Monad m => Step a m b > Iteratee a m b
 continue :: Monad m => (Stream a > Iteratee a m b) > Iteratee a m b
 yield :: Monad m => b > Stream a > Iteratee a m b
 (>>==) :: Monad m => Iteratee a m b > (Step a m b > Iteratee a' m b') > Iteratee a' m b'
 (==<<) :: Monad m => (Step a m b > Iteratee a' m b') > Iteratee a m b > Iteratee a' m b'
 ($$) :: Monad m => (Step a m b > Iteratee a' m b') > Iteratee a m b > Iteratee a' m b'
 (>==>) :: Monad m => Enumerator a m b > (Step a m b > Iteratee a' m b') > Step a m b > Iteratee a' m b'
 (<==<) :: Monad m => (Step a m b > Iteratee a' m b') > Enumerator a m b > Step a m b > Iteratee a' m b'
 enumEOF :: Monad m => Enumerator a m b
 checkContinue0 :: Monad m => (Enumerator a m b > (Stream a > Iteratee a m b) > Iteratee a m b) > Enumerator a m b
 checkContinue1 :: Monad m => ((s1 > Enumerator a m b) > s1 > (Stream a > Iteratee a m b) > Iteratee a m b) > s1 > Enumerator a m b
 checkDoneEx :: Monad m => Stream a' > ((Stream a > Iteratee a m b) > Iteratee a' m (Step a m b)) > Enumeratee a' a m b
 checkDone :: Monad m => ((Stream a > Iteratee a m b) > Iteratee a' m (Step a m b)) > Enumeratee a' a m b
Documentation
A Stream
is a sequence of chunks generated by an Enumerator
.
(
is used to indicate that a stream is still active, but
currently has no available data. Iteratees should ignore empty chunks.
Chunks
[])
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
.
Iteratee  

Continue (Stream a > Iteratee a m b)  The 
Yield b (Stream a)  The 
Error SomeException  The 
type Enumerator a m b = Step a m b > Iteratee a m bSource
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.
type Enumeratee ao ai m b = Step ai m b > Iteratee ao m (Step ai m b)Source
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 leftover input
is passed between elements of the data processing pipeline.
Primitives
yield :: Monad m => b > Stream a > Iteratee a m bSource
yield
x extra =returnI
(Yield
x extra)
WARNING: due to the current encoding of iteratees in this library,
careless use of the yield
primitive may violate the monad laws.
To prevent this, always make sure that an iteratee never yields
extra data unless it has received at least one input element.
More strictly, iteratees may not yield data that they did not
receive as input. Don't use yield
to “inject” elements
into the stream.
Operators
(>>==) :: Monad m => Iteratee a m b > (Step a m b > Iteratee a' m b') > Iteratee a' m b'Source
The most primitive stream operator. iter >>== enum
returns a new
iteratee which will read from enum
before continuing.
(>==>) :: Monad m => Enumerator a m b > (Step a m b > Iteratee a' m b') > Step a m b > Iteratee a' m b'Source
(<==<) :: Monad m => (Step a m b > Iteratee a' m b') > Enumerator a m b > Step a m b > Iteratee a' m b'Source
Miscellaneous
enumEOF :: Monad m => Enumerator a m bSource
Sends EOF
to its iteratee. Most clients should use run
or run_
instead.
checkContinue0 :: Monad m => (Enumerator a m b > (Stream a > Iteratee a m b) > Iteratee a m b) > Enumerator a m bSource
A common pattern in Enumerator
implementations is to check whether
the inner Iteratee
has finished, and if so, to return its output.
checkContinue0
passes its parameter a continuation if the Iteratee
can still consume input; if not, it returns the iteratee's step.
The type signature here is a bit crazy, but it's actually very easy to use. Take this code:
repeat :: Monad m => a > Enumerator a m b repeat x = loop where loop (Continue k) = k (Chunks [x]) >>== loop loop step = returnI step
And rewrite it without the boilerplate:
repeat :: Monad m => a > Enumerator a m b repeat x = checkContinue0 $ \loop k > k (Chunks [x] >>== loop
Since: 0.4.9
checkContinue1 :: Monad m => ((s1 > Enumerator a m b) > s1 > (Stream a > Iteratee a m b) > Iteratee a m b) > s1 > Enumerator a m bSource
Like checkContinue0
, but allows each loop step to use a state value:
iterate :: Monad m => (a > a) > a > Enumerator a m b iterate f = checkContinue1 $ \loop a k > k (Chunks [a]) >>== loop (f a)
Since: 0.4.9
checkDoneEx :: Monad m => Stream a' > ((Stream a > Iteratee a m b) > Iteratee a' m (Step a m b)) > Enumeratee a' a m bSource
A common pattern in Enumeratee
implementations is to check whether
the inner Iteratee
has finished, and if so, to return its output.
checkDone
passes its parameter a continuation if the Iteratee
can still consume input, or yields otherwise.
Since: 0.4.3