|
Data.Enumerator | Portability | portable | Maintainer | jmillikin@gmail.com |
|
|
|
|
|
Description |
An implementation of Oleg Kiselyov’s left-fold enumerators
|
|
Synopsis |
|
|
|
|
Types
|
|
|
Not to be confused with types from the Stream or
stream-fusion packages, a Stream is a sequence of chunks
generated by an Enumerator. In contrast to Oleg’s implementation,
this stream does not support error handling -- errors encountered
while generating a stream are reported in the Step type instead.
(Chunks []) is used to indicate that a stream is still active, but
currently has no available data. Iteratees should ignore empty chunks.
| Constructors | | Instances | |
|
|
|
Constructors | Continue (Stream a -> Iteratee a m b) | The Iteratee is capable of accepting more input. Note that more input
is not necessarily required; the Iteratee might be able to generate a
value immediately if it receives EOF.
| Yield b (Stream a) | The Iteratee has received enough input to generate a result.
Included in this value is left-over input, which can be passed to
composed Iteratees.
| Error SomeException | The Iteratee encountered an error which prevents it from proceeding
further.
|
|
|
|
|
The primary data type for this library, which consumes
input from a Stream until it either generates a value or encounters
an error. Rather than requiring all input at once, an iteratee will
return Continue when it is capable of processing more data.
In general, iteratees begin in the Continue state. As each chunk is
passed to the continuation, the iteratee returns the next step:
Continue for more data, Yield when it's finished, or Error to
abort processing.
| Constructors | Iteratee | | runIteratee :: m (Step a m b) | |
|
| Instances | |
|
|
|
While Iteratees consume data, enumerators generate it. Since
Iteratee is an alias for m (Step a m b), Enumerators can
be considered step transformers of type
Step a m b -> m (Step a m b).
Enumerators typically read from an external source (parser, handle,
random generator, etc). They feed chunks into an Iteratee until the
source runs out of data (triggering EOF) or the iteratee finishes
processing (Yields a value).
|
|
|
In cases where an enumerator acts as both a source and sink, the resulting
type is named an Enumeratee. Enumeratees have two input types,
“outer a” (aOut) and “inner a” (aIn).
|
|
Primitives
|
|
Combinators
|
|
These are common patterns which occur whenever iteratees are
being defined.
|
|
|
returnI x = Iteratee (return x) |
|
|
yield x chunk = returnI (Yield x chunk) |
|
|
continue k = returnI (Continue k) |
|
|
throwError err = returnI (Error err) |
|
|
|
|
liftI f = continue (returnI . f) |
|
|
Equivalent to (>>=), but allows Iteratees with different input types
to be composed.
|
|
|
(==<<) = flip (>>==) |
|
|
($$) = (==<<) This might be easier to read when passing a chain of iteratees to an
enumerator.
|
|
|
(>==>) e1 e2 s = e1 s >>== e2 |
|
|
(<==<) = flip (>==>) |
|
Iteratees
|
|
|
Run an iteratee until it finishes, and return either the final value
(if it succeeded) or the error (if it failed).
|
|
|
|
|
Consume all input until EOF, then return consumed input as a list.
|
|
|
Return True if the next Stream is EOF.
|
|
|
Lift an Iteratee onto a monad transformer, re-wrapping the
Iteratee’s inner monadic values.
|
|
|
Lifts a pure left fold into an iteratee.
|
|
|
As liftFoldL, but strict in its accumulator.
|
|
|
Lifts a monadic left fold into an iteratee.
|
|
|
Print chunks as they're received from the enumerator, optionally
printing empty chunks.
|
|
Enumerators
|
|
|
The most primitive enumerator; simply sends EOF. The iteratee must
either yield a value or throw an error continuing receiving EOF will
not terminate with any useful value.
|
|
|
Another small, useful enumerator separates an input list into chunks,
and sends them to the iteratee. This is useful for testing iteratees in pure
code.
|
|
|
Compose a list of Enumerators using '(>>==)'
|
|
Enumeratees
|
|
|
checkDone = checkDoneEx (Chunks []) Use this for enumeratees which do not have an input buffer.
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
joinI is used to “flatten” Enumeratees into an
Iteratee.
|
|
Parser combinators
|
|
Oleg’s original IterateeM.hs includes some basic iteratees
for parsing, so this section ports them to the new interface. However,
in practice most parsing will be performed with enumerator-based
interfaces to existing parser libraries (such as Parsec or Attoparsec).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
break p = span (not . p) |
|
Produced by Haddock version 2.6.1 |