{-# LANGUAGE CPP #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE OverlappingInstances, FlexibleInstances #-}
{-|
Defines the @Throws@ binary relationship between types.
-}
module Control.Monad.Exception.Throws (
Throws, Caught,
CheckedException(..)
) where
#if __GLASGOW_HASKELL__ < 610
import Control.Exception.Extensible (Exception(..), SomeException)
#else
import Control.Exception (Exception(..), SomeException)
#endif
import Data.Typeable
-- | A type level witness of a exception handler.
data Caught e l
{-| @Throws@ is a type level binary relationship
used to model a list of exceptions.
There is only one case in which the user must
add further instances to @Throws@, and that is
to encode the hierarchy of exceptions.
[/Subtyping/]
As there is no way to automatically infer
the subcases of an exception, they have to be encoded
manually mirroring the hierarchy defined in the defined
'Exception' instances.
For example,
the following instance encodes that @MyFileNotFoundException@ is
a subexception of @MyIOException@ :
> instance Throws MyFileNotFoundException (Caught MyIOException l)
'Throws' is not a transitive relation and every ancestor relation
must be explicitly encoded.
> -- TopException
> -- |
> instance Throws MidException (Caught TopException l) -- |
> -- MidException
> instance Throws ChildException (Caught MidException l) -- |
> instance Throws ChildException (Caught TopException l) -- |
> -- ChildException
'SomeException' is automatically
an ancestor of every other exception type.
-}
class Exception e => Throws e l
instance Throws e l => Throws e (Caught e' l)
instance Exception e => Throws e (Caught e l)
-- | @SomeException@ is at the top of the exception hierarchy
-- .
-- Capturing SomeException captures every possible exception
instance Exception e => Throws e (Caught SomeException l)
instance Throws SomeException (Caught SomeException l) -- Disambiguation instance
-- Labelled SomeException
-- ------------------------
-- | @CheckedException@ adds a phantom type parameter @l@ to @SomeException@
newtype CheckedException l = CheckedException {checkedException::SomeException} deriving (Typeable)
instance Show (CheckedException l) where show (CheckedException e) = show e