Portability | portable |
---|---|
Maintainer | jmillikin@gmail.com |
Core enumerator types, and some useful primitives.
This module is intended to be imported qualified:
import qualified Data.Enumerator as E
- 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
- yield :: Monad m => b -> Stream a -> Iteratee a m b
- continue :: Monad m => (Stream a -> Iteratee a m b) -> 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'
- throwError :: (Monad m, Exception e) => e -> Iteratee a m b
- catchError :: Monad m => Iteratee a m b -> (SomeException -> Iteratee a m b) -> Iteratee a m b
- foldl :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
- foldl' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
- foldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b
- iterate :: Monad m => (a -> a) -> a -> Enumerator a m b
- iterateM :: Monad m => (a -> m a) -> a -> Enumerator a m b
- repeat :: Monad m => a -> Enumerator a m b
- repeatM :: Monad m => m a -> Enumerator a m b
- replicate :: Monad m => Integer -> a -> Enumerator a m b
- replicateM :: Monad m => Integer -> m a -> Enumerator a m b
- generateM :: Monad m => m (Maybe a) -> Enumerator a m b
- map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
- concatMap :: Monad m => (ao -> [ai]) -> Enumeratee ao ai m b
- filter :: Monad m => (a -> Bool) -> Enumeratee a a m b
- mapM :: Monad m => (ao -> m ai) -> Enumeratee ao ai m b
- concatMapM :: Monad m => (ao -> m [ai]) -> Enumeratee ao ai m b
- filterM :: Monad m => (a -> m Bool) -> Enumeratee a a m b
- printChunks :: (MonadIO m, Show a) => Bool -> Iteratee a m ()
- concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b
- joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m b
- joinE :: Monad m => Enumerator ao m (Step ai m b) -> Enumeratee ao ai m b -> Enumerator ai m b
- sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m b
- enumList :: Monad m => Integer -> [a] -> Enumerator a m b
- enumEOF :: Monad m => Enumerator a m b
- run :: Monad m => Iteratee a m b -> m (Either SomeException b)
- run_ :: Monad m => Iteratee a m b -> m b
- checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' 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
- isEOF :: Monad m => Iteratee a m Bool
- liftTrans :: (Monad m, MonadTrans t, Monad (t m)) => Iteratee a m b -> Iteratee a (t m) b
- liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m b
- peek :: Monad m => Iteratee a m (Maybe a)
- last :: Monad m => Iteratee a m (Maybe a)
- length :: Monad m => Iteratee a m Integer
- head :: Monad m => Iteratee a m (Maybe a)
- drop :: Monad m => Integer -> Iteratee a m ()
- dropWhile :: Monad m => (a -> Bool) -> Iteratee a m ()
- span :: Monad m => (a -> Bool) -> Iteratee a m [a]
- break :: Monad m => (a -> Bool) -> Iteratee a m [a]
- consume :: Monad m => Iteratee a m [a]
- liftFoldL :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
- liftFoldL' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
- liftFoldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b
Core
Types
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, 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.
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
While Iteratee
s consume data, enumerators generate it. Since
is an alias for Iteratee
m (
, Step
a m b)Enumerator
s can
be considered step transformers of type
.
Step
a m b -> m (Step
a m b)
Enumerator
s 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 (Yield
s a value).
type Enumeratee ao ai m b = Step ai m b -> Iteratee ao m (Step ai m b)Source
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
).
Operators
(==<<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'Source
(==<<) = flip (>>==)
($$) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'Source
($$) = (==<<)
This might be easier to read when passing a chain of iteratees to an enumerator.
Since: 0.1.1
(>==>) :: Monad m => Enumerator a m b -> (Step a m b -> Iteratee a' m b') -> Step a m b -> Iteratee a' m b'Source
(>==>) e1 e2 s = e1 s >>== e2
Since: 0.1.1
(<==<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Enumerator a m b -> Step a m b -> Iteratee a' m b'Source
(<==<) = flip (>==>)
Since: 0.1.1
Primitives
Error handling
throwError :: (Monad m, Exception e) => e -> Iteratee a m bSource
throwError exc =returnI
(Error
(toException
exc))
catchError :: Monad m => Iteratee a m b -> (SomeException -> Iteratee a m b) -> Iteratee a m bSource
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.
Since: 0.1.1
Iteratees
foldl :: Monad m => (b -> a -> b) -> b -> Iteratee a m bSource
Run the entire input stream through a pure left fold, yielding when there is no more input.
Since: 0.4.5
foldl' :: Monad m => (b -> a -> b) -> b -> Iteratee a m bSource
Run the entire input stream through a pure strict left fold, yielding when there is no more input.
Since: 0.4.5
foldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m bSource
Run the entire input stream through a monadic left fold, yielding when there is no more input.
Since: 0.4.5
Enumerators
iterate :: Monad m => (a -> a) -> a -> Enumerator a m bSource
iterate f x
enumerates an infinite stream of repeated applications
of f to x.
Analogous to iterate
.
Since: 0.4.5
iterateM :: Monad m => (a -> m a) -> a -> Enumerator a m bSource
Similar to iterate
, except the iteration function is monadic.
Since: 0.4.5
repeat :: Monad m => a -> Enumerator a m bSource
repeatM :: Monad m => m a -> Enumerator a m bSource
Enumerates an infinite stream by running the provided computation and passing each result to the iteratee.
Since: 0.4.5
replicate :: Monad m => Integer -> a -> Enumerator a m bSource
replicateM :: Monad m => Integer -> m a -> Enumerator a m bSource
replicateM n m_x
enumerates a stream of n input elements; each
element is generated by running the input computation m_x once.
Since: 0.4.5
generateM :: Monad m => m (Maybe a) -> Enumerator a m bSource
Enumeratees
concatMap :: Monad m => (ao -> [ai]) -> Enumeratee ao ai m bSource
concatMap f = concatMapM
(return . f)
Since: 0.4.3
filter :: Monad m => (a -> Bool) -> Enumeratee a a m bSource
mapM :: Monad m => (ao -> m ai) -> Enumeratee ao ai m bSource
mapM f =concatMapM
(x ->mapM
f [x])
Since: 0.4.3
concatMapM :: Monad m => (ao -> m [ai]) -> Enumeratee ao ai m bSource
concatMapM f
applies f to each input element and feeds the
resulting outputs to the inner iteratee.
Since: 0.4.5
filterM :: Monad m => (a -> m Bool) -> Enumeratee a a m bSource
filterM p =concatMapM
(x ->filterM
p [x])
Since: 0.4.5
Debugging
Print chunks as they're received from the enumerator, optionally printing empty chunks.
Misc. utilities
concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m bSource
Compose a list of Enumerator
s using '(>>==)'
joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m bSource
joinI
is used to “flatten” Enumeratee
s into an
Iteratee
.
joinE :: Monad m => Enumerator ao m (Step ai m b) -> Enumeratee ao ai m b -> Enumerator ai m bSource
Flatten an enumerator/enumeratee pair into a single enumerator.
sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m bSource
Feeds outer input elements into the provided iteratee until it yields an inner input, passes that to the inner iteratee, and then loops.
enumList :: Monad m => Integer -> [a] -> Enumerator a m bSource
enumList n xs
enumerates xs as a stream, passing n inputs per
chunk.
Primarily useful for testing and debugging.
enumEOF :: Monad m => Enumerator a m bSource
docs TODO
run :: Monad m => Iteratee a m b -> m (Either SomeException b)Source
Run an iteratee until it finishes, and return either the final value (if it succeeded) or the error (if it failed).
run_ :: Monad m => Iteratee a m b -> m bSource
Like run
, except errors are converted to exceptions and thrown.
Primarily useful for small scripts or other simple cases.
Since: 0.4.1
checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m bSource
checkDone =checkDoneEx
(Chunks
[])
Use this for enumeratees which do not have an input buffer.
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
Compatibility
Obsolete functions
liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m bSource
Deprecated in 0.4.5: use continue
instead
peek :: Monad m => Iteratee a m (Maybe a)Source
Peek at the next element in the stream, or Nothing
if the stream
has ended.
last :: Monad m => Iteratee a m (Maybe a)Source
Get the last element in the stream, or Nothing
if the stream
has ended.
Consumes the entire stream.
length :: Monad m => Iteratee a m IntegerSource
Get how many elements remained in the stream.
Consumes the entire stream.
Deprecated aliases
head :: Monad m => Iteratee a m (Maybe a)Source
Deprecated in 0.4.5: use Data.Enumerator.List.head
instead
drop :: Monad m => Integer -> Iteratee a m ()Source
Deprecated in 0.4.5: use Data.Enumerator.List.drop
instead
dropWhile :: Monad m => (a -> Bool) -> Iteratee a m ()Source
Deprecated in 0.4.5: use Data.Enumerator.List.dropWhile
instead
span :: Monad m => (a -> Bool) -> Iteratee a m [a]Source
Deprecated in 0.4.5: use Data.Enumerator.List.takeWhile
instead
break :: Monad m => (a -> Bool) -> Iteratee a m [a]Source
Deprecated in 0.4.5: use Data.Enumerator.List.takeWhile
instead
consume :: Monad m => Iteratee a m [a]Source
Deprecated in 0.4.5: use Data.Enumerator.List.consume
instead
liftFoldL :: Monad m => (b -> a -> b) -> b -> Iteratee a m bSource
Deprecated in 0.4.5: use foldl
instead
Since: 0.1.1
liftFoldL' :: Monad m => (b -> a -> b) -> b -> Iteratee a m bSource
Deprecated in 0.4.5: use foldl'
instead
Since: 0.1.1