Copyright	(c) Michael Weber <michael.weber@post.rwth-aachen.de> 2001, (c) Jeff Newbern 2003-2006, (c) Andriy Palamarchuk 2006
License	BSD-style (see the file LICENSE)
Maintainer	ross@soi.city.ac.uk
Stability	experimental
Portability	portable
Safe Haskell	Safe-Inferred
Language	Haskell98

Control.Monad.Trans.Error

Contents

The ErrorT monad transformer
Error operations
Lifting other operations
Examples

Description

This monad transformer adds the ability to fail or throw exceptions to a monad.

A sequence of actions succeeds, producing a value, only if all the actions in the sequence are successful. If one fails with an error, the rest of the sequence is skipped and the composite action fails with that error.

If the value of the error is not required, the variant in Control.Monad.Trans.Maybe may be used instead.

Synopsis

The ErrorT monad transformer

class Error a whereSource

An exception to be thrown.

Minimal complete definition: noMsg or strMsg.

Methods

noMsg :: aSource

Creates an exception without a message. The default implementation is strMsg "".

strMsg :: String -> aSource

Creates an exception with a message. The default implementation of strMsg s is noMsg.

Instances

Error IOException
ErrorList a => Error [a]	A string can be thrown as an error.

class ErrorList a whereSource

Workaround so that we can have a Haskell 98 instance Error String.

Methods

listMsg :: String -> [a]Source

Instances

ErrorList Char

newtype ErrorT e m aSource

The error monad transformer. It can be used to add error handling to other monads.

The ErrorT Monad structure is parameterized over two things:

e - The error type.
m - The inner monad.

The return function yields a successful computation, while >>= sequences two subcomputations, failing on the first error.

Constructors

ErrorT
Fields runErrorT :: m (Either e a)

Instances

Error e => MonadTrans (ErrorT e)
(Functor m, Monad m, Error e) => Alternative (ErrorT e m)
(Monad m, Error e) => Monad (ErrorT e m)
Functor m => Functor (ErrorT e m)
(MonadFix m, Error e) => MonadFix (ErrorT e m)
(Monad m, Error e) => MonadPlus (ErrorT e m)
(Functor m, Monad m) => Applicative (ErrorT e m)
Foldable f => Foldable (ErrorT e f)
Traversable f => Traversable (ErrorT e f)
(Error e, MonadIO m) => MonadIO (ErrorT e m)

mapErrorT :: (m (Either e a) -> n (Either e' b)) -> ErrorT e m a -> ErrorT e' n bSource

Map the unwrapped computation using the given function.

runErrorT (mapErrorT f m) = f (runErrorT m)

Error operations

throwError :: (Monad m, Error e) => e -> ErrorT e m aSource

Signal an error value e.

runErrorT (throwError e) = return (Left e)

```
throwError e >>= m = throwError e
```

catchError Source

Arguments

:: (Monad m, Error e)
=> ErrorT e m a	the inner computation
-> (e -> ErrorT e m a)	a handler for errors in the inner computation
-> ErrorT e m a

Handle an error.

```
catchError h (lift m) = lift m
```
```
catchError h (throwError e) = h e
```

Lifting other operations

liftCallCC :: (((Either e a -> m (Either e b)) -> m (Either e a)) -> m (Either e a)) -> ((a -> ErrorT e m b) -> ErrorT e m a) -> ErrorT e m aSource

Lift a callCC operation to the new monad.

liftListen :: Monad m => (m (Either e a) -> m (Either e a, w)) -> ErrorT e m a -> ErrorT e m (a, w)Source

Lift a listen operation to the new monad.

liftPass :: Monad m => (m (Either e a, w -> w) -> m (Either e a)) -> ErrorT e m (a, w -> w) -> ErrorT e m aSource

Lift a pass operation to the new monad.

Examples

Wrapping an IO action that can throw an error e:

 type ErrorWithIO e a = ErrorT e IO a
 ==> ErrorT (IO (Either e a))

An IO monad wrapped in StateT inside of ErrorT:

 type ErrorAndStateWithIO e s a = ErrorT e (StateT s IO) a
 ==> ErrorT (StateT s IO (Either e a))
 ==> ErrorT (StateT (s -> IO (Either e a,s)))