Safe Haskell | None |
---|---|

Language | Haskell2010 |

Monadic Iteratees: incremental input parsers, processors and transformers

This module provides many basic iteratees from which more complicated
iteratees can be built. In general these iteratees parallel those in
`Data.List`

, with some additions.

## Synopsis

- isFinished :: Nullable s => Iteratee s m Bool
- stream2list :: Monad m => Iteratee [el] m [el]
- stream2stream :: (Monad m, Nullable s, Monoid s) => Iteratee s m s
- dropWhileStream :: (el -> Bool) -> Iteratee [el] m ()
- dropStream :: Int -> Iteratee [el] m ()
- headStream :: Iteratee [el] m el
- tryHead :: Iteratee [el] m (Maybe el)
- lastStream :: Iteratee [el] m el
- heads :: (Monad m, Eq el) => [el] -> Iteratee [el] m Int
- peekStream :: Iteratee [el] m (Maybe el)
- roll :: Monad m => Int -> Int -> Iteratee [el] m [[el]]
- lengthStream :: Num a => Iteratee [el] m a
- chunkLength :: Iteratee [el] m (Maybe Int)
- takeFromChunk :: Int -> Iteratee [el] m [el]
- breakStream :: (el -> Bool) -> Iteratee [el] m [el]
- breakE :: (el -> Bool) -> Enumeratee [el] [el] m a
- takeStream :: Monad m => Int -> Enumeratee [el] [el] m a
- takeUpTo :: Monad m => Int -> Enumeratee [el] [el] m a
- takeWhileE :: (el -> Bool) -> Enumeratee [el] [el] m a
- mapStream :: (el -> el') -> Enumeratee [el] [el'] m a
- concatMapStream :: Monoid t => (a -> t) -> Enumeratee [a] t m r
- concatMapStreamM :: Monad m => (a -> m t) -> Enumeratee [a] t m r
- mapMaybeStream :: (a -> Maybe b) -> Enumeratee [a] [b] m r
- filterStream :: (el -> Bool) -> Enumeratee [el] [el] m a
- filterStreamM :: Monad m => (a -> m Bool) -> Enumeratee [a] [a] m r
- groupStreamBy :: Monad m => (t -> t -> Bool) -> m (Iteratee [t] m t2) -> Enumeratee [t] [t2] m a
- groupStreamOn :: (Monad m, Eq t1) => (e -> t1) -> (t1 -> m (Iteratee [e] m t2)) -> Enumeratee [e] [(t1, t2)] m a
- mergeStreams :: Monad m => (el1 -> el2 -> b) -> Enumeratee [el2] b (Iteratee [el1] m) a
- mergeByChunks :: Monad m => ([el1] -> [el2] -> c3) -> ([el1] -> c3) -> ([el2] -> c3) -> Enumeratee [el2] c3 (Iteratee [el1] m) a
- foldStream :: (a -> el -> a) -> a -> Iteratee [el] m a
- enumPureNChunk :: Monad m => [el] -> Int -> Enumerator [el] m a
- enumWith :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m (a, b)
- zipStreams :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m (a, b)
- zipStreams3 :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m c -> Iteratee [el] m (a, b, c)
- zipStreams4 :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m c -> Iteratee [el] m d -> Iteratee [el] m (a, b, c, d)
- zipStreams5 :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m c -> Iteratee [el] m d -> Iteratee [el] m e -> Iteratee [el] m (a, b, c, d, e)
- sequenceStreams_ :: Monad m => [Iteratee [el] m a] -> Iteratee [el] m ()
- countConsumed :: (Monad m, Integral n) => Iteratee [el] m a -> Iteratee [el] m (a, n)
- mapStreamM :: Monad m => (el -> m el') -> Enumeratee [el] [el'] m a
- mapStreamM_ :: Monad m => (el -> m b) -> Iteratee [el] m ()
- foldStreamM :: Monad m => (b -> a -> m b) -> b -> Iteratee [a] m b
- module Bio.Iteratee.Iteratee

# Iteratees

## Iteratee Utilities

stream2list :: Monad m => Iteratee [el] m [el] Source #

Read a stream to the end and return all of its elements as a list. This iteratee returns all data from the stream *strictly*.

stream2stream :: (Monad m, Nullable s, Monoid s) => Iteratee s m s Source #

Read a stream to the end and return all of its elements as a stream. This iteratee returns all data from the stream *strictly*.

## Basic Iteratees

dropWhileStream :: (el -> Bool) -> Iteratee [el] m () Source #

Skip all elements while the predicate is true.

The analogue of `List.dropWhile`

dropStream :: Int -> Iteratee [el] m () Source #

Drop n elements of the stream, if there are that many.

The analogue of `List.drop`

headStream :: Iteratee [el] m el Source #

Attempt to read the next element of the stream and return it Raise a (recoverable) error if the stream is terminated.

The analogue of `List.head`

Because `head`

can raise an error, it shouldn't be used when constructing
iteratees for `convStream`

. Use `tryHead`

instead.

tryHead :: Iteratee [el] m (Maybe el) Source #

