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


-- | A composable exception handler
--   
--   If you have ever had to compose an exception handler for exceptions of
--   multiple types, you know how frustraiting it can get. This library
--   approaches this issue by providing a composable exception handler
--   type, which has instances of the standard classes.
--   
--   Composability means that you can define custom partial handlers and
--   reuse them by composing other handlers from them.
--   
--   Here is an example of a composable partial handler, which only defines
--   what to do in case of a ThreadKilled exception (the code uses the
--   LambdaCase extension):
--   
--   <pre>
--   ignoreThreadKilled :: PartialHandler ()
--   ignoreThreadKilled =
--     typed $ \case
--       ThreadKilled -&gt; Just $ return ()
--       _ -&gt; Nothing
--   </pre>
--   
--   Here's how you can construct a handler of type <tt>SomeException -&gt;
--   IO ()</tt> using this library:
--   
--   <pre>
--   totalizeRethrowing $
--     ignoreThreadKilled &lt;&gt;
--     onAlreadyExists (putStrLn "Already exists")
--   </pre>
--   
--   and here is how you would do it traditionally (with the MultiWayIf
--   extension):
--   
--   <pre>
--   \e -&gt; if
--     | Just ThreadKilled &lt;- fromException e -&gt;
--         return ()
--     | Just e' &lt;- fromException e, isAlreadyExistsError e' -&gt;
--         putStrLn "Already exists"
--     | otherwise -&gt;
--         throwIO e
--   </pre>
--   
--   Putting all the syntactic trickery to make it shorter aside, this
--   handler is a monolith block of code. Unlike with PartialHandler you
--   can neither decompose it into simpler ones, nor compose it with other
--   handlers to form a more complex one.
@package partial-handler
@version 1.0.2

module PartialHandler

-- | A composable exception handler.
newtype PartialHandler a
PartialHandler :: (SomeException -> Maybe (IO a)) -> PartialHandler a

-- | A function, which handles all exceptions.
--   
--   Can be used as a parameter to standard functions like <a>catch</a> and
--   <a>handle</a>, or to process the result of <a>try</a>.
type TotalHandler a = SomeException -> IO a

-- | Convert a partial handler into a total handler, which throws an error
--   for unhandled cases. In other words, the produced total handler is
--   itself a partial function, so use this only in cases when an unhandled
--   exception should be considered as a bug.
totalize :: PartialHandler a -> TotalHandler a

-- | Convert a partial handler into a total handler, which rethrows all
--   unhandled exceptions.
totalizeRethrowing :: PartialHandler a -> TotalHandler a

-- | Convert a partial handler into a total handler, which rethrows all
--   unhandled exceptions to the specified thread and the current thread.
totalizeRethrowingTo :: ThreadId -> PartialHandler a -> TotalHandler a

-- | Convert a partial handler into a total handler, which rethrows all
--   unhandled exceptions to the specified thread, while the current thread
--   continues the execution.
totalizeRethrowingTo_ :: ThreadId -> PartialHandler () -> TotalHandler ()

-- | A handler of exceptions of a specific type.
typed :: Exception e => (e -> Maybe (IO a)) -> PartialHandler a

-- | A handler of the <a>ThreadKilled</a> exception.
onThreadKilled :: IO a -> PartialHandler a

-- | A handler of all exceptions of type <a>IOError</a> by their type.
onIOErrorByType :: (IOErrorType -> Maybe (IO a)) -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isAlreadyExistsError</a> predicate.
onAlreadyExists :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isDoesNotExistError</a> predicate.
onDoesNotExist :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isAlreadyInUseError</a> predicate.
onAlreadyInUse :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isFullError</a> predicate.
onFull :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isEOFError</a> predicate.
onEOF :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isIllegalOperation</a> predicate.
onIllegalOperation :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isPermissionError</a> predicate.
onPermission :: IO a -> PartialHandler a

-- | A handler of an <a>IOError</a> exception with type satisfying the
--   <a>isUserError</a> predicate.
onUser :: IO a -> PartialHandler a
instance GHC.Base.Functor PartialHandler.PartialHandler
instance GHC.Base.Applicative PartialHandler.PartialHandler
instance GHC.Base.Alternative PartialHandler.PartialHandler
instance GHC.Base.Monoid (PartialHandler.PartialHandler a)
