Capability.Error

Defines capabilities for actions that may fail or throw exceptions, and optionally may catch exceptions.

Monads based on IO can use the underlying IO exception mechanism to that end. The details of synchronous and asynchronous exception handling depend on the strategy used. See MonadThrow, SafeExceptions, MonadUnliftIO.

The associated tag can be used to select the exception type, or to select a layer in monad transformer stacks. Note, that it is illegal to have multiple tags refer to overlapping exception types in the same layer. Consider the following example

newtype M a = M (IO a)
  deriving (HasThrow "foo" IOException) via
    MonadUnliftIO IO
  deriving (HasThrow "bar" SomeException) via
    MonadUnliftIO IO

In this case the tags "foo" and "bar" refer to overlapping exception types in the same layer, because catch @"bar" may also catch an exception thrown under "foo".

Relational capabilities

class Monad m => HasThrow (tag :: k) (e :: Type) (m :: Type -> Type) | tag m -> e where

Capability to throw exceptions of type e under tag.

HasThrow/HasCatch capabilities at different tags should be independent. See HasCatch.

Methods

throw_ :: Proxy# tag -> e -> m a

For technical reasons, this method needs an extra proxy argument. You only need it if you are defining new instances of HasReader. Otherwise, you will want to use throw. See throw for more documentation.

Instances

(HasThrow tag e m, MonadTrans t, Monad (t m)) => HasThrow (tag :: k) e (Lift (t m))

Lift one layer in a monad transformer stack.

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> Lift (t m) a

