------------------------------------------------------------------------------
-- |
-- Module      : PhatSort.Monad.Trans.Error
-- Description : error monad transformer
-- Copyright   : Copyright (c) 2019-2022 Travis Cardwell
-- License     : MIT
------------------------------------------------------------------------------

module PhatSort.Monad.Trans.Error
  ( -- * ErrorT
    ErrorT
    -- * API
  , errorT
  , errorTE
  , lift
  , liftEither
  , liftEitherE
  , run
  , throw
  , throwE
  ) where

-- https://hackage.haskell.org/package/base
import Control.Exception (Exception(displayException))
import Data.Bifunctor (first)

-- https://hackage.haskell.org/package/transformers
import qualified Control.Monad.Trans.Except as Except
import Control.Monad.Trans.Except (ExceptT(ExceptT))
import qualified Control.Monad.Trans.Class as Trans

------------------------------------------------------------------------------
-- $ErrorT

-- | Transformer used to manage errors: 'ExceptT' 'String'
--
-- @since 0.5.0.0
type ErrorT = ExceptT String

------------------------------------------------------------------------------
-- $API

-- | Manage 'String' errors of an action
--
-- @since 0.5.0.0
errorT
  :: Monad m
  => m (Either String a)
  -> ErrorT m a
errorT :: m (Either String a) -> ErrorT m a
errorT = m (Either String a) -> ErrorT m a
forall e (m :: * -> *) a. m (Either e a) -> ExceptT e m a
ExceptT
{-# INLINE errorT #-}

------------------------------------------------------------------------------

-- | Manage 'Exception' errors of an action
--
-- @since 0.5.0.0
errorTE
  :: (Exception e, Monad m)
  => m (Either e a)
  -> ErrorT m a
errorTE :: m (Either e a) -> ErrorT m a
errorTE = m (Either String a) -> ErrorT m a
forall e (m :: * -> *) a. m (Either e a) -> ExceptT e m a
ExceptT (m (Either String a) -> ErrorT m a)
-> (m (Either e a) -> m (Either String a))
-> m (Either e a)
-> ErrorT m a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Either e a -> Either String a)
-> m (Either e a) -> m (Either String a)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((e -> String) -> Either e a -> Either String a
forall (p :: * -> * -> *) a b c.
Bifunctor p =>
(a -> b) -> p a c -> p b c
first e -> String
forall e. Exception e => e -> String
displayException)
{-# INLINE errorTE #-}

------------------------------------------------------------------------------

-- | Lift an action without errors
--
-- @since 0.5.0.0
lift
  :: Monad m
  => m a
  -> ErrorT m a
lift :: m a -> ErrorT m a
lift = m a -> ErrorT m a
forall (t :: (* -> *) -> * -> *) (m :: * -> *) a.
(MonadTrans t, Monad m) =>
m a -> t m a
Trans.lift
{-# INLINE lift #-}

------------------------------------------------------------------------------

-- | Manage 'String' errors
--
-- @since 0.5.0.0
liftEither
  :: Monad m
  => Either String a
  -> ErrorT m a
liftEither :: Either String a -> ErrorT m a
liftEither = m (Either String a) -> ErrorT m a
forall e (m :: * -> *) a. m (Either e a) -> ExceptT e m a
ExceptT (m (Either String a) -> ErrorT m a)
-> (Either String a -> m (Either String a))
-> Either String a
-> ErrorT m a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Either String a -> m (Either String a)
forall (f :: * -> *) a. Applicative f => a -> f a
pure
{-# INLINE liftEither #-}

------------------------------------------------------------------------------

-- | Manage 'Exception' errors
--
-- @since 0.5.0.0
liftEitherE
  :: (Exception e, Monad m)
  => Either e a
  -> ErrorT m a
liftEitherE :: Either e a -> ErrorT m a
liftEitherE = m (Either String a) -> ErrorT m a
forall e (m :: * -> *) a. m (Either e a) -> ExceptT e m a
ExceptT (m (Either String a) -> ErrorT m a)
-> (Either e a -> m (Either String a)) -> Either e a -> ErrorT m a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Either String a -> m (Either String a)
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Either String a -> m (Either String a))
-> (Either e a -> Either String a)
-> Either e a
-> m (Either String a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (e -> String) -> Either e a -> Either String a
forall (p :: * -> * -> *) a b c.
Bifunctor p =>
(a -> b) -> p a c -> p b c
first e -> String
forall e. Exception e => e -> String
displayException
{-# INLINE liftEitherE #-}

------------------------------------------------------------------------------

-- | Run the transformer
--
-- @since 0.5.0.0
run
  :: Monad m
  => ErrorT m a
  -> m (Either String a)
run :: ErrorT m a -> m (Either String a)
run = ErrorT m a -> m (Either String a)
forall e (m :: * -> *) a. ExceptT e m a -> m (Either e a)
Except.runExceptT
{-# INLINE run #-}

------------------------------------------------------------------------------

-- | Throw a 'String' error
--
-- @since 0.5.0.0
throw
  :: Monad m
  => String
  -> ErrorT m a
throw :: String -> ErrorT m a
throw = String -> ErrorT m a
forall (m :: * -> *) e a. Monad m => e -> ExceptT e m a
Except.throwE
{-# INLINE throw #-}

------------------------------------------------------------------------------

-- | Throw an 'Exception' error
--
-- @since 0.5.0.0
throwE
  :: (Exception e, Monad m)
  => e
  -> ErrorT m a
throwE :: e -> ErrorT m a
throwE = String -> ErrorT m a
forall (m :: * -> *) e a. Monad m => e -> ExceptT e m a
Except.throwE (String -> ErrorT m a) -> (e -> String) -> e -> ErrorT m a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. e -> String
forall e. Exception e => e -> String
displayException
{-# INLINE throwE #-}