Copyright | (c) 2012--2014 The University of Kansas |
---|---|

License | BSD3 |

Maintainer | Neil Sculthorpe <neil@ittc.ku.edu> |

Stability | beta |

Portability | ghc |

Safe Haskell | Safe-Inferred |

Language | Haskell2010 |

This module provides classes for catch-like operations on `Monad`

s.

- class Monad m => MonadCatch m where
- data KureM a
- runKureM :: (a -> b) -> (String -> b) -> KureM a -> b
- fromKureM :: (String -> a) -> KureM a -> a
- liftKureM :: Monad m => KureM a -> m a
- liftAndCatchIO :: (MonadCatch m, MonadIO m) => IO a -> m a
- (<+) :: MonadCatch m => m a -> m a -> m a
- catchesM :: (Foldable f, MonadCatch m) => f (m a) -> m a
- tryM :: MonadCatch m => a -> m a -> m a
- mtryM :: (MonadCatch m, Monoid a) => m a -> m a
- attemptM :: MonadCatch m => m a -> m (Either String a)
- testM :: MonadCatch m => m a -> m Bool
- notM :: MonadCatch m => m a -> m ()
- modFailMsg :: MonadCatch m => (String -> String) -> m a -> m a
- setFailMsg :: MonadCatch m => String -> m a -> m a
- prefixFailMsg :: MonadCatch m => String -> m a -> m a
- withPatFailMsg :: MonadCatch m => String -> m a -> m a

# Monads with a Catch

class Monad m => MonadCatch m where Source

`Monad`

s with a catch for `fail`

.
The following laws are expected to hold:

fail msg `catchM` f == f msg return a `catchM` f == return a

MonadCatch IO | The String is generated by |

MonadCatch KureM | |

MonadCatch m => MonadCatch (OneR m) | |

MonadCatch m => MonadCatch (AnyR m) | |

Typeable ((* -> *) -> Constraint) MonadCatch | |

MonadCatch m => MonadCatch (Transform * c m a) | Lifting through a Reader transformer, where (c,a) is the read-only environment. |

## The KURE Monad

`KureM`

is the minimal structure that can be an instance of `MonadCatch`

.
The KURE user is free to either use `KureM`

or provide their own monad.
`KureM`

is essentially the same as `Either`

`String`

, except that it supports a `MonadCatch`

instance which `Either`

`String`

does not (because its `fail`

method calls `error`

)
A major advantage of this is that monadic pattern match failures are caught safely.

fromKureM :: (String -> a) -> KureM a -> a Source

Get the value from a `KureM`

, providing a function to handle the error case.

## The IO Monad

liftAndCatchIO :: (MonadCatch m, MonadIO m) => IO a -> m a Source

Lift a computation from the `IO`

monad, catching failures in the target monad.

## Combinators

(<+) :: MonadCatch m => m a -> m a -> m a infixl 3 Source

A monadic catch that ignores the error message.

catchesM :: (Foldable f, MonadCatch m) => f (m a) -> m a Source

Select the first monadic computation that succeeds, discarding any thereafter.

tryM :: MonadCatch m => a -> m a -> m a Source

Catch a failing monadic computation, making it succeed with a constant value.

mtryM :: (MonadCatch m, Monoid a) => m a -> m a Source

Catch a failing monadic computation, making it succeed with `mempty`

.

attemptM :: MonadCatch m => m a -> m (Either String a) Source

Catch a failing monadic computation, making it succeed with an error message.

testM :: MonadCatch m => m a -> m Bool Source

Determine if a monadic computation succeeds.

notM :: MonadCatch m => m a -> m () Source

Fail if the monadic computation succeeds; succeed with `()`

if it fails.

modFailMsg :: MonadCatch m => (String -> String) -> m a -> m a Source

Modify the error message of a failing monadic computation. Successful computations are unaffected.

setFailMsg :: MonadCatch m => String -> m a -> m a Source

Set the error message of a failing monadic computation. Successful computations are unaffected.

prefixFailMsg :: MonadCatch m => String -> m a -> m a Source

Add a prefix to the error message of a failing monadic computation. Successful computations are unaffected.

withPatFailMsg :: MonadCatch m => String -> m a -> m a Source

Use the given error message whenever a monadic pattern match failure occurs.