{-# LANGUAGE
  BangPatterns,
  GADTs,
  KindSignatures,
  RankNTypes,
  ScopedTypeVariables,
  StandaloneKindSignatures,
  TypeOperators #-}

-- | = Exceptions as an algebraic effect
--
-- These scoped exceptions are similar to "Bluefin.Exception".
--
-- Algebraic operations in Bluefin are truly scoped:
-- they cannot be intercepted by exception handlers, notably 'Bluefin.Eff.bracket'.
--
-- 'catch' and 'try' make an explicit call to 'cancel' to trigger exception handlers.
-- This makes them equivalent to "Bluefin.Exception".
--
-- The simpler variants 'catch'' and 'try'' don't use 'cancel', so they are
-- faster when there is no 'Bluefin.Eff.bracket' to worry about.
module Bluefin.Algae.Exception
  ( -- * Operations
    Exception(..)
  , throw

    -- * Default handlers
  , catch
  , try

    -- * Variant without cancelling continuations
  , catch'
  , try'
  ) where

import Data.Kind (Type)
import Bluefin.Eff (Eff, type (:&), type (:>))
import Bluefin.Algae

-- | Exception interface.
data Exception (e :: Type) :: AEffect where
  -- | Throw an exception.
  Throw :: e -> Exception e r

-- | Throw an exception. Call the 'Throw' operation.
throw :: z :> zz => Handler (Exception e) z -> e -> Eff zz a
throw :: forall (z :: Effects) (zz :: Effects) e a.
(z :> zz) =>
Handler (Exception e) z -> e -> Eff zz a
throw Handler (Exception e) z
h e
e = Handler (Exception e) z -> Exception e a -> Eff zz a
forall (s :: Effects) (ss :: Effects) (f :: AEffect) a.
(s :> ss) =>
Handler f s -> f a -> Eff ss a
call Handler (Exception e) z
h (e -> Exception e a
forall e r. e -> Exception e r
Throw e
e)

-- | Catch an exception.
--
-- Simple version of 'catch' which just discards the continuation
-- instead of explicitly cancelling it.
--
-- === Warning: Discarded continuations
--
-- 'catch'' discards the continuation, which may be problematic
-- if there are resources to be freed by the continuation (typically
-- if 'throw' was called in the middle of a 'Bluefin.Eff.bracket').
-- Use 'catch' to free those resources instead.
--
-- Without anything like 'Bluefin.Eff.bracket', 'catch'' does less work.
-- 'catch' makes 'throw' traverse the stack twice (first to find the prompt,
-- then to 'cancel' the continuation).
-- 'catch'' makes 'throw' traverse the stack only once.
catch' :: forall e a zz.
  (forall z. Handler (Exception e) z -> Eff (z :& zz) a) ->  -- ^ Handled computation
  (e -> Eff zz a) ->  -- ^ Exception clause
  Eff zz a
catch' :: forall e a (zz :: Effects).
(forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a)
-> (e -> Eff zz a) -> Eff zz a
catch' forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f e -> Eff zz a
h = HandlerBody (Exception e) zz a
-> (forall (z :: Effects).
    Handler (Exception e) z -> Eff (z :& zz) a)
-> Eff zz a
forall (f :: AEffect) (ss :: Effects) a.
HandlerBody f ss a -> ScopedEff f ss a -> Eff ss a
handle Exception e x -> (x -> Eff zz a) -> Eff zz a
HandlerBody (Exception e) zz a
exceptionHandler Handler (Exception e) s -> Eff (s :& zz) a
forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f
  where
    exceptionHandler :: HandlerBody (Exception e) zz a
    exceptionHandler :: HandlerBody (Exception e) zz a
exceptionHandler (Throw e
e) x -> Eff zz a
_ = e -> Eff zz a
h e
e

-- | Return 'Either' the exception or the result of the handled computation.
--
-- Simple version of 'try' which discards the continuation (like 'catch'').
try' :: forall e a zz.
  (forall z. Handler (Exception e) z -> Eff (z :& zz) a) ->
  Eff zz (Either e a)
try' :: forall e a (zz :: Effects).
(forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a)
-> Eff zz (Either e a)
try' forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f = (forall (z :: Effects).
 Handler (Exception e) z -> Eff (z :& zz) (Either e a))
-> (e -> Eff zz (Either e a)) -> Eff zz (Either e a)
forall e a (zz :: Effects).
(forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a)
-> (e -> Eff zz a) -> Eff zz a
catch' ((a -> Either e a) -> Eff (z :& zz) a -> Eff (z :& zz) (Either e a)
forall a b. (a -> b) -> Eff (z :& zz) a -> Eff (z :& zz) b
forall (f :: AEffect) a b. Functor f => (a -> b) -> f a -> f b
fmap a -> Either e a
forall a b. b -> Either a b
Right (Eff (z :& zz) a -> Eff (z :& zz) (Either e a))
-> (Handler (Exception e) z -> Eff (z :& zz) a)
-> Handler (Exception e) z
-> Eff (z :& zz) (Either e a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Handler (Exception e) z -> Eff (z :& zz) a
forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f) (Either e a -> Eff zz (Either e a)
forall a. a -> Eff zz a
forall (f :: AEffect) a. Applicative f => a -> f a
pure (Either e a -> Eff zz (Either e a))
-> (e -> Either e a) -> e -> Eff zz (Either e a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. e -> Either e a
forall a b. a -> Either a b
Left)

-- | Catch an exception.
--
-- The continuation is canceled ('cancel') when
-- an exception is thrown to this handler.
catch :: forall e a zz.
  (forall z. Handler (Exception e) z -> Eff (z :& zz) a) ->
  (e -> Eff zz a) ->
  Eff zz a
catch :: forall e a (zz :: Effects).
(forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a)
-> (e -> Eff zz a) -> Eff zz a
catch forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f e -> Eff zz a
h = HandlerBody' (Exception e) zz a
-> (forall (z :: Effects).
    Handler (Exception e) z -> Eff (z :& zz) a)
-> Eff zz a
forall (f :: AEffect) (ss :: Effects) a.
HandlerBody' f ss a -> ScopedEff f ss a -> Eff ss a
handle' Exception e x -> Continuation ss0 zz x a -> Eff zz a
HandlerBody' (Exception e) zz a
exceptionHandler Handler (Exception e) s -> Eff (s :& zz) a
forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f
  where
    exceptionHandler :: HandlerBody' (Exception e) zz a
    exceptionHandler :: HandlerBody' (Exception e) zz a
exceptionHandler (Throw e
e) Continuation ss0 zz x a
k = Continuation ss0 zz x a -> Eff zz ()
forall (t :: Effects) (s :: Effects) b a.
Continuation t s b a -> Eff s ()
cancel Continuation ss0 zz x a
k Eff zz () -> Eff zz a -> Eff zz a
forall a b. Eff zz a -> Eff zz b -> Eff zz b
forall (m :: AEffect) a b. Monad m => m a -> m b -> m b
>> e -> Eff zz a
h e
e

-- | Return 'Either' the exception or the result of the handled computation.
--
-- The continuation is canceled ('cancel') when
-- an exception is thrown to this handler.
try :: forall e a zz.
  (forall z. Handler (Exception e) z -> Eff (z :& zz) a) ->
  Eff zz (Either e a)
try :: forall e a (zz :: Effects).
(forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a)
-> Eff zz (Either e a)
try forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f = (forall (z :: Effects).
 Handler (Exception e) z -> Eff (z :& zz) (Either e a))
-> (e -> Eff zz (Either e a)) -> Eff zz (Either e a)
forall e a (zz :: Effects).
(forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a)
-> (e -> Eff zz a) -> Eff zz a
catch ((a -> Either e a) -> Eff (z :& zz) a -> Eff (z :& zz) (Either e a)
forall a b. (a -> b) -> Eff (z :& zz) a -> Eff (z :& zz) b
forall (f :: AEffect) a b. Functor f => (a -> b) -> f a -> f b
fmap a -> Either e a
forall a b. b -> Either a b
Right (Eff (z :& zz) a -> Eff (z :& zz) (Either e a))
-> (Handler (Exception e) z -> Eff (z :& zz) a)
-> Handler (Exception e) z
-> Eff (z :& zz) (Either e a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Handler (Exception e) z -> Eff (z :& zz) a
forall (z :: Effects). Handler (Exception e) z -> Eff (z :& zz) a
f) (Either e a -> Eff zz (Either e a)
forall a. a -> Eff zz a
forall (f :: AEffect) a. Applicative f => a -> f a
pure (Either e a -> Eff zz (Either e a))
-> (e -> Either e a) -> e -> Eff zz (Either e a)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. e -> Either e a
forall a b. a -> Either a b
Left)