errors-2.1.3: Simplified error-handling

Safe Haskell | Safe
Language | Haskell98

Data.EitherR

Contents

- EitherR
  - Operations in the EitherR monad
  - Conversions to the Either monad
  - Flip alternative
- ExceptRT
  - Operations in the ExceptRT monad
  - Conversions to the ExceptT monad
  - Flip alternative

Description

This module provides `throwEither` and `catchEither` for `Either`. These two functions reside here because `throwEither` and `catchEither` correspond to `return` and (`>>=`) for the flipped `Either` monad: `EitherR`. Additionally, this module defines `handleE` as the flipped version of `catchE` for `ExceptT`.

`throwEither` and `catchEither` improve upon `MonadError` because:

- `catchEither` is more general than `catch` and allows you to change the left value's type
- Both are Haskell98

More advanced users can use `EitherR` and `ExceptRT` to program in an entirely symmetric "success monad" where exceptional results are the norm and successful results terminate the computation. This allows you to chain error-handlers using `do` notation and pass around exceptional values of varying types until you can finally recover from the error:

    runExceptRT $ do
        e2   <- ioExceptionHandler e1
        bool <- arithmeticExceptionhandler e2
        when bool $ lift $ putStrLn "DEBUG: Arithmetic handler did something"

If any of the above error handlers `succeed`, no other handlers are tried.

If you choose not to typefully distinguish between the error and sucess monad, then use `flipEither` and `flipET`, which swap the type variables without changing the type.

Synopsis

- newtype EitherR r e = EitherR {
  - runEitherR :: Either e r
  }
- succeed :: r -> EitherR r e
- throwEither :: e -> Either e r
- catchEither :: Either a r -> (a -> Either b r) -> Either b r
- handleEither :: (a -> Either b r) -> Either a r -> Either b r
- fmapL :: (a -> b) -> Either a r -> Either b r
- flipEither :: Either a b -> Either b a
- newtype ExceptRT r m e = ExceptRT {
  - runExceptRT :: ExceptT e m r
  }
- succeedT :: Monad m => r -> ExceptRT r m e
- handleE :: Monad m => (a -> ExceptT b m r) -> ExceptT a m r -> ExceptT b m r
- fmapLT :: Functor m => (a -> b) -> ExceptT a m r -> ExceptT b m r
- flipET :: Monad m => ExceptT a m b -> ExceptT b m a

# EitherR

newtype EitherR r e #

If "`Either e r`" is the error monad, then "`EitherR r e`" is the corresponding success monad, where:

- `return` is `throwEither`.
- (`>>=`) is `catchEither`.
- Successful results abort the computation

Constructors

EitherR |
Fields runEitherR :: Either e r

Instances

Monad (EitherR r) # |
Methods (>>=) :: EitherR r a -> (a -> EitherR r b) -> EitherR r b # (>>) :: EitherR r a -> EitherR r b -> EitherR r b # return :: a -> EitherR r a # fail :: String -> EitherR r a #
Functor (EitherR r) # |
Methods fmap :: (a -> b) -> EitherR r a -> EitherR r b # (<$) :: a -> EitherR r b -> EitherR r a #
Applicative (EitherR r) # |
Methods pure :: a -> EitherR r a # (<*>) :: EitherR r (a -> b) -> EitherR r a -> EitherR r b # (*>) :: EitherR r a -> EitherR r b -> EitherR r b # (<*) :: EitherR r a -> EitherR r b -> EitherR r a #
Monoid r => Alternative (EitherR r) # |
Methods empty :: EitherR r a # (<|>) :: EitherR r a -> EitherR r a -> EitherR r a # some :: EitherR r a -> EitherR r [a] # many :: EitherR r a -> EitherR r [a] #
Monoid r => MonadPlus (EitherR r) # |
Methods mzero :: EitherR r a # mplus :: EitherR r a -> EitherR r a -> EitherR r a #

## Operations in the EitherR monad

succeed :: r -> EitherR r e #

Complete error handling, returning a result

## Conversions to the Either monad

throwEither :: e -> Either e r #

`throwEither` in the error monad corresponds to `return` in the success monad

catchEither :: Either a r -> (a -> Either b r) -> Either b r #

`catchEither` in the error monad corresponds to (`>>=`) in the success monad

handleEither :: (a -> Either b r) -> Either a r -> Either b r #

`catchEither` with the arguments flipped

fmapL :: (a -> b) -> Either a r -> Either b r #

Map a function over the `Left` value of an `Either`

## Flip alternative

flipEither :: Either a b -> Either b a #

Flip the type variables of `Either`

# ExceptRT

newtype ExceptRT r m e #

`EitherR` converted into a monad transformer

Constructors

ExceptRT |
Fields runExceptRT :: ExceptT e m r

Instances

MonadTrans (ExceptRT r) # |
Methods lift :: Monad m => m a -> ExceptRT r m a #
Monad m => Monad (ExceptRT r m) # |
Methods (>>=) :: ExceptRT r m a -> (a -> ExceptRT r m b) -> ExceptRT r m b # (>>) :: ExceptRT r m a -> ExceptRT r m b -> ExceptRT r m b # return :: a -> ExceptRT r m a # fail :: String -> ExceptRT r m a #
Monad m => Functor (ExceptRT r m) # |
Methods fmap :: (a -> b) -> ExceptRT r m a -> ExceptRT r m b # (<$) :: a -> ExceptRT r m b -> ExceptRT r m a #
Monad m => Applicative (ExceptRT r m) # |
Methods pure :: a -> ExceptRT r m a # (<*>) :: ExceptRT r m (a -> b) -> ExceptRT r m a -> ExceptRT r m b # (*>) :: ExceptRT r m a -> ExceptRT r m b -> ExceptRT r m b # (<*) :: ExceptRT r m a -> ExceptRT r m b -> ExceptRT r m a #
MonadIO m => MonadIO (ExceptRT r m) # |
Methods liftIO :: IO a -> ExceptRT r m a #
(Monad m, Monoid r) => Alternative (ExceptRT r m) # |
Methods empty :: ExceptRT r m a # (<|>) :: ExceptRT r m a -> ExceptRT r m a -> ExceptRT r m a # some :: ExceptRT r m a -> ExceptRT r m [a] # many :: ExceptRT r m a -> ExceptRT r m [a] #
(Monad m, Monoid r) => MonadPlus (ExceptRT r m) # |
Methods mzero :: ExceptRT r m a # mplus :: ExceptRT r m a -> ExceptRT r m a -> ExceptRT r m a #

## Operations in the ExceptRT monad

succeedT :: Monad m => r -> ExceptRT r m e #

Complete error handling, returning a result

## Conversions to the ExceptT monad

handleE :: Monad m => (a -> ExceptT b m r) -> ExceptT a m r -> ExceptT b m r #

`catchT` with the arguments flipped

fmapLT :: Functor m => (a -> b) -> ExceptT a m r -> ExceptT b m r #

Map a function over the `Left` value of an `ExceptT`

## Flip alternative

flipET :: Monad m => ExceptT a m b -> ExceptT b m a #

Flip the type variables of an `ExceptT`