-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A 'Failable' error monad class to unify failure across monads that can fail
--   
--   This library contains a <a>Failable</a> error monad class to unify
--   failure across monads and transformers most commonly used to implement
--   pipelines that can fail and does so in a simple nonsense way by
--   providing the means of signaling a computation "failure" while
--   striving to keep the failure behaviour consistent with the actual
--   definition of the monad/transformer. Please refer to the README file
--   for a more elaborate description and some examples.
@package failable
@version 1.2.0.0


-- | This library provides a <a>Failable</a> error monad class to unify
--   errors across monads and transformers most commonly used to implement
--   pipelines that can fail.
module Control.Monad.Failable

-- | The <a>Failable</a> class. A Monad which is an instance of this class
--   can be used as a context in a function running in one with this class
--   constraint, in order to report error conditions
class (Monad m) => Failable m

-- | trigger a failure. It takes an exception value as argument and it
--   returns whatever might be used to abort a monadic computation in the
--   monad instantiating this class.
failure :: (Failable m, Exception e) => e -> m a

-- | recover from a possible failure. Basically a generalized
--   <tt>catch</tt> for a <tt>Failable</tt>.
recover :: (Failable m, e ~ SomeException) => m a -> (e -> m a) -> m a

-- | A <a>Hoistable</a> is a type that can be "promoted" or "hoisted" to a
--   Failable monad.
class (Failable m) => Hoistable m t e' | t -> e'

-- | Given a transformation function to obtain an error in the target
--   <a>Failable</a> context from an eventual errored value from the value
--   being hoisted, It promotes such value to a <a>Failable</a> operation.
--   For example:
--   
--   <pre>
--   foo :: (Failable m) =&gt; String -&gt; m Int
--   foo = hoist BadValue . readEither
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; λ&gt; runExceptT $ foo "5"
--   
--   &gt;&gt;&gt; Right 5
--   
--   &gt;&gt;&gt; λ&gt; foo "X5"
--   
--   &gt;&gt;&gt; *** Exception: BadValue "Prelude.read: no parse"
--   
--   &gt;&gt;&gt; λ&gt; runMaybeT $ foo "X5"
--   
--   &gt;&gt;&gt; Nothing
--   </pre>
hoist :: (Hoistable m t e', Exception e) => (e' -> e) -> t a -> m a

-- | Perform a set of IO actions in a <a>Failable</a> <a>MonadIO</a>
--   instance, triggering a <a>failure</a> upon an IO exception, instead of
--   blindly triggering an asynchronos exception. This serves ultimately to
--   unify error handling in the <a>Failable</a> context. For example:
--   
--   <pre>
--   foo :: (Failable m, MonadIO m) =&gt; m ()
--   foo = do
--     failableIO $ do
--       txt &lt;- readFile "foo.txt"
--       putStrLn txt
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; λ&gt; runExceptT foo
--   
--   &gt;&gt;&gt; Left foo.txt: openFile: does not exist (No such file or directory)
--   
--   &gt;&gt;&gt; 
--   
--   &gt;&gt;&gt; λ&gt; runMaybeT foo
--   
--   &gt;&gt;&gt; Nothing
--   
--   &gt;&gt;&gt; 
--   
--   &gt;&gt;&gt; λ&gt; foo
--   
--   &gt;&gt;&gt; *** Exception: foo.txt: openFile: does not exist (No such file or directory)
--   </pre>
failableIO :: (Failable m, MonadIO m) => IO a -> m a
instance GHC.Base.Monad m => Control.Monad.Failable.RunnableStateT (Control.Monad.Trans.State.Strict.StateT s) s m
instance GHC.Base.Monad m => Control.Monad.Failable.RunnableStateT (Control.Monad.Trans.Reader.ReaderT r) r m
instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Control.Monad.Failable.RunnableStateT (Control.Monad.Trans.Writer.Strict.WriterT w) w m
instance (GHC.Base.Monad (t m), Control.Monad.Trans.Class.MonadTrans t, Control.Monad.Failable.Failable m, Control.Monad.Failable.RunnableStateT t s m, Control.Monad.State.Class.MonadState s (t m)) => Control.Monad.Failable.Failable (t m)
instance Control.Monad.Failable.Failable m => Control.Monad.Failable.Hoistable m GHC.Maybe.Maybe ()
instance Control.Monad.Failable.Failable m => Control.Monad.Failable.Hoistable m (Data.Either.Either e') e'
instance Control.Monad.Failable.Failable GHC.Types.IO
instance Control.Monad.Failable.Failable []
instance Control.Monad.Failable.Failable GHC.Maybe.Maybe
instance (e Data.Type.Equality.~ GHC.Exception.Type.SomeException) => Control.Monad.Failable.Failable (Data.Either.Either e)
instance GHC.Base.Monad m => Control.Monad.Failable.Failable (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Base.Monad m, e Data.Type.Equality.~ GHC.Exception.Type.SomeException) => Control.Monad.Failable.Failable (Control.Monad.Trans.Except.ExceptT e m)
instance (GHC.Base.Monoid w, Control.Monad.Failable.Failable m) => Control.Monad.Failable.Failable (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance Control.Monad.Failable.Failable m => Control.Monad.Failable.Failable (Control.Monad.Trans.Reader.ReaderT r m)
instance GHC.Exception.Type.Exception ()