-- 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.0.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

-- | 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

-- | <a>Promote</a> an <a>Either</a> value into a <a>Failable</a> context.
--   Useful to reduce verbosity when using functions that return an
--   <a>Either</a> type. If the value is <tt>Left err</tt>, the wrapped
--   error is then passed as an argument to the provided function which
--   should return an instance of <a>Exception</a>. so for example:
--   
--   <pre>
--   data MyErrors = BadValue deriving (Typeable, Show)
--   instance Exception MyErrors
--   
--   foo :: (Failable m) =&gt; String -&gt; m Int
--   foo = hoistEither BadValue . readEither
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; λ&gt; foo "5" :: Maybe Int
--   
--   &gt;&gt;&gt; Just 5
--   
--   &gt;&gt;&gt; λ&gt; foo "5" :: Either SomeException Int
--   
--   &gt;&gt;&gt; Right 5
--   
--   &gt;&gt;&gt; λ&gt; foo "X5" :: Either SomeException Int
--   
--   &gt;&gt;&gt; Left (BadValue "Prelude.read: no parse")
--   
--   &gt;&gt;&gt; λ&gt; foo "5" :: Maybe Int
--   
--   &gt;&gt;&gt; Just 5
--   
--   &gt;&gt;&gt; λ&gt; foo "X5" :: Maybe Int
--   
--   &gt;&gt;&gt; Nothing
--   </pre>
hoistEither :: (Failable m, Exception e) => (a -> e) -> Either a b -> m b

-- | <a>Promote</a> a <a>Maybe</a> into a <a>Failable</a> context. Useful
--   to reduce boilerplate when using functions that might return a
--   <a>Maybe</a> type. If the value is <tt>Nothing</tt>, the error
--   specified is then triggered in the <a>Failable</a> context
hoistMaybe :: (Failable m, Exception e) => e -> Maybe a -> m a
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.Exception.Type.Exception ()