Snap Framework type aliases and utilities for iteratees. Note that as a
convenience, this module also exports everything from Data.Enumerator
in
the enumerator
library.
- enumBS :: Monad m => ByteString -> Enumerator ByteString m a
- enumLBS :: Monad m => ByteString -> Enumerator ByteString m a
- enumBuilder :: Monad m => Builder -> Enumerator Builder m a
- enumFile :: FilePath -> Enumerator ByteString IO a
- enumFilePartial :: FilePath -> (Int64, Int64) -> Enumerator ByteString IO a
- data InvalidRangeException
- joinI' :: Monad m => Iteratee a m (Step a m b) -> Iteratee a m b
- countBytes :: Monad m => forall a. Iteratee ByteString m a -> Iteratee ByteString m (a, Int64)
- drop' :: Monad m => Int64 -> Iteratee ByteString m ()
- mkIterateeBuffer :: IO (ForeignPtr CChar)
- unsafeBufferIterateeWithBuffer :: ForeignPtr CChar -> Iteratee ByteString IO a -> Iteratee ByteString IO a
- unsafeBufferIteratee :: Iteratee ByteString IO a -> IO (Iteratee ByteString IO a)
- take :: Monad m => Int -> Enumeratee ByteString ByteString m a
- drop :: Monad m => Int -> Iteratee ByteString m ()
- takeExactly :: Monad m => Int64 -> Enumeratee ByteString ByteString m a
- takeNoMoreThan :: Monad m => Int64 -> Enumeratee ByteString ByteString m a
- skipToEof :: Monad m => Iteratee a m ()
- mapEnum :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Enumerator aIn m a -> Enumerator aOut m a
- mapIter :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Iteratee aIn m a -> Iteratee aOut m a
- killIfTooSlow :: MonadIO m => m () -> Double -> Int -> Iteratee ByteString m a -> Iteratee ByteString m a
- data TooManyBytesReadException
- data ShortWriteException
- data RateTooSlowException
- data Stream a
- data Step a m b
- newtype Iteratee a m b = Iteratee {
- runIteratee :: m (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
- 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
- liftI :: Monad m => (Stream a -> Step 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'
- run :: Monad m => Iteratee a m b -> m (Either SomeException b)
- run_ :: Monad m => Iteratee a m b -> m b
- consume :: Monad m => Iteratee a m [a]
- isEOF :: Monad m => Iteratee a m Bool
- liftTrans :: (Monad m, MonadTrans t, Monad (t m)) => Iteratee a m b -> Iteratee a (t m) b
- 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
- printChunks :: (MonadIO m, Show a) => Bool -> Iteratee a m ()
- head :: Monad m => Iteratee a m (Maybe a)
- peek :: Monad m => Iteratee a m (Maybe a)
- enumEOF :: Monad m => Enumerator a m b
- enumList :: Monad m => Integer -> [a] -> Enumerator a m b
- concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b
- checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m b
- map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
- sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m b
- joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m b
Enumerators
enumBS :: Monad m => ByteString -> Enumerator ByteString m aSource
Enumerates a strict bytestring.
enumLBS :: Monad m => ByteString -> Enumerator ByteString m aSource
Enumerates a lazy bytestring.
enumBuilder :: Monad m => Builder -> Enumerator Builder m aSource
Enumerates a Builder.
enumFile :: FilePath -> Enumerator ByteString IO aSource
enumFilePartial :: FilePath -> (Int64, Int64) -> Enumerator ByteString IO aSource
Iteratee utilities
countBytes :: Monad m => forall a. Iteratee ByteString m a -> Iteratee ByteString m (a, Int64)Source
Wraps an Iteratee
, counting the number of bytes consumed by it.
drop' :: Monad m => Int64 -> Iteratee ByteString m ()Source
Skip n elements of the stream, if there are that many
mkIterateeBuffer :: IO (ForeignPtr CChar)Source
Creates a buffer to be passed into unsafeBufferIterateeWithBuffer
.
unsafeBufferIterateeWithBuffer :: ForeignPtr CChar -> Iteratee ByteString IO a -> Iteratee ByteString IO aSource
Buffers an iteratee, "unsafely". Here we use a fixed binary buffer which we'll re-use, meaning that if you hold on to any of the bytestring data passed into your iteratee (instead of, let's say, shoving it right out a socket) it'll get changed out from underneath you, breaking referential transparency. Use with caution!
This version accepts a buffer created by mkIterateeBuffer
.
unsafeBufferIteratee :: Iteratee ByteString IO a -> IO (Iteratee ByteString IO a)Source
Buffers an iteratee, "unsafely". Here we use a fixed binary buffer which we'll re-use, meaning that if you hold on to any of the bytestring data passed into your iteratee (instead of, let's say, shoving it right out a socket) it'll get changed out from underneath you, breaking referential transparency. Use with caution!
take :: Monad m => Int -> Enumeratee ByteString ByteString m aSource
drop :: Monad m => Int -> Iteratee ByteString m ()Source
Skip n elements of the stream, if there are that many
takeExactly :: Monad m => Int64 -> Enumeratee ByteString ByteString m aSource
Reads n bytes from a stream and applies the given iteratee to the stream of the read elements. Reads exactly n bytes, and if the stream is short propagates an error.
takeNoMoreThan :: Monad m => Int64 -> Enumeratee ByteString ByteString m aSource
mapEnum :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Enumerator aIn m a -> Enumerator aOut m aSource
:: MonadIO m | |
=> m () | action to bump timeout |
-> Double | minimum data rate, in bytes per second |
-> Int | minimum amount of time to let the iteratee run for |
-> Iteratee ByteString m a | iteratee consumer to wrap |
-> Iteratee ByteString m a |
Re-export types and functions from Data.Enumerator
data Stream a
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
[])
data Step a m b
Continue (Stream a -> Iteratee a m b) | The |
Yield b (Stream a) | The |
Error SomeException | The |
newtype Iteratee a m b
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 | |
|
type Enumerator a m b = Step a m b -> Iteratee a m b
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)
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.
yield :: Monad m => b -> Stream a -> Iteratee a m b
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.
throwError :: (Monad m, Exception e) => e -> Iteratee a m b
throwError
exc =returnI
(Error
(toException
exc))
catchError :: Monad m => Iteratee a m b -> (SomeException -> Iteratee a m b) -> Iteratee a m b
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: after a few rounds of catchError doesn't work because X, this
function has grown into a horrible monster. I have no concept of what
unexpected behaviors lurk in its dark crevices. Users are strongly advised
to wrap all uses of catchError
with an appropriate isolate
, such as
Data.Enumerator.List.isolate
or Data.Enumerator.Binary.isolate
, which
will handle input framing even in the face of unexpected errors.
Within the error handler, it is difficult or impossible to know how much input the original iteratee has consumed.
Since: 0.1.1
liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m b
Deprecated in 0.4.5: use continue
instead
(==<<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'
'(==<<)' = flip '(>>==)'
($$) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'
'($$)' = '(==<<)'
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'
'(>==>)' 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'
'(<==<)' = flip '(>==>)'
Since: 0.1.1
Iteratees
run :: Monad m => Iteratee a m b -> m (Either SomeException b)
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 b
Like run
, except errors are converted to exceptions and thrown.
Primarily useful for small scripts or other simple cases.
Since: 0.4.1
isEOF :: Monad m => Iteratee a m Bool
Check whether a stream has reached EOF. Most clients should use
Data.Enumerator.List.head
instead.
liftFoldL :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
Deprecated in 0.4.5: use Data.Enumerator.List.fold
instead
Since: 0.1.1
liftFoldL' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
Deprecated in 0.4.5: use Data.Enumerator.List.fold
instead
Since: 0.1.1
liftFoldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b
Deprecated in 0.4.5: use Data.Enumerator.List.foldM
instead
Since: 0.1.1
Print chunks as they're received from the enumerator, optionally printing empty chunks.
head :: Monad m => Iteratee a m (Maybe a)
Get the next element from the stream, or Nothing
if the stream has
ended.
Since: 0.4.5
peek :: Monad m => Iteratee a m (Maybe a)
Peek at the next element in the stream, or Nothing
if the stream
has ended.
Enumerators
enumEOF :: Monad m => Enumerator a m b
enumList :: Monad m => Integer -> [a] -> Enumerator a m b
enumerates xs as a stream, passing n inputs per
chunk.
enumList
n xs
Primarily useful for testing and debugging.
concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b
Compose a list of Enumerator
s using '(>>==)'
Enumeratees
checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m b
checkDone
=checkDoneEx
(Chunks
[])
Use this for enumeratees which do not have an input buffer.
map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
applies f to each input element and feeds the
resulting outputs to the inner iteratee.
map
f
Since: 0.4.8
sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m b
Feeds outer input elements into the provided iteratee until it yields an inner input, passes that to the inner iteratee, and then loops.