snap-core-0.5.1.3: Snap: A Haskell Web Framework (Core)

Snap.Iteratee

Contents

Description

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.

Synopsis

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.

Iteratee utilities

joinI' :: Monad m => Iteratee a m (Step a m b) -> Iteratee a m bSource

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

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!

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.

mapEnum :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Enumerator aIn m a -> Enumerator aOut m aSource

mapIter :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Iteratee aIn m a -> Iteratee aOut m aSource

killIfTooSlowSource

Arguments

:: 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.

(Chunks []) is used to indicate that a stream is still active, but currently has no available data. Iteratees should ignore empty chunks.

Constructors

Chunks [a] 
EOF 

Instances

Monad Stream 
Functor Stream 
Typeable1 Stream

Since: 0.4.8

Applicative Stream

Since: 0.4.5

Eq a => Eq (Stream a) 
Show a => Show (Stream a) 
Monoid (Stream a) 

data Step a m b

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 cannot receive any more input, and has generated 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.

Instances

(Typeable a, Typeable1 m) => Typeable1 (Step a m)

Since: 0.4.8

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.

Constructors

Iteratee 

Fields

runIteratee :: m (Step a m b)
 

Instances

MonadTrans (Iteratee a) 
Monad m => Monad (Iteratee a m) 
Monad m => Functor (Iteratee a m) 
(Typeable a, Typeable1 m) => Typeable1 (Iteratee a m)

Since: 0.4.6

Monad m => Applicative (Iteratee a m) 
(Functor m, MonadCatchIO m) => MonadCatchIO (Iteratee s m) 
MonadIO m => MonadIO (Iteratee a m) 

type Enumerator a m b = Step a m b -> Iteratee a m b

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).

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.

returnI :: Monad m => Step a m b -> Iteratee a m b

returnI step = Iteratee (return step)

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.

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

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

liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m b

Deprecated in 0.4.5: use continue instead

(>>==) :: Monad m => Iteratee a m b -> (Step a m b -> Iteratee a' m b') -> Iteratee a' m b'

Equivalent to '(>>=)' for m (Step a m b); allows Iteratees with different input types to be composed.

(==<<) :: 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

consume :: Monad m => Iteratee a m [a]

consume = takeWhile (const True)

Since: 0.4.5

isEOF :: Monad m => Iteratee a m Bool

Check whether a stream has reached EOF. Most clients should use Data.Enumerator.List.head instead.

liftTrans :: (Monad m, MonadTrans t, Monad (t m)) => Iteratee a m b -> Iteratee a (t m) b

Lift an Iteratee onto a monad transformer, re-wrapping the Iteratee’s inner monadic values.

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

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

printChunks

Arguments

:: (MonadIO m, Show a) 
=> Bool

Print empty chunks

-> Iteratee a m () 

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

Sends EOF to its iteratee. Most clients should use run or run_ instead.

enumList :: Monad m => Integer -> [a] -> Enumerator a m b

enumList n xs enumerates xs as a stream, passing n inputs per chunk.

Primarily useful for testing and debugging.

concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b

Compose a list of Enumerators 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

map f applies f to each input element and feeds the resulting outputs to the inner iteratee.

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.

joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m b

joinI is used to “flatten” Enumeratees into an Iteratee.