-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A 'FailT' monad transformer that plays well with 'MonadFail'
--
-- Fail gracefully when stuck in a MonadFail
--
--
-- >>> runFailT (fail "Failure!?" >> pure "Success!!")
-- Left "Failure!?"
--
-- >>> runFailT (fail "Failure!?" <|> pure "Success!!")
-- Right "Success!!"
--
-- >>> runFailT (pure ["Success!!"] <> fail "Failure!?" <> pure ["At", "Last!"])
-- Right ["Success!!","At","Last!"]
--
@package FailT
@version 0.1.2.0
module Control.Monad.Trans.Fail
-- | FailT transformer with Identity as the base monad.
type Fail e = FailT e Identity
-- | Unwrap the pure Fail monad and reveal the underlying result of
-- monadic computation.
--
--
-- >>> runFail (fail "Something went wrong") :: Either String ()
-- Left "Something went wrong"
--
-- >>> runFail (failT "Something went wrong" >> pure ())
-- Left "Something went wrong"
--
-- >>> import Control.Applicative
--
-- >>> runFail (failT "Something could have gone wrong" <|> pure ())
-- Right ()
--
--
-- All errors accrued during the monadic computation will be combined
-- using the Semigroup instance and delimited by a comma:
--
--
-- >>> runFail (fail "One thing went wrong" <|> fail "Another thing went wrong") :: Either String ()
-- Left "One thing went wrong, Another thing went wrong"
--
--
-- Failing with one of instances functions mempty or empty
-- will yield a no-reason error report:
--
--
-- >>> runFail mempty :: Either String ()
-- Left "No failure reason given"
--
runFail :: (IsString e, Semigroup e) => Fail e a -> Either e a
-- | This is a variant of runFailAgg where only the error reported
-- for the very last failed computation will be produced and others
-- discarded. This is useful when it is not relevant to retain
-- information about all the attempts and only the last one matters, eg.
-- parsing with backtracking.
runFailLast :: IsString e => Fail e a -> Either e a
-- | Convert a Fail monad computation in an Either, where the
-- Left will contain all failures in the same order they where
-- received, or Right upon a successful computation.
--
--
-- >>> runFailAgg (fail "One bad thing" <|> fail "Another bad thing") :: Either [String] ()
-- Left ["One bad thing","Another bad thing"]
--
-- >>> runFailAgg (fail "A bad thing" <|> pure "A good thing") :: Either [String] String
-- Right "A good thing"
--
runFailAgg :: Fail e a -> Either [e] a
-- | Throw an error if there was a failure, otherwise return the result of
-- computation. Use throwFailT in case you'd like to handle an
-- actual exception in some other underlying monad.
--
--
-- >>> errorFail (fail "This didn't work" :: Fail String ())
-- *** Exception: "This didn't work"
-- CallStack (from HasCallStack):
-- ...
--
-- >>> errorFail (fail "This didn't work" <|> pure "That Worked" :: Fail String String)
-- "That Worked"
--
errorFail :: (Show e, HasCallStack) => Fail e a -> a
-- | Same as errorFail, but without the stack trace:
--
--
-- >>> errorFailWithoutStackTrace (fail "This didn't work" :: Fail String ())
-- *** Exception: "This didn't work"
--
-- >>> errorFailWithoutStackTrace (fail "This didn't work" <|> pure "That Worked" :: Fail String String)
-- "That Worked"
--
errorFailWithoutStackTrace :: Show e => Fail e a -> a
-- | Fail monad transformer that plays well with MonadFail type
-- class.
newtype FailT e m a
FailT :: m (Either [e] a) -> FailT e m a
-- | An exception that is produced by the FailT monad transformer.
data FailException
[FailException] :: (Typeable e, Show e) => [e] -> CallStack -> FailException
-- | Similar to fail, but it is not restricted to String.
failT :: Applicative m => e -> FailT e m a
-- | Similar to failT, but accepts a list of failures.
--
--
-- runFailAgg (foldMap failT (xs :: [String])) == runFailAgg (failManyT xs)
--
failManyT :: Applicative m => [e] -> FailT e m a
-- | Similar to runFail, except underlying monad is not restricted
-- to Identity.
--
-- Unwrap the FailT monad transformer and produce an action that
-- can be executed in the underlying monad and, which will produce either
-- a comma delimited error message upon a failure or the result
-- otherwise.
--
--
-- >>> runFailT (failT "Could have failed" <|> liftIO (putStrLn "Nothing went wrong"))
-- Nothing went wrong
-- Right ()
--
runFailT :: (IsString e, Semigroup e, Functor m) => FailT e m a -> m (Either e a)
-- | Similar to runFailLast, except underlying monad is not
-- restricted to Identity.
runFailLastT :: (IsString e, Functor m) => FailT e m a -> m (Either e a)
-- | Similar to runFailAgg, except underlying monad is not
-- restricted to Identity.
runFailAggT :: FailT e m a -> m (Either [e] a)
-- | Change the underlying monad with the hoisting function.
hoistFailT :: (forall a. m a -> n a) -> FailT e m b -> FailT e n b
-- | Map a function over the underlying representation of the FailT
-- monad.
mapFailT :: (m (Either [e] a) -> n (Either [e] b)) -> FailT e m a -> FailT e n b
-- | Map a function over the error type in the FailT monad.
mapErrorFailT :: Functor m => (e -> e') -> FailT e m a -> FailT e' m a
-- | Map a function over the aggregation of errors in the FailT
-- monad. Could be used for example for clearing our all of the
-- aggregated error messages:
--
--
-- >>> runFail (mapErrorsFailT (const []) $ failT "Something went wrong") :: Either String ()
-- Left "No failure reason given"
--
mapErrorsFailT :: Functor m => ([e] -> [e']) -> FailT e m a -> FailT e' m a
-- | Convert a FailT computation into an ExceptT.
--
--
-- >>> exceptFailT (fail "A bad thing" >> pure () :: Fail String ())
-- ExceptT (Identity (Left FailException
-- "A bad thing"
-- CallStack (from HasCallStack):
-- ...
--
exceptFailT :: (HasCallStack, Typeable e, Show e, Monad m) => FailT e m a -> ExceptT FailException m a
-- | Same as exceptFailT, but works with any MonadError.
--
--
-- >>> throwErrorFailT (fail "A bad thing" >> pure () :: FailT String (Except FailException) ())
-- ExceptT (Identity (Left FailException
-- "A bad thing"
-- CallStack (from HasCallStack):
-- ...
--
throwErrorFailT :: (HasCallStack, Typeable e, Show e, MonadError FailException m) => FailT e m a -> m a
-- | Use the MonadThrow instance to raise a FailException in
-- the underlying monad.
--
--
-- >>> throwFailT (failT "One thing went wrong")
-- *** Exception: FailException
-- "One thing went wrong"
-- ...
--
-- >>> throwFailT (failT "One thing went wrong") :: Maybe ()
-- Nothing
--
throwFailT :: (HasCallStack, Typeable e, Show e, MonadThrow m) => FailT e m a -> m a
-- | Lift a catchE operation to the new monad.
liftCatch :: (m (Either [e] a) -> (e -> m (Either [e] a)) -> m (Either [e] a)) -> FailT e m a -> (e -> FailT e m a) -> FailT e m a
-- | Lift a listen operation to the new monad.
liftListen :: Monad m => (m (Either [e] a) -> m (Either [e] a, w)) -> FailT e m a -> FailT e m (a, w)
-- | Lift a pass operation to the new monad.
liftPass :: Monad m => (m (Either [e] a, w -> w) -> m (Either [e] a)) -> FailT e m (a, w -> w) -> FailT e m a
instance GHC.Show.Show Control.Monad.Trans.Fail.FailException
instance GHC.Exception.Type.Exception Control.Monad.Trans.Fail.FailException
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Trans.Fail.FailT e m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Trans.Fail.FailT e m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trans.Fail.FailT e m)
instance (Data.String.IsString e, GHC.Base.Monad m) => Control.Monad.Fail.MonadFail (Control.Monad.Trans.Fail.FailT e m)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Monad.Trans.Fail.FailT e f)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Monad.Trans.Fail.FailT e f)
instance GHC.Base.Monad m => GHC.Base.Alternative (Control.Monad.Trans.Fail.FailT e m)
instance (GHC.Base.Monad m, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Control.Monad.Trans.Fail.FailT e m a)
instance (GHC.Base.Monad m, GHC.Base.Semigroup a) => GHC.Base.Monoid (Control.Monad.Trans.Fail.FailT e m a)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Trans.Fail.FailT e)
instance Control.Monad.Zip.MonadZip m => Control.Monad.Zip.MonadZip (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Trans.Fail.FailT e m)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Monad.Trans.Fail.FailT e f)
instance (GHC.Classes.Eq e, Data.Functor.Classes.Eq1 m) => Data.Functor.Classes.Eq1 (Control.Monad.Trans.Fail.FailT e m)
instance (GHC.Classes.Ord e, Data.Functor.Classes.Ord1 m) => Data.Functor.Classes.Ord1 (Control.Monad.Trans.Fail.FailT e m)
instance (GHC.Read.Read e, Data.Functor.Classes.Read1 m) => Data.Functor.Classes.Read1 (Control.Monad.Trans.Fail.FailT e m)
instance (GHC.Show.Show e, Data.Functor.Classes.Show1 m) => Data.Functor.Classes.Show1 (Control.Monad.Trans.Fail.FailT e m)
instance (GHC.Classes.Eq e, Data.Functor.Classes.Eq1 m, GHC.Classes.Eq a) => GHC.Classes.Eq (Control.Monad.Trans.Fail.FailT e m a)
instance (GHC.Classes.Ord e, Data.Functor.Classes.Ord1 m, GHC.Classes.Ord a) => GHC.Classes.Ord (Control.Monad.Trans.Fail.FailT e m a)
instance (GHC.Read.Read e, Data.Functor.Classes.Read1 m, GHC.Read.Read a) => GHC.Read.Read (Control.Monad.Trans.Fail.FailT e m a)
instance (GHC.Show.Show e, Data.Functor.Classes.Show1 m, GHC.Show.Show a) => GHC.Show.Show (Control.Monad.Trans.Fail.FailT e m a)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.RWS.Class.MonadRWS r w s m => Control.Monad.RWS.Class.MonadRWS r w s (Control.Monad.Trans.Fail.FailT e m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Fail.FailT e m)
-- | This module contains a synonym for FailT e m a
-- transformer, where failure type e is restricted to
-- String. All functions in this module have the
-- same names and are a drop-in replacement for
-- Control.Monad.Trans.Fail module, except with monomorphic
-- failure type.
module Control.Monad.Trans.Fail.String
-- | Version of Fail restricted to String
type Fail = Fail String
-- | Version of runFail restricted to String
runFail :: Fail a -> Either String a
-- | Version of runFailLast restricted to String
runFailLast :: Fail a -> Either String a
-- | Version of runFailAgg restricted to String
runFailAgg :: Fail a -> Either [String] a
-- | Version of errorFail restricted to String
--
-- Throw an error if there was a failure, otherwise return the result of
-- monadic computation. Use throwFailT in case you'd like to
-- handle an actual exception.
errorFail :: HasCallStack => Fail a -> a
-- | Version of runFail restricted to String
--
-- Same as errorFail, but without the stack trace:
--
--
-- >>> errorFailWithoutStackTrace (fail "This didn't work" :: Fail ())
-- *** Exception: "This didn't work"
--
-- >>> import Control.Applicative
--
-- >>> errorFailWithoutStackTrace (fail "This didn't work" <|> pure "That Worked" :: Fail String)
-- "That Worked"
--
errorFailWithoutStackTrace :: Fail a -> a
-- | Version of FailT restricted to String
--
-- Fail monad transformer that plays well with MonadFail
type FailT = FailT String
-- | An exception that is produced by the FailT monad transformer.
data FailException
[FailException] :: (Typeable e, Show e) => [e] -> CallStack -> FailException
-- | Version of failT restricted to String
--
-- Monomorphic synonym for fail
failT :: Applicative m => String -> FailT m a
-- | Version of failManyT restricted to String
--
--
-- runFailAgg (foldMap failT xs) == runFailAgg (failManyT xs)
--
failManyT :: Applicative m => [String] -> FailT m a
-- | Version of runFailT restricted to String
runFailT :: Functor m => FailT m a -> m (Either String a)
-- | Version of runFailLastT restricted to String
runFailLastT :: Functor m => FailT m a -> m (Either String a)
-- | Version of runFailAggT restricted to String
runFailAggT :: FailT m a -> m (Either [String] a)
-- | Version of hoistFailT restricted to String
--
-- Change the underlying monad with the hoisting function
hoistFailT :: (forall a. m a -> n a) -> FailT m b -> FailT n b
-- | Version of mapFailT restricted to String
--
-- Map a function over the underlying representation of the FailT
-- monad.
mapFailT :: (m (Either [String] a) -> n (Either [String] b)) -> FailT m a -> FailT n b
-- | Version of mapErrorFail, where resulting type is restricted to
-- String
--
-- Map a function over the error type in the FailT monad.
mapErrorFailT :: Functor m => (e -> String) -> FailT e m a -> FailT m a
-- | Version of mapErrorsFail, where resulting type is restricted to
-- String
--
-- Map a function over the aggregation of errors in the FailT
-- monad. Could be used for example for clearing our all of the
-- aggregated error messages:
--
--
-- >>> runFail (mapErrorsFailT (const []) $ failT "Something went wrong") :: Either String ()
-- Left "No failure reason given"
--
mapErrorsFailT :: Functor m => ([e] -> [String]) -> FailT e m a -> FailT m a
-- | Version of exceptFailT restricted to String
exceptFailT :: (HasCallStack, Monad m) => FailT m a -> ExceptT FailException m a
-- | Version of throwErrorFailT restricted to String
--
-- Same as exceptFailT, but works with any MonadError.
--
--
-- >>> import Control.Monad.Trans.Fail.String
--
-- >>> throwErrorFailT (fail "A bad thing" >> pure () :: FailT (Except FailException) ())
-- ExceptT (Identity (Left FailException
-- "A bad thing"
-- CallStack (from HasCallStack):
-- ...
--
throwErrorFailT :: (HasCallStack, MonadError FailException m) => FailT m a -> m a
-- | Version of throwFailT restricted to String
throwFailT :: (HasCallStack, MonadThrow m) => FailT m a -> m a
-- | This module contains a synonym for FailT e m a
-- transformer, where failure type e is restricted to
-- Text. All functions in this module have the
-- same names and are a drop-in replacement for
-- Control.Monad.Trans.Fail module, except with monomorphic
-- failure type.
module Control.Monad.Trans.Fail.Text
-- | Version of Fail restricted to Text
type Fail = Fail Text
-- | Version of runFail restricted to Text
runFail :: Fail a -> Either Text a
-- | Version of runFailLast restricted to Text
runFailLast :: Fail a -> Either Text a
-- | Version of runFailAgg restricted to Text
runFailAgg :: Fail a -> Either [Text] a
-- | Version of errorFail restricted to Text
--
-- Throw an error if there was a failure, otherwise return the result of
-- monadic computation. Use throwFailT in case you'd like to
-- handle an actual exception.
errorFail :: HasCallStack => Fail a -> a
-- | Version of errorFailWithoutStackTrace restricted to Text
--
-- Same as errorFail, but without the stack trace:
--
--
-- >>> errorFailWithoutStackTrace (fail "This didn't work" :: Fail ())
-- *** Exception: "This didn't work"
--
-- >>> import Control.Applicative
--
-- >>> errorFailWithoutStackTrace (fail "This didn't work" <|> pure "That Worked" :: Fail String)
-- "That Worked"
--
errorFailWithoutStackTrace :: Fail a -> a
-- | Version of FailT restricted to Text
--
-- Fail monad transformer that plays well with MonadFail
type FailT = FailT Text
-- | An exception that is produced by the FailT monad transformer.
data FailException
[FailException] :: (Typeable e, Show e) => [e] -> CallStack -> FailException
-- | Version of failT restricted to Text
--
-- Monomorphic synonym for fail
failT :: Applicative m => Text -> FailT m a
-- | Version of failManyT restricted to Text
failManyT :: Applicative m => [Text] -> FailT m a
-- | Version of runFailT restricted to Text
runFailT :: Functor m => FailT m a -> m (Either Text a)
-- | Version of runFailLastT restricted to Text
runFailLastT :: Functor m => FailT m a -> m (Either Text a)
-- | Version of runFailAggT restricted to Text
runFailAggT :: FailT m a -> m (Either [Text] a)
-- | Version of hoistFailT restricted to Text
--
-- Change the underlying monad with the hoisting function
hoistFailT :: (forall a. m a -> n a) -> FailT m b -> FailT n b
-- | Version of mapFailT restricted to Text
--
-- Map a function over the underlying representation of the FailT
-- monad.
mapFailT :: (m (Either [Text] a) -> n (Either [Text] b)) -> FailT m a -> FailT n b
-- | Version of mapErrorFailT where resulting type is restricted to
-- Text
--
-- Map a function over the error type in the FailT monad.
mapErrorFailT :: Functor m => (e -> Text) -> FailT e m a -> FailT m a
-- | Version of mapErrorsFail, where resulting type is restricted to
-- Text
--
-- Map a function over the aggregation of errors in the FailT
-- monad. Could be used for example for clearing our all of the
-- aggregated error messages:
--
--
-- >>> runFail (mapErrorsFailT (const [] :: [Text] -> [Text]) $ fail "Something went wrong" >> pure ())
-- Left "No failure reason given"
--
mapErrorsFailT :: Functor m => ([e] -> [Text]) -> FailT e m a -> FailT m a
-- | Version of exceptFailT restricted to Text
exceptFailT :: (HasCallStack, Monad m) => FailT m a -> ExceptT FailException m a
-- | Version of throwErrorFailT restricted to Text
--
-- Same as exceptFailT, but works with any MonadError.
--
--
-- >>> import Control.Monad.Trans.Fail.Text
--
-- >>> throwErrorFailT (fail "A bad thing" >> pure () :: FailT (Except FailException) ())
-- ExceptT (Identity (Left FailException
-- "A bad thing"
-- CallStack (from HasCallStack):
-- ...
--
throwErrorFailT :: (HasCallStack, MonadError FailException m) => FailT m a -> m a
-- | Version of throwFailT restricted to Text
throwFailT :: (HasCallStack, MonadThrow m) => FailT m a -> m a