MonadError e m => HasThrow (tag :: k) e (MonadError m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadError m a

(Exception e, MonadThrow m) => HasThrow (tag :: k) e (MonadThrow e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadThrow e m a

(Exception e, MonadThrow m) => HasThrow (tag :: k) e (SafeExceptions e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> SafeExceptions e m a

(Exception e, MonadIO m) => HasThrow (tag :: k) e (MonadUnliftIO e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadUnliftIO e m a

(Exception e, MonadThrow m) => HasThrow (tag :: k) e (MonadCatch e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadCatch e m a

(Monad m, Reifies s (Reified tag (HasThrow tag e) m)) => HasThrow (tag :: k) e (Reflected s (HasThrow tag e) m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> Reflected s (HasThrow tag e) m a

HasThrow oldtag e m => HasThrow (newtag :: k2) e (Rename oldtag m)

Rename the tag.

Apply cautiously. See HasCatch newtag e (Rename oldtag m).

Defined in Capability.Error

Methods

throw_ :: Proxy# newtag -> e -> Rename oldtag m a

(Monad m, Reifies s (Reified tag (HasCatch tag e) m)) => HasThrow (tag :: k) e (Reflected s (HasCatch tag e) m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> Reflected s (HasCatch tag e) m a

(forall x. Coercible (m x) (t2 (t1 m) x), Monad m, HasThrow tag e (t2 (t1 m))) => HasThrow (tag :: k) e ((t2 :.: t1) m)

Compose two accessors.

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> (t2 :.: t1) m a

(AsConstructor' ctor sum e, HasThrow oldtag sum m) => HasThrow (ctor :: Symbol) e (Ctor ctor oldtag m)

Wrap the exception e with the constructor ctor to throw an exception of type sum.

Defined in Capability.Error

Methods

throw_ :: Proxy# ctor -> e -> Ctor ctor oldtag m a

data Reified (tag :: k) (HasThrow tag e) m

Defined in Capability.Error

data Reified (tag :: k) (HasThrow tag e) m = ReifiedThrow {

• _throw :: forall a. e -> m a

}

throw :: forall tag e m a. HasThrow tag e m => e -> m a

Throw an exception in the specified exception capability.

class HasThrow tag e m => HasCatch (tag :: k) (e :: Type) (m :: Type -> Type) | tag m -> e where

Capability to catch exceptions of type e under tag.

HasThrow/HasCatch capabilities at different tags should be independent. In particular, the following program should throw SomeError and not return (). > example :: > (HasThrow Left SomeError m, HasCatch Right SomeError m) > => m () > example = > catch Left > (throw Right SomeError) > _ -> pure ()

See wrapError for a way to combine multiple exception types into one.

Methods

catch_ :: Proxy# tag -> m a -> (e -> m a) -> m a

For technical reasons, this method needs an extra proxy argument. You only need it if you are defining new instances of HasReader. Otherwise, you will want to use catch. See catch for more documentation.

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> m a -> (b -> m a) -> m a

For technical reasons, this method needs an extra proxy argument. You only need it if you are defining new instances of HasReader. Otherwise, you will want to use catchJust. See catchJust for more documentation.

Instances

(HasCatch tag e m, MonadTransControl t, Monad (t m)) => HasCatch (tag :: k) e (Lift (t m))

Lift one layer in a monad transformer stack.

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> Lift (t m) a -> (e -> Lift (t m) a) -> Lift (t m) a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> Lift (t m) a -> (b -> Lift (t m) a) -> Lift (t m) a

MonadError e m => HasCatch (tag :: k) e (MonadError m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> MonadError m a -> (e -> MonadError m a) -> MonadError m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> MonadError m a -> (b -> MonadError m a) -> MonadError m a

(Exception e, MonadCatch m) => HasCatch (tag :: k) e (MonadCatch e m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> MonadCatch e m a -> (e -> MonadCatch e m a) -> MonadCatch e m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> MonadCatch e m a -> (b -> MonadCatch e m a) -> MonadCatch e m a

(Exception e, MonadCatch m) => HasCatch (tag :: k) e (SafeExceptions e m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> SafeExceptions e m a -> (e -> SafeExceptions e m a) -> SafeExceptions e m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> SafeExceptions e m a -> (b -> SafeExceptions e m a) -> SafeExceptions e m a

(Exception e, MonadUnliftIO m) => HasCatch (tag :: k) e (MonadUnliftIO e m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> MonadUnliftIO e m a -> (e -> MonadUnliftIO e m a) -> MonadUnliftIO e m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> MonadUnliftIO e m a -> (b -> MonadUnliftIO e m a) -> MonadUnliftIO e m a

(Monad m, Reifies s (Reified tag (HasCatch tag e) m)) => HasCatch (tag :: k) e (Reflected s (HasCatch tag e) m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> Reflected s (HasCatch tag e) m a -> (e -> Reflected s (HasCatch tag e) m a) -> Reflected s (HasCatch tag e) m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> Reflected s (HasCatch tag e) m a -> (b -> Reflected s (HasCatch tag e) m a) -> Reflected s (HasCatch tag e) m a

HasCatch oldtag e m => HasCatch (newtag :: k2) e (Rename oldtag m)

Rename the tag.

Apply cautiously. E.g. the following code produces colliding instances, where exceptions thrown in "Foo" cannot be distinguished from exceptions thrown in "Bar" and vice-versa.

newtype Bad a = Bad (IO a)
  deriving (Functor, Applicative, Monad)
  deriving
    ( HasThrow "Foo" m
    , HasCatch "Foo" m
    ) via Rename () (MonadUnliftIO SomeError IO)
  deriving
    ( HasThrow "Bar" m
    , HasCatch "Bar" m
    ) via Rename () (MonadUnliftIO SomeError IO)

Defined in Capability.Error

Methods

catch_ :: Proxy# newtag -> Rename oldtag m a -> (e -> Rename oldtag m a) -> Rename oldtag m a

catchJust_ :: Proxy# newtag -> (e -> Maybe b) -> Rename oldtag m a -> (b -> Rename oldtag m a) -> Rename oldtag m a

(forall x. Coercible (m x) (t2 (t1 m) x), Monad m, HasCatch tag e (t2 (t1 m))) => HasCatch (tag :: k) e ((t2 :.: t1) m)

Compose two accessors.

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> (t2 :.: t1) m a -> (e -> (t2 :.: t1) m a) -> (t2 :.: t1) m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> (t2 :.: t1) m a -> (b -> (t2 :.: t1) m a) -> (t2 :.: t1) m a

(Monad m, Reifies s (Reified tag (HasCatch tag e) m)) => HasThrow (tag :: k) e (Reflected s (HasCatch tag e) m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> Reflected s (HasCatch tag e) m a

(AsConstructor' ctor sum e, HasCatch oldtag sum m) => HasCatch (ctor :: Symbol) e (Ctor ctor oldtag m)

Catch an exception of type sum if its constructor matches ctor.

Defined in Capability.Error

Methods

catch_ :: Proxy# ctor -> Ctor ctor oldtag m a -> (e -> Ctor ctor oldtag m a) -> Ctor ctor oldtag m a

catchJust_ :: Proxy# ctor -> (e -> Maybe b) -> Ctor ctor oldtag m a -> (b -> Ctor ctor oldtag m a) -> Ctor ctor oldtag m a

data Reified (tag :: k) (HasCatch tag e) m

Defined in Capability.Error

data Reified (tag :: k) (HasCatch tag e) m = ReifiedCatch {

• _catchThrow :: Reified tag (HasThrow tag e) m
• _catch :: forall a. m a -> (e -> m a) -> m a
• _catchJust :: forall a b. (e -> Maybe b) -> m a -> (b -> m a) -> m a

}

catch :: forall tag e m a. HasCatch tag e m => m a -> (e -> m a) -> m a

Provide a handler for exceptions thrown in the given action in the given exception capability.

catchJust :: forall tag e m a b. HasCatch tag e m => (e -> Maybe b) -> m a -> (b -> m a) -> m a

Like catch, but only handle the exception if the provided function returns Just.

wrapError :: forall innertag t (cs :: [Capability]) inner m a. (forall x. Coercible (t m x) (m x), HasCatch innertag inner (t m), All cs m) => (forall m'. All (HasCatch innertag inner ': cs) m' => m' a) -> m a

Wrap exceptions inner originating from the given action according to the accessor t. Retain arbitrary capabilities listed in cs.

Example:

wrapError
  @"ComponentError" @(Ctor "ComponentError" "AppError") @'[]
  component

component :: HasError "ComponentError" ComponentError m => m ()
data AppError = ComponentError ComponentError

This function is experimental and subject to change. See https://github.com/tweag/capability/issues/46.

Functional capabilities

type HasThrow' (tag :: k) = HasThrow tag (TypeOf k tag)

Type synonym using the TypeOf type family to specify HasThrow constraints without having to specify the type associated to a tag.

type HasCatch' (tag :: k) = HasCatch tag (TypeOf k tag)

Type synonym using the TypeOf type family to specify HasCatch constraints without having to specify the type associated to a tag.

type family TypeOf k (s :: k) :: Type

Type family associating a tag to the corresponding type. It is intended to simplify constraint declarations, by removing the need to redundantly specify the type associated to a tag.

It is poly-kinded, which allows users to define their own kind of tags. Standard haskell types can also be used as tags by specifying the Type kind when defining the type family instance.

Defining TypeOf instances for Symbols (typelevel string literals) is discouraged. Since symbols all belong to the same global namespace, such instances could conflict with others defined in external libraries. More generally, as for typeclasses, TypeOf instances should always be defined in the same module as the tag type to prevent issues due to orphan instances.

Example:

    import Capability.Reader

    data Foo
    data Bar
    type instance TypeOf Type Foo = Int
    type instance TypeOf Type Bar = String

    -- Same as: foo :: HasReader Foo Int M => …
    foo :: HasReader' Foo m => …
    foo = …

Strategies

newtype MonadError m (a :: Type)

Derive 'HasError from m's MonadError instance.

Constructors

MonadError (m a)

Instances

MonadError e m => HasCatch (tag :: k) e (MonadError m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> MonadError m a -> (e -> MonadError m a) -> MonadError m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> MonadError m a -> (b -> MonadError m a) -> MonadError m a

MonadError e m => HasThrow (tag :: k) e (MonadError m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadError m a

Monad m => Monad (MonadError m)

Defined in Capability.Error

Methods

(>>=) :: MonadError m a -> (a -> MonadError m b) -> MonadError m b

(>>) :: MonadError m a -> MonadError m b -> MonadError m b

return :: a -> MonadError m a

Functor m => Functor (MonadError m)

Defined in Capability.Error

Methods

fmap :: (a -> b) -> MonadError m a -> MonadError m b

(<$) :: a -> MonadError m b -> MonadError m a

Applicative m => Applicative (MonadError m)

Defined in Capability.Error

Methods

pure :: a -> MonadError m a

(<*>) :: MonadError m (a -> b) -> MonadError m a -> MonadError m b

liftA2 :: (a -> b -> c) -> MonadError m a -> MonadError m b -> MonadError m c

(*>) :: MonadError m a -> MonadError m b -> MonadError m b

(<*) :: MonadError m a -> MonadError m b -> MonadError m a

MonadIO m => MonadIO (MonadError m)

Defined in Capability.Error

Methods

liftIO :: IO a -> MonadError m a

PrimMonad m => PrimMonad (MonadError m)

Defined in Capability.Error

Associated Types

type PrimState (MonadError m)

Methods

primitive :: (State# (PrimState (MonadError m)) -> (# State# (PrimState (MonadError m)), a #)) -> MonadError m a

type PrimState (MonadError m)

Defined in Capability.Error

type PrimState (MonadError m) = PrimState m

newtype MonadThrow (e :: Type) m (a :: Type)

Derive HasThrow from m's MonadThrow instance.

Constructors

MonadThrow (m a)

Instances

(Exception e, MonadThrow m) => HasThrow (tag :: k) e (MonadThrow e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadThrow e m a

Monad m => Monad (MonadThrow e m)

Defined in Capability.Error

Methods

(>>=) :: MonadThrow e m a -> (a -> MonadThrow e m b) -> MonadThrow e m b

(>>) :: MonadThrow e m a -> MonadThrow e m b -> MonadThrow e m b

return :: a -> MonadThrow e m a

Functor m => Functor (MonadThrow e m)

Defined in Capability.Error

Methods

fmap :: (a -> b) -> MonadThrow e m a -> MonadThrow e m b

(<$) :: a -> MonadThrow e m b -> MonadThrow e m a

Applicative m => Applicative (MonadThrow e m)

Defined in Capability.Error

Methods

pure :: a -> MonadThrow e m a

(<*>) :: MonadThrow e m (a -> b) -> MonadThrow e m a -> MonadThrow e m b

liftA2 :: (a -> b -> c) -> MonadThrow e m a -> MonadThrow e m b -> MonadThrow e m c

(*>) :: MonadThrow e m a -> MonadThrow e m b -> MonadThrow e m b

(<*) :: MonadThrow e m a -> MonadThrow e m b -> MonadThrow e m a

MonadIO m => MonadIO (MonadThrow e m)

Defined in Capability.Error

Methods

liftIO :: IO a -> MonadThrow e m a

PrimMonad m => PrimMonad (MonadThrow e m)

Defined in Capability.Error

Associated Types

type PrimState (MonadThrow e m)

Methods

primitive :: (State# (PrimState (MonadThrow e m)) -> (# State# (PrimState (MonadThrow e m)), a #)) -> MonadThrow e m a

type PrimState (MonadThrow e m)

Defined in Capability.Error

type PrimState (MonadThrow e m) = PrimState m

newtype MonadCatch (e :: Type) m (a :: Type)

Derive 'HasCatch from m's 'Control.Monad.Catch.MonadCatch instance.

Constructors

MonadCatch (m a)

Instances

(Exception e, MonadCatch m) => HasCatch (tag :: k) e (MonadCatch e m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> MonadCatch e m a -> (e -> MonadCatch e m a) -> MonadCatch e m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> MonadCatch e m a -> (b -> MonadCatch e m a) -> MonadCatch e m a

(Exception e, MonadThrow m) => HasThrow (tag :: k) e (MonadCatch e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadCatch e m a

Monad m => Monad (MonadCatch e m)

Defined in Capability.Error

Methods

(>>=) :: MonadCatch e m a -> (a -> MonadCatch e m b) -> MonadCatch e m b

(>>) :: MonadCatch e m a -> MonadCatch e m b -> MonadCatch e m b

return :: a -> MonadCatch e m a

Functor m => Functor (MonadCatch e m)

Defined in Capability.Error

Methods

fmap :: (a -> b) -> MonadCatch e m a -> MonadCatch e m b

(<$) :: a -> MonadCatch e m b -> MonadCatch e m a

Applicative m => Applicative (MonadCatch e m)

Defined in Capability.Error

Methods

pure :: a -> MonadCatch e m a

(<*>) :: MonadCatch e m (a -> b) -> MonadCatch e m a -> MonadCatch e m b

liftA2 :: (a -> b -> c) -> MonadCatch e m a -> MonadCatch e m b -> MonadCatch e m c

(*>) :: MonadCatch e m a -> MonadCatch e m b -> MonadCatch e m b

(<*) :: MonadCatch e m a -> MonadCatch e m b -> MonadCatch e m a

MonadIO m => MonadIO (MonadCatch e m)

Defined in Capability.Error

Methods

liftIO :: IO a -> MonadCatch e m a

PrimMonad m => PrimMonad (MonadCatch e m)

Defined in Capability.Error

Associated Types

type PrimState (MonadCatch e m)

Methods

primitive :: (State# (PrimState (MonadCatch e m)) -> (# State# (PrimState (MonadCatch e m)), a #)) -> MonadCatch e m a

type PrimState (MonadCatch e m)

Defined in Capability.Error

type PrimState (MonadCatch e m) = PrimState m

newtype SafeExceptions (e :: Type) m (a :: Type)

Derive HasError using the functionality from the safe-exceptions package.

Constructors

SafeExceptions (m a)

Instances

(Exception e, MonadCatch m) => HasCatch (tag :: k) e (SafeExceptions e m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> SafeExceptions e m a -> (e -> SafeExceptions e m a) -> SafeExceptions e m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> SafeExceptions e m a -> (b -> SafeExceptions e m a) -> SafeExceptions e m a

(Exception e, MonadThrow m) => HasThrow (tag :: k) e (SafeExceptions e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> SafeExceptions e m a

Monad m => Monad (SafeExceptions e m)

Defined in Capability.Error

Methods

(>>=) :: SafeExceptions e m a -> (a -> SafeExceptions e m b) -> SafeExceptions e m b

(>>) :: SafeExceptions e m a -> SafeExceptions e m b -> SafeExceptions e m b

return :: a -> SafeExceptions e m a

Functor m => Functor (SafeExceptions e m)

Defined in Capability.Error

Methods

fmap :: (a -> b) -> SafeExceptions e m a -> SafeExceptions e m b

(<$) :: a -> SafeExceptions e m b -> SafeExceptions e m a

Applicative m => Applicative (SafeExceptions e m)

Defined in Capability.Error

Methods

pure :: a -> SafeExceptions e m a

(<*>) :: SafeExceptions e m (a -> b) -> SafeExceptions e m a -> SafeExceptions e m b

liftA2 :: (a -> b -> c) -> SafeExceptions e m a -> SafeExceptions e m b -> SafeExceptions e m c

(*>) :: SafeExceptions e m a -> SafeExceptions e m b -> SafeExceptions e m b

(<*) :: SafeExceptions e m a -> SafeExceptions e m b -> SafeExceptions e m a

MonadIO m => MonadIO (SafeExceptions e m)

Defined in Capability.Error

Methods

liftIO :: IO a -> SafeExceptions e m a

PrimMonad m => PrimMonad (SafeExceptions e m)

Defined in Capability.Error

Associated Types

type PrimState (SafeExceptions e m)

Methods

primitive :: (State# (PrimState (SafeExceptions e m)) -> (# State# (PrimState (SafeExceptions e m)), a #)) -> SafeExceptions e m a

type PrimState (SafeExceptions e m)

Defined in Capability.Error

type PrimState (SafeExceptions e m) = PrimState m

newtype MonadUnliftIO (e :: Type) m (a :: Type)

Derive HasError using the functionality from the unliftio package.

Constructors

MonadUnliftIO (m a)

Instances

(Exception e, MonadUnliftIO m) => HasCatch (tag :: k) e (MonadUnliftIO e m)

Defined in Capability.Error

Methods

catch_ :: Proxy# tag -> MonadUnliftIO e m a -> (e -> MonadUnliftIO e m a) -> MonadUnliftIO e m a

catchJust_ :: Proxy# tag -> (e -> Maybe b) -> MonadUnliftIO e m a -> (b -> MonadUnliftIO e m a) -> MonadUnliftIO e m a

(Exception e, MonadIO m) => HasThrow (tag :: k) e (MonadUnliftIO e m)

Defined in Capability.Error

Methods

throw_ :: Proxy# tag -> e -> MonadUnliftIO e m a

Monad m => Monad (MonadUnliftIO e m)

Defined in Capability.Error

Methods

(>>=) :: MonadUnliftIO e m a -> (a -> MonadUnliftIO e m b) -> MonadUnliftIO e m b

(>>) :: MonadUnliftIO e m a -> MonadUnliftIO e m b -> MonadUnliftIO e m b

return :: a -> MonadUnliftIO e m a

Functor m => Functor (MonadUnliftIO e m)

Defined in Capability.Error

Methods

fmap :: (a -> b) -> MonadUnliftIO e m a -> MonadUnliftIO e m b

(<$) :: a -> MonadUnliftIO e m b -> MonadUnliftIO e m a

Applicative m => Applicative (MonadUnliftIO e m)

Defined in Capability.Error

Methods

pure :: a -> MonadUnliftIO e m a

(<*>) :: MonadUnliftIO e m (a -> b) -> MonadUnliftIO e m a -> MonadUnliftIO e m b

liftA2 :: (a -> b -> c) -> MonadUnliftIO e m a -> MonadUnliftIO e m b -> MonadUnliftIO e m c

(*>) :: MonadUnliftIO e m a -> MonadUnliftIO e m b -> MonadUnliftIO e m b

(<*) :: MonadUnliftIO e m a -> MonadUnliftIO e m b -> MonadUnliftIO e m a

MonadIO m => MonadIO (MonadUnliftIO e m)

Defined in Capability.Error

Methods

liftIO :: IO a -> MonadUnliftIO e m a

PrimMonad m => PrimMonad (MonadUnliftIO e m)

Defined in Capability.Error

Associated Types

type PrimState (MonadUnliftIO e m)

Methods

primitive :: (State# (PrimState (MonadUnliftIO e m)) -> (# State# (PrimState (MonadUnliftIO e m)), a #)) -> MonadUnliftIO e m a

type PrimState (MonadUnliftIO e m)

Defined in Capability.Error

type PrimState (MonadUnliftIO e m) = PrimState m

Modifiers

module Capability.Accessors

Reflection

data family Reified (tag :: k) (c :: Capability) (m :: Type -> Type)

Reified tag capability m

Defines the dictionary type for the methods of capability under tag in the monad m. Refer to interpret_ for an example use-case.

For example, the HasSink capability has the method yield :: a -> m (). The corresponding dictionary type is defined as follows.

>>> :{
  data instance Reified tag (HasSink tag a) m =
    ReifiedSink { _yield :: forall a. a -> m () }
  :}

Superclass dictionaries are represented as nested records. For example, the HasState capability has the superclasses HasSource and HasSink and the method state :: (s -> (a, s)) -> m a. The corresponding dictionary type is defined as follows.

>>> :{
  data instance Reified tag (HasState tag s) m =
    ReifiedState
      { _stateSource :: Reified tag (HasSource tag s) m,
        _stateSink :: Reified tag (HasSink tag s) m,
        _state :: forall a. (s -> (a, s)) -> m a
      }
  :}

Instances

data Reified (tag :: k) (HasSink tag a) m

Defined in Capability.Sink.Internal.Class

data Reified (tag :: k) (HasSink tag a) m = ReifiedSink {

• _yield :: a -> m ()

}

data Reified (tag :: k) (HasSource tag a) m

Defined in Capability.Source.Internal.Class

data Reified (tag :: k) (HasSource tag a) m = ReifiedSource {

• _await :: m a

}

data Reified (tag :: k) (HasReader tag r) m

Defined in Capability.Reader.Internal.Class

data Reified (tag :: k) (HasReader tag r) m = ReifiedReader {

• _readerSource :: Reified tag (HasSource tag r) m
• _local :: forall a. (r -> r) -> m a -> m a
• _reader :: forall a. (r -> a) -> m a

}

data Reified (tag :: k) (HasState tag s) m

Defined in Capability.State.Internal.Class

data Reified (tag :: k) (HasState tag s) m = ReifiedState {

• _stateSource :: Reified tag (HasSource tag s) m
• _stateSink :: Reified tag (HasSink tag s) m
• _state :: forall a. (s -> (a, s)) -> m a

}

data Reified (tag :: k) (HasThrow tag e) m

Defined in Capability.Error

data Reified (tag :: k) (HasThrow tag e) m = ReifiedThrow {

• _throw :: forall a. e -> m a

}

data Reified (tag :: k) (HasCatch tag e) m

Defined in Capability.Error

data Reified (tag :: k) (HasCatch tag e) m = ReifiedCatch {

• _catchThrow :: Reified tag (HasThrow tag e) m
• _catch :: forall a. m a -> (e -> m a) -> m a
• _catchJust :: forall a b. (e -> Maybe b) -> m a -> (b -> m a) -> m a

}

data Reified (tag :: k) (HasWriter tag w) m

Defined in Capability.Writer

data Reified (tag :: k) (HasWriter tag w) m = ReifiedWriter {

• _writerSink :: Reified tag (HasSink tag w) m
• _writer :: forall a. (a, w) -> m a
• _listen :: forall a. m a -> m (a, w)
• _pass :: forall a. m (a, w -> w) -> m a

}

Re-exported

class (Typeable e, Show e) => Exception e where

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
    deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
    show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
    SomeCompilerException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
    show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
    toException = compilerExceptionToException
    fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
    SomeFrontendException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
    deriving Show

instance Exception MismatchedParentheses where
    toException   = frontendExceptionToException
    fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

Minimal complete definition

Nothing

Methods

toException :: e -> SomeException

fromException :: SomeException -> Maybe e

displayException :: e -> String

Render this exception value in a human-friendly manner.

Default implementation: show.

Since: base-4.8.0.0

Instances

Exception Void

Since: base-4.8.0.0

Defined in Data.Void

Methods

toException :: Void -> SomeException

fromException :: SomeException -> Maybe Void

displayException :: Void -> String

Exception BlockedIndefinitelyOnMVar

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: BlockedIndefinitelyOnMVar -> SomeException

fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar

displayException :: BlockedIndefinitelyOnMVar -> String

Exception BlockedIndefinitelyOnSTM

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: BlockedIndefinitelyOnSTM -> SomeException

fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM

displayException :: BlockedIndefinitelyOnSTM -> String

Exception Deadlock

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: Deadlock -> SomeException

fromException :: SomeException -> Maybe Deadlock

displayException :: Deadlock -> String

Exception AllocationLimitExceeded

Since: base-4.8.0.0

Defined in GHC.IO.Exception

Methods

toException :: AllocationLimitExceeded -> SomeException

fromException :: SomeException -> Maybe AllocationLimitExceeded

displayException :: AllocationLimitExceeded -> String

Exception CompactionFailed

Since: base-4.10.0.0

Defined in GHC.IO.Exception

Methods

toException :: CompactionFailed -> SomeException

fromException :: SomeException -> Maybe CompactionFailed

displayException :: CompactionFailed -> String

Exception AssertionFailed

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: AssertionFailed -> SomeException

fromException :: SomeException -> Maybe AssertionFailed

displayException :: AssertionFailed -> String

Exception SomeAsyncException

Since: base-4.7.0.0

Defined in GHC.IO.Exception

Methods

toException :: SomeAsyncException -> SomeException

fromException :: SomeException -> Maybe SomeAsyncException

displayException :: SomeAsyncException -> String

Exception AsyncException

Since: base-4.7.0.0

Defined in GHC.IO.Exception

Methods

toException :: AsyncException -> SomeException

fromException :: SomeException -> Maybe AsyncException

displayException :: AsyncException -> String

Exception ArrayException

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: ArrayException -> SomeException

fromException :: SomeException -> Maybe ArrayException

displayException :: ArrayException -> String

Exception FixIOException

Since: base-4.11.0.0

Defined in GHC.IO.Exception

Methods

toException :: FixIOException -> SomeException

fromException :: SomeException -> Maybe FixIOException

displayException :: FixIOException -> String

Exception ExitCode

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: ExitCode -> SomeException

fromException :: SomeException -> Maybe ExitCode

displayException :: ExitCode -> String

Exception IOException

Since: base-4.1.0.0

Defined in GHC.IO.Exception

Methods

toException :: IOException -> SomeException

fromException :: SomeException -> Maybe IOException

displayException :: IOException -> String

Exception ArithException

Since: base-4.0.0.0

Defined in GHC.Exception.Type

Methods

toException :: ArithException -> SomeException

fromException :: SomeException -> Maybe ArithException

displayException :: ArithException -> String

Exception SomeException

Since: base-3.0

Defined in GHC.Exception.Type

Methods

toException :: SomeException -> SomeException

fromException :: SomeException -> Maybe SomeException

displayException :: SomeException -> String

Exception StringException

Defined in Control.Exception.Safe

Methods

toException :: StringException -> SomeException

fromException :: SomeException -> Maybe StringException

displayException :: StringException -> String

Exception SyncExceptionWrapper

Defined in Control.Exception.Safe

Methods

toException :: SyncExceptionWrapper -> SomeException

fromException :: SomeException -> Maybe SyncExceptionWrapper

displayException :: SyncExceptionWrapper -> String

Exception AsyncExceptionWrapper

Defined in Control.Exception.Safe

Methods

toException :: AsyncExceptionWrapper -> SomeException

fromException :: SomeException -> Maybe AsyncExceptionWrapper

displayException :: AsyncExceptionWrapper -> String

Exception SyncExceptionWrapper

Since: unliftio-0.1.0.0

Defined in UnliftIO.Exception

Methods

toException :: SyncExceptionWrapper -> SomeException

fromException :: SomeException -> Maybe SyncExceptionWrapper

displayException :: SyncExceptionWrapper -> String

Exception AsyncExceptionWrapper

Since: unliftio-0.1.0.0

Defined in UnliftIO.Exception

Methods

toException :: AsyncExceptionWrapper -> SomeException

fromException :: SomeException -> Maybe AsyncExceptionWrapper

displayException :: AsyncExceptionWrapper -> String

Exception StringException

Since: unliftio-0.1.0.0

Defined in UnliftIO.Exception

Methods

toException :: StringException -> SomeException

fromException :: SomeException -> Maybe StringException

displayException :: StringException -> String

class Typeable (a :: k)

The class Typeable allows a concrete representation of a type to be calculated.

Minimal complete definition

typeRep#

Instances

HasDict (Typeable k, Typeable a) (TypeRep a)

Defined in Data.Constraint

Methods

evidence :: TypeRep a -> Dict (Typeable k, Typeable a)