{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE UndecidableInstances #-}

{- | A carrier for an 'Empty' effect, indicating failure with a 'Nothing' value. Users that need access to an error message should use the 'Control.Effect.Fail.Fail' effect.

Note that 'Empty' effects can, when they are the last effect in a stack, be interpreted directly to a 'Maybe' without a call to 'runEmpty'.

@since 1.0.0.0
-}

module Control.Carrier.Empty.Maybe
( -- * Empty carrier
  runEmpty
, evalEmpty
, execEmpty
, EmptyC(..)
  -- * Empty effect
, module Control.Effect.Empty
) where

import Control.Algebra
import Control.Effect.Empty
import Control.Monad.Fail as Fail
import Control.Monad.Fix
import Control.Monad.IO.Class
import Control.Monad.Trans.Class
import Control.Monad.Trans.Maybe
import Data.Functor (void)
import Data.Maybe (isJust)

-- | Run an 'Empty' effect, returning 'Nothing' for empty computations, or 'Just' the result otherwise.
--
-- @
-- 'runEmpty' 'empty' = 'pure' 'Nothing'
-- @
-- @
-- 'runEmpty' ('pure' a) = 'pure' ('Just' a)
-- @
--
-- @since 1.0.0.0
runEmpty :: EmptyC m a -> m (Maybe a)
runEmpty :: EmptyC m a -> m (Maybe a)
runEmpty (EmptyC MaybeT m a
m) = MaybeT m a -> m (Maybe a)
forall (m :: * -> *) a. MaybeT m a -> m (Maybe a)
runMaybeT MaybeT m a
m
{-# INLINE runEmpty #-}

-- | Run an 'Empty' effect, discarding its result.
--
-- This is convenient for using 'empty' to signal early returns without needing to know whether control exited normally or not.
--
-- @
-- 'evalEmpty' = 'void' '.' 'runEmpty'
-- @
--
-- @since 1.1.0.0
evalEmpty :: Functor m => EmptyC m a -> m ()
evalEmpty :: EmptyC m a -> m ()
evalEmpty = m (Maybe a) -> m ()
forall (f :: * -> *) a. Functor f => f a -> f ()
void (m (Maybe a) -> m ())
-> (EmptyC m a -> m (Maybe a)) -> EmptyC m a -> m ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. EmptyC m a -> m (Maybe a)
forall (m :: * -> *) a. EmptyC m a -> m (Maybe a)
runEmpty
{-# INLINE evalEmpty #-}

-- | Run an 'Empty' effect, replacing its result with a 'Bool' indicating whether control exited normally.
--
-- This is convenient for using 'empty' to signal early returns when all you need to know is whether control exited normally or not, and not what value it exited with.
--
-- @
-- 'execEmpty' = 'fmap' 'isJust' '.' 'runEmpty'
-- @
-- @
-- 'execEmpty' ('pure' a) = 'pure' 'True'
-- @
-- @
-- 'execEmpty' 'empty' = 'pure' 'False'
-- @
--
-- @since 1.1.0.0
execEmpty :: Functor m => EmptyC m a -> m Bool
execEmpty :: EmptyC m a -> m Bool
execEmpty = (Maybe a -> Bool) -> m (Maybe a) -> m Bool
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap Maybe a -> Bool
forall a. Maybe a -> Bool
isJust (m (Maybe a) -> m Bool)
-> (EmptyC m a -> m (Maybe a)) -> EmptyC m a -> m Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. EmptyC m a -> m (Maybe a)
forall (m :: * -> *) a. EmptyC m a -> m (Maybe a)
runEmpty
{-# INLINE execEmpty #-}

-- | @since 1.0.0.0
newtype EmptyC m a = EmptyC (MaybeT m a)
  deriving (Algebra (Empty :+: sig), Functor (EmptyC m)
a -> EmptyC m a
Functor (EmptyC m)
-> (forall a. a -> EmptyC m a)
-> (forall a b. EmptyC m (a -> b) -> EmptyC m a -> EmptyC m b)
-> (forall a b c.
    (a -> b -> c) -> EmptyC m a -> EmptyC m b -> EmptyC m c)
-> (forall a b. EmptyC m a -> EmptyC m b -> EmptyC m b)
-> (forall a b. EmptyC m a -> EmptyC m b -> EmptyC m a)
-> Applicative (EmptyC m)
EmptyC m a -> EmptyC m b -> EmptyC m b
EmptyC m a -> EmptyC m b -> EmptyC m a
EmptyC m (a -> b) -> EmptyC m a -> EmptyC m b
(a -> b -> c) -> EmptyC m a -> EmptyC m b -> EmptyC m c
forall a. a -> EmptyC m a
forall a b. EmptyC m a -> EmptyC m b -> EmptyC m a
forall a b. EmptyC m a -> EmptyC m b -> EmptyC m b
forall a b. EmptyC m (a -> b) -> EmptyC m a -> EmptyC m b
forall a b c.
(a -> b -> c) -> EmptyC m a -> EmptyC m b -> EmptyC m c
forall (m :: * -> *). Monad m => Functor (EmptyC m)
forall (m :: * -> *) a. Monad m => a -> EmptyC m a
forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> EmptyC m b -> EmptyC m a
forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> EmptyC m b -> EmptyC m b
forall (m :: * -> *) a b.
Monad m =>
EmptyC m (a -> b) -> EmptyC m a -> EmptyC m b
forall (m :: * -> *) a b c.
Monad m =>
(a -> b -> c) -> EmptyC m a -> EmptyC m b -> EmptyC m c
forall (f :: * -> *).
Functor f
-> (forall a. a -> f a)
-> (forall a b. f (a -> b) -> f a -> f b)
-> (forall a b c. (a -> b -> c) -> f a -> f b -> f c)
-> (forall a b. f a -> f b -> f b)
-> (forall a b. f a -> f b -> f a)
-> Applicative f
<* :: EmptyC m a -> EmptyC m b -> EmptyC m a
$c<* :: forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> EmptyC m b -> EmptyC m a
*> :: EmptyC m a -> EmptyC m b -> EmptyC m b
$c*> :: forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> EmptyC m b -> EmptyC m b
liftA2 :: (a -> b -> c) -> EmptyC m a -> EmptyC m b -> EmptyC m c
$cliftA2 :: forall (m :: * -> *) a b c.
Monad m =>
(a -> b -> c) -> EmptyC m a -> EmptyC m b -> EmptyC m c
<*> :: EmptyC m (a -> b) -> EmptyC m a -> EmptyC m b
$c<*> :: forall (m :: * -> *) a b.
Monad m =>
EmptyC m (a -> b) -> EmptyC m a -> EmptyC m b
pure :: a -> EmptyC m a
$cpure :: forall (m :: * -> *) a. Monad m => a -> EmptyC m a
$cp1Applicative :: forall (m :: * -> *). Monad m => Functor (EmptyC m)
Applicative, a -> EmptyC m b -> EmptyC m a
(a -> b) -> EmptyC m a -> EmptyC m b
(forall a b. (a -> b) -> EmptyC m a -> EmptyC m b)
-> (forall a b. a -> EmptyC m b -> EmptyC m a)
-> Functor (EmptyC m)
forall a b. a -> EmptyC m b -> EmptyC m a
forall a b. (a -> b) -> EmptyC m a -> EmptyC m b
forall (m :: * -> *) a b.
Functor m =>
a -> EmptyC m b -> EmptyC m a
forall (m :: * -> *) a b.
Functor m =>
(a -> b) -> EmptyC m a -> EmptyC m b
forall (f :: * -> *).
(forall a b. (a -> b) -> f a -> f b)
-> (forall a b. a -> f b -> f a) -> Functor f
<$ :: a -> EmptyC m b -> EmptyC m a
$c<$ :: forall (m :: * -> *) a b.
Functor m =>
a -> EmptyC m b -> EmptyC m a
fmap :: (a -> b) -> EmptyC m a -> EmptyC m b
$cfmap :: forall (m :: * -> *) a b.
Functor m =>
(a -> b) -> EmptyC m a -> EmptyC m b
Functor, Applicative (EmptyC m)
a -> EmptyC m a
Applicative (EmptyC m)
-> (forall a b. EmptyC m a -> (a -> EmptyC m b) -> EmptyC m b)
-> (forall a b. EmptyC m a -> EmptyC m b -> EmptyC m b)
-> (forall a. a -> EmptyC m a)
-> Monad (EmptyC m)
EmptyC m a -> (a -> EmptyC m b) -> EmptyC m b
EmptyC m a -> EmptyC m b -> EmptyC m b
forall a. a -> EmptyC m a
forall a b. EmptyC m a -> EmptyC m b -> EmptyC m b
forall a b. EmptyC m a -> (a -> EmptyC m b) -> EmptyC m b
forall (m :: * -> *). Monad m => Applicative (EmptyC m)
forall (m :: * -> *) a. Monad m => a -> EmptyC m a
forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> EmptyC m b -> EmptyC m b
forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> (a -> EmptyC m b) -> EmptyC m b
forall (m :: * -> *).
Applicative m
-> (forall a b. m a -> (a -> m b) -> m b)
-> (forall a b. m a -> m b -> m b)
-> (forall a. a -> m a)
-> Monad m
return :: a -> EmptyC m a
$creturn :: forall (m :: * -> *) a. Monad m => a -> EmptyC m a
>> :: EmptyC m a -> EmptyC m b -> EmptyC m b
$c>> :: forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> EmptyC m b -> EmptyC m b
>>= :: EmptyC m a -> (a -> EmptyC m b) -> EmptyC m b
$c>>= :: forall (m :: * -> *) a b.
Monad m =>
EmptyC m a -> (a -> EmptyC m b) -> EmptyC m b
$cp1Monad :: forall (m :: * -> *). Monad m => Applicative (EmptyC m)
Monad, Monad (EmptyC m)
Monad (EmptyC m)
-> (forall a. (a -> EmptyC m a) -> EmptyC m a)
-> MonadFix (EmptyC m)
(a -> EmptyC m a) -> EmptyC m a
forall a. (a -> EmptyC m a) -> EmptyC m a
forall (m :: * -> *).
Monad m -> (forall a. (a -> m a) -> m a) -> MonadFix m
forall (m :: * -> *). MonadFix m => Monad (EmptyC m)
forall (m :: * -> *) a.
MonadFix m =>
(a -> EmptyC m a) -> EmptyC m a
mfix :: (a -> EmptyC m a) -> EmptyC m a
$cmfix :: forall (m :: * -> *) a.
MonadFix m =>
(a -> EmptyC m a) -> EmptyC m a
$cp1MonadFix :: forall (m :: * -> *). MonadFix m => Monad (EmptyC m)
MonadFix, Monad (EmptyC m)
Monad (EmptyC m)
-> (forall a. IO a -> EmptyC m a) -> MonadIO (EmptyC m)
IO a -> EmptyC m a
forall a. IO a -> EmptyC m a
forall (m :: * -> *).
Monad m -> (forall a. IO a -> m a) -> MonadIO m
forall (m :: * -> *). MonadIO m => Monad (EmptyC m)
forall (m :: * -> *) a. MonadIO m => IO a -> EmptyC m a
liftIO :: IO a -> EmptyC m a
$cliftIO :: forall (m :: * -> *) a. MonadIO m => IO a -> EmptyC m a
$cp1MonadIO :: forall (m :: * -> *). MonadIO m => Monad (EmptyC m)
MonadIO, m a -> EmptyC m a
(forall (m :: * -> *) a. Monad m => m a -> EmptyC m a)
-> MonadTrans EmptyC
forall (m :: * -> *) a. Monad m => m a -> EmptyC m a
forall (t :: (* -> *) -> * -> *).
(forall (m :: * -> *) a. Monad m => m a -> t m a) -> MonadTrans t
lift :: m a -> EmptyC m a
$clift :: forall (m :: * -> *) a. Monad m => m a -> EmptyC m a
MonadTrans)

-- | 'EmptyC' passes 'Fail.MonadFail' operations along to the underlying monad @m@, rather than interpreting it as a synonym for 'empty' à la 'MaybeT'.
instance Fail.MonadFail m => Fail.MonadFail (EmptyC m) where
  fail :: String -> EmptyC m a
fail = m a -> EmptyC m a
forall (t :: (* -> *) -> * -> *) (m :: * -> *) a.
(MonadTrans t, Monad m) =>
m a -> t m a
lift (m a -> EmptyC m a) -> (String -> m a) -> String -> EmptyC m a
forall b c a. (b -> c) -> (a -> b) -> a -> c
. String -> m a
forall (m :: * -> *) a. MonadFail m => String -> m a
Fail.fail
  {-# INLINE fail #-}