Data.Iteratee.Base

iteratee-0.8.8.1: Iteratee-based I/O

Data.Iteratee.Base

Contents

- Types
  - Exception types
  - Iteratees
- Functions
  - Control functions
  - Creating Iteratees
  - Stream Functions
- Classes

Description

Monadic Iteratees: incremental input parsers, processors and transformers

Synopsis

- data Stream c
  - = EOF (Maybe SomeException)
  - | Chunk c
- data StreamStatus
  - = DataRemaining
  - | EofNoError
  - | EofError SomeException
- module Data.Iteratee.Exception
- newtype Iteratee s m a = Iteratee {
  - runIter :: forall r. (a -> Stream s -> m r) -> ((Stream s -> Iteratee s m a) -> Maybe SomeException -> m r) -> m r
  }
- run :: Monad m => Iteratee s m a -> m a
- tryRun :: (Exception e, Monad m) => Iteratee s m a -> m (Either e a)
- mapIteratee :: (NullPoint s, Monad n, Monad m) => (m a -> n b) -> Iteratee s m a -> Iteratee s n b
- ilift :: (Monad m, Monad n) => (forall r. m r -> n r) -> Iteratee s m a -> Iteratee s n a
- ifold :: (Monad m, Monad n) => (forall r. m r -> acc -> n (r, acc)) -> acc -> Iteratee s m a -> Iteratee s n (a, acc)
- idone :: Monad m => a -> Stream s -> Iteratee s m a
- icont :: (Stream s -> Iteratee s m a) -> Maybe SomeException -> Iteratee s m a
- liftI :: Monad m => (Stream s -> Iteratee s m a) -> Iteratee s m a
- idoneM :: Monad m => a -> Stream s -> m (Iteratee s m a)
- icontM :: Monad m => (Stream s -> Iteratee s m a) -> Maybe SomeException -> m (Iteratee s m a)
- setEOF :: Stream c -> SomeException

# Types

data Stream c

A stream is a (continuing) sequence of elements bundled in Chunks. The first variant indicates termination of the stream. Chunk a gives the currently available part of the stream. The stream is not terminated yet. The case (null Chunk) signifies a stream with no currently available data but which is still continuing. A stream processor should, informally speaking, ``suspend itself'' and wait for more data to arrive.

Constructors

EOF (Maybe SomeException) |
Chunk c |

Instances

Functor Stream | Map a function over a stream.
Typeable1 Stream |
Eq c => Eq (Stream c) |
Show c => Show (Stream c) |
Monoid c => Monoid (Stream c) |

data StreamStatus

Describe the status of a stream of data.

Constructors

DataRemaining |
EofNoError |
EofError SomeException |

Instances

Show StreamStatus |
Typeable StreamStatus |

## Exception types

module Data.Iteratee.Exception

## Iteratees

newtype Iteratee s m a

Monadic iteratee

Constructors

Iteratee |
Fields runIter :: forall r. (a -> Stream s -> m r) -> ((Stream s -> Iteratee s m a) -> Maybe SomeException -> m r) -> m r

Instances

NullPoint s => MonadTrans (Iteratee s) |
(Monad m, Nullable s) => Monad (Iteratee s m) |
(Functor m, Monad m) => Functor (Iteratee s m) |
(Functor m, Monad m, Nullable s) => Applicative (Iteratee s m) |
(MonadCatchIO m, Nullable s, NullPoint s) => MonadCatchIO (Iteratee s m) |
(MonadIO m, Nullable s, NullPoint s) => MonadIO (Iteratee s m) |

# Functions

## Control functions

run :: Monad m => Iteratee s m a -> m a

Send `EOF` to the `Iteratee` and disregard the unconsumed part of the stream. If the iteratee is in an exception state, that exception is thrown with `Control.Exception.throw`. Iteratees that do not terminate on `EOF` will throw `EofException`.

tryRun :: (Exception e, Monad m) => Iteratee s m a -> m (Either e a)

Run an iteratee, returning either the result or the iteratee exception. Note that only internal iteratee exceptions will be returned; exceptions thrown with `Control.Exception.throw` or `Control.Monad.CatchIO.throw` will not be returned.

See `IFException` for details.

mapIteratee :: (NullPoint s, Monad n, Monad m) => (m a -> n b) -> Iteratee s m a -> Iteratee s n b

Transform a computation inside an `Iteratee`.

ilift :: (Monad m, Monad n) => (forall r. m r -> n r) -> Iteratee s m a -> Iteratee s n a

Lift a computation in the inner monad of an iteratee.

A simple use would be to lift a logger iteratee to a monad stack.

     logger :: Iteratee String IO ()
     logger = mapChunksM_ putStrLn

     loggerG :: MonadIO m => Iteratee String m ()
     loggerG = ilift liftIO logger

A more complex example would involve lifting an iteratee to work with interleaved streams. See the example at `Data.Iteratee.ListLike.merge`.

ifold :: (Monad m, Monad n) => (forall r. m r -> acc -> n (r, acc)) -> acc -> Iteratee s m a -> Iteratee s n (a, acc)

Lift a computation in the inner monad of an iteratee, while threading through an accumulator.

## Creating Iteratees

idone :: Monad m => a -> Stream s -> Iteratee s m a

icont :: (Stream s -> Iteratee s m a) -> Maybe SomeException -> Iteratee s m a

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

idoneM :: Monad m => a -> Stream s -> m (Iteratee s m a)

icontM :: Monad m => (Stream s -> Iteratee s m a) -> Maybe SomeException -> m (Iteratee s m a)

## Stream Functions

setEOF :: Stream c -> SomeException

Produce the `EOF` error message. If the stream was terminated because of an error, keep the error message.

# Classes