Similar to `headStream`

, except it returns `Nothing`

if the stream
is terminated.

lastStream :: Iteratee [el] m el Source #

Attempt to read the last element of the stream and return it Raise a (recoverable) error if the stream is terminated

The analogue of `List.last`

heads :: (Monad m, Eq el) => [el] -> Iteratee [el] m Int Source #

Given a sequence of characters, attempt to match them against
the characters on the stream. Return the count of how many
characters matched. The matched characters are removed from the
stream.
For example, if the stream contains `abd`

, then (heads `abc`

)
will remove the characters `ab`

and return 2.

peekStream :: Iteratee [el] m (Maybe el) Source #

Look ahead at the next element of the stream, without removing
it from the stream.
Return `Just c`

if successful, return `Nothing`

if the stream is
terminated by `EOF`

.

Return a chunk of `t`

elements length while consuming `d`

elements
from the stream. Useful for creating a 'rolling average' with
`convStream`

.

lengthStream :: Num a => Iteratee [el] m a Source #

Return the total length of the remaining part of the stream.

This forces evaluation of the entire stream.

The analogue of `List.length`

chunkLength :: Iteratee [el] m (Maybe Int) Source #

Get the length of the current chunk, or `Nothing`

if `EOF`

.

This function consumes no input.

takeFromChunk :: Int -> Iteratee [el] m [el] Source #

Take `n`

elements from the current chunk, or the whole chunk if
`n`

is greater.

## Nested iteratee combinators

breakStream :: (el -> Bool) -> Iteratee [el] m [el] Source #

Takes an element predicate and returns the (possibly empty) prefix of the stream. None of the characters in the string satisfy the character predicate. If the stream is not terminated, the first character of the remaining stream satisfies the predicate.

N.B. `breakE`

should be used in preference to `breakStream`

.
`breakStream`

will retain all data until the predicate is met, which may
result in a space leak.

The analogue of `List.break`

breakE :: (el -> Bool) -> Enumeratee [el] [el] m a Source #

Takes an element predicate and an iteratee, running the iteratee on all elements of the stream until the predicate is met.

the following rule relates `break`

to `breakE`

`break`

pred === `joinI`

(`breakE`

pred stream2stream)

`breakE`

should be used in preference to `break`

whenever possible.

:: Monad m | |

=> Int | number of elements to consume |

-> Enumeratee [el] [el] m a |

Read n elements from a stream and apply the given iteratee to the stream of the read elements. Unless the stream is terminated early, we read exactly n elements, even if the iteratee has accepted fewer.

The analogue of `List.take`

takeUpTo :: Monad m => Int -> Enumeratee [el] [el] m a Source #

Read n elements from a stream and apply the given iteratee to the
stream of the read elements. If the given iteratee accepted fewer
elements, we stop.
This is the variation of `takeStream`

with the early termination
of processing of the outer stream once the processing of the inner stream
finished early.

Iteratees composed with `takeUpTo`

will consume only enough elements to
reach a done state. Any remaining data will be available in the outer
stream.

> let iter = do h <- joinI $ takeUpTo 5 I.head t <- stream2list return (h,t) > enumPureNChunk [1..10::Int] 3 iter >>= run >>= print (1,[2,3,4,5,6,7,8,9,10]) > enumPureNChunk [1..10::Int] 7 iter >>= run >>= print (1,[2,3,4,5,6,7,8,9,10])

in each case, `I.head`

consumes only one element, returning the remaining
4 elements to the outer stream

takeWhileE :: (el -> Bool) -> Enumeratee [el] [el] m a Source #

Takes an element predicate and an iteratee, running the iteratee on all elements of the stream while the predicate is met.

This is preferred to `takeWhile`

.

mapStream :: (el -> el') -> Enumeratee [el] [el'] m a Source #

Map a function over an `Iteratee`

.
This one is reimplemented and differs from the the one in
Data.Iteratee.ListLike in so far that it doesn't pass on an `EOF`

received in the input, which is the expected behavior.

concatMapStream :: Monoid t => (a -> t) -> Enumeratee [a] t m r Source #

Apply a function to the elements of a stream, concatenate the results into a stream. No giant intermediate list is produced.

concatMapStreamM :: Monad m => (a -> m t) -> Enumeratee [a] t m r Source #

Apply a monadic function to the elements of a stream, concatenate the results into a stream. No giant intermediate list is produced.

mapMaybeStream :: (a -> Maybe b) -> Enumeratee [a] [b] m r Source #

filterStream :: (el -> Bool) -> Enumeratee [el] [el] m a Source #

Creates an `enumeratee`

with only elements from the stream that
satisfy the predicate function. The outer stream is completely consumed.

The analogue of `List.filter`

filterStreamM :: Monad m => (a -> m Bool) -> Enumeratee [a] [a] m r Source #

Apply a monadic filter predicate to an `Iteratee`

.

groupStreamBy :: Monad m => (t -> t -> Bool) -> m (Iteratee [t] m t2) -> Enumeratee [t] [t2] m a Source #

Grouping on `Iteratee`

s. `groupStreamBy cmp inner outer`

executes
`inner`

to obtain an `Iteratee`

`i`

, then passes elements `e`

to `i`

as long as `cmp e0 e`

, where `e0`

is some preceeding element, is
true. Else, the result of `run i`

is passed to `outer`

and
`groupStreamBy`

restarts. At end of input, the resulting `outer`

is
returned.

groupStreamOn :: (Monad m, Eq t1) => (e -> t1) -> (t1 -> m (Iteratee [e] m t2)) -> Enumeratee [e] [(t1, t2)] m a Source #

Grouping on `Iteratee`

s. `groupStreamOn proj inner outer`

executes
`inner (proj e)`

, where `e`

is the first input element, to obtain an
`Iteratee`

`i`

, then passes elements `e`

to `i`

as long as `proj e`

produces the same result. If `proj e`

changes or the input ends, the
pair of `proj e`

and the result of `run i`

is passed to `outer`

. At
end of input, the resulting `outer`

is returned.

mergeStreams :: Monad m => (el1 -> el2 -> b) -> Enumeratee [el2] b (Iteratee [el1] m) a Source #

`mergeStreams`

offers another way to nest iteratees: as a monad stack.
This allows for the possibility of interleaving data from multiple
streams.

-- print each element from a stream of lines. logger :: (MonadIO m) => Iteratee [ByteString] m () logger = mapStreamM_ (liftIO . putStrLn . B.unpack) -- combine alternating lines from two sources -- To see how this was derived, follow the types from -- 'ileaveLines logger' and work outwards. run =<< enumFile 10 "file1" (joinI $ enumLinesBS $ ( enumFile 10 "file2" . joinI . enumLinesBS $ joinI (ileaveLines logger)) >>= run) ileaveLines :: (Functor m, Monad m) => Enumeratee [ByteString] [ByteString] (Iteratee [ByteString] m) [ByteString] ileaveLines = mergeStreams (\l1 l2 -> [B.pack "f1:\n\t" ,l1 ,B.pack "f2:\n\t" ,l2 ]

:: Monad m | |

=> ([el1] -> [el2] -> c3) | merge function |

-> ([el1] -> c3) | |

-> ([el2] -> c3) | |

-> Enumeratee [el2] c3 (Iteratee [el1] m) a |

A version of mergeStreams which operates on chunks instead of elements.

mergeByChunks offers more control than `mergeStreams`

.
`mergeStreams`

terminates when the first stream terminates, however
mergeByChunks will continue until both streams are exhausted.

`mergeByChunks`

guarantees that both chunks passed to the merge
function will have the same number of elements, although that number
may vary between calls.

## Folds

foldStream :: (a -> el -> a) -> a -> Iteratee [el] m a Source #

Left-associative fold that is strict in the accumulator.
This function should be used in preference to `foldl`

whenever possible.

The analogue of `List.foldl'`

.

# Enumerators

## Basic enumerators

enumPureNChunk :: Monad m => [el] -> Int -> Enumerator [el] m a Source #

The pure n-chunk enumerator
It passes a given stream of elements to the iteratee in `n`

-sized chunks.

## Enumerator Combinators

enumWith :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m (a, b) Source #

Enumerate over two iteratees in parallel as long as the first iteratee is still consuming input. The second iteratee will be terminated with EOF when the first iteratee has completed. An example use is to determine how many elements an iteratee has consumed:

snd <$> enumWith (dropWhile (<5)) length

Compare to `zipStreams`

zipStreams :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m (a, b) Source #

Enumerate two iteratees over a single stream simultaneously.

Compare to `List.zip`

.

zipStreams3 :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m c -> Iteratee [el] m (a, b, c) Source #

zipStreams4 :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m c -> Iteratee [el] m d -> Iteratee [el] m (a, b, c, d) Source #

zipStreams5 :: Monad m => Iteratee [el] m a -> Iteratee [el] m b -> Iteratee [el] m c -> Iteratee [el] m d -> Iteratee [el] m e -> Iteratee [el] m (a, b, c, d, e) Source #

sequenceStreams_ :: Monad m => [Iteratee [el] m a] -> Iteratee [el] m () Source #

Enumerate a list of iteratees over a single stream simultaneously and discard the results. This is a different behavior than Prelude's sequence_ which runs iteratees in the list one after the other.

Compare to `Prelude.sequence_`

.

countConsumed :: (Monad m, Integral n) => Iteratee [el] m a -> Iteratee [el] m (a, n) Source #

Transform an iteratee into one that keeps track of how much data it consumes.

## Monadic functions

mapStreamM :: Monad m => (el -> m el') -> Enumeratee [el] [el'] m a Source #

Maps a monadic function over an `Iteratee`

.

mapStreamM_ :: Monad m => (el -> m b) -> Iteratee [el] m () Source #

Maps a monadic function over the elements of the stream and ignores the result.

foldStreamM :: Monad m => (b -> a -> m b) -> b -> Iteratee [a] m b Source #

Folds a monadic function over an `Iteratee`

.

# Re-exported modules

module Bio.Iteratee.Iteratee