Throw an exception. To raise an "inner" exception following can be used:

liftT . throw
    :: (MonadCatch m, Exception e, Exception e')
    => e
    -> Throws e' (Throws e m) a

Catch exception.

To catch inner exception following construct can be used:

catch . flipT
    :: (Exception e, Exception e', MonadCatch m)
    => Throws e' (Throws e m) a
    -> (e -> Throws e' m a)
    -> Throws e' m a

Catch any exception.

Flipped version of catch. Usage example:

foo = handle exceptionHandler $ do
    ...
  where exceptionHandler = ...

Handle "inner" exception:

insideT . handle
    :: (MonadCatch m, Exception e, Exception e')
    => (e' -> m a)
    -> Throws e (Throws e' m) a
    -> Throws e m a

Flipped version of catch'

Map one exception to another.

Mapping "inner" exception has generally two forms:

1. Modifying raised exception, but not changing its type:

liftT1 . mapException
    :: (Exception e, Exception e', MonadCatch m)
    => (e -> e)
    -> Throws e' (Throws e m) a
    -> Throws e' (Throws e m) a

2. Modifying raised exception, including its type:

insideT . mapException
    :: (Exception e, Exception e1, Exception e2, MonadCatch m)
    => (e1 -> e2)
    -> Throws e (Throws e1 m) a
    -> Throws e (Throws e2 m) a

Unhiding exception by mapping it in to a different type of exception:

\f -> mapException f . liftT
    :: (Exception e, Exception e', MonadCatch m)
    => (e -> e')
    -> m a
    -> Throws e' m a

Similar to catch, but returns Either exception or result.

Inner try:

try . flipT
    :: (Exception e, Exception e', MonadCatch m)
    => Throws e' (Throws e m) a
    -> Throws e' m (Either e a)

Run computation if exception was raised. Basically:

m onException n = liftT m catch \e -> liftT n >> throw e

Same as onException, but uses catch' and so second computation is executed if any exception is raised.

Exception tag.

Construct exception tag, with type restrictions.

Reflect raised exception in function's type:

import Control.Monad.TaggedException (Throws, liftT)
import System.IO (Handle, IOMode)
import qualified System.IO as IO (openFile)


openFile :: FilePath -> IOMode -> Throws IOError IO Handle
openFile = (liftT .) . IO.openFile

Lifting m to Throws e m:

import Control.Exception (Exception)

import Control.Monad.TaggedException (Throws, liftT, throw)
import Data.Typeable (Typeable)


data EmptyString = EmptyString
    deriving (Show, Typeable)

instance Exception EmptyString

writeIfNotEmpty
    :: FilePath
    -> String
    -> Throws EmptyString IO ()
writeIfNotEmpty filename str = do
    when (null str) $ throw EmptyString
    liftT $ writeFile filename str

We have a some commonly used patterns:

(liftT .)
    :: (Exception e, MonadThrow m)
    => (a -> m b)
    -> a -> Throws e m b

Above is also usable for lifting throw-like functions:

import Control.Monad.Trans.Class (MonadTrans(lift))

((liftT . lift) .)
    ::  ( Exception e
        , MonadThrow m
        , MonadThrow (t m)
        , MonadTrans t)
    => (a -> m b)
    -> a -> Throws e (t m) b

Shorthand for liftT . liftT.

Shorthand for liftT . liftT . liftT.

liftT for functions with arity one.

liftT for functions with arity two.

liftT for functions with arity three.

Join two outermost exception tags.

Join three outermost exception tags.

Flip two outermost exception tags.

Generalized liftT. Usage examples:

insideT lift
   :: (MonadThrow (t m), MonadThrow m, Exception e, MonadTrans t)
   => Throws e m b
   -> Throws e (t m) b

This is variation on the first example that explicitly lifts monad:

insideT WriterT :: (Exception e, MonadThrow m, Monoid w) => Throws e m (b, w) -> Throws e (WriterT w m) b

Some useful compositions of exception tag combinators:

insideT flipT
    :: (Exception e0, Exception e1, Exception e2, MonadThrow m)
    => Throws e0 (Throws e1 (Throws e2 m)) a
    -> Throws e0 (Throws e2 (Throws e1 m)) a

flipT . insideT flipT
    :: (Exception e0, Exception e1, Exception e2, MonadThrow m)
    => Throws e0 (Throws e1 (Throws e2 m)) a
    -> Throws e2 (Throws e0 (Throws e1 m)) a

Generalized liftT2.

Generalized liftT3.

Variant of insideT.

Usage example:

insideTf StateT
    :: (Exception e, MonadThrow m)
    => (s -> Throws e m (a, s))
    -> Throws e (StateT s m) a

Variant of insideT.

Usage example:

insideTf2 RWST
    :: (Exception e, MonadThrow m)
    => (r -> s -> Throws e m (a, s, w))
    -> Throws e (RWST r w s m) a

Since 1.2.0.0