{-# OPTIONS_HADDOCK not-home #-}
-- | This module contains the definition of the 'Eff' monad, which is basically an @'Env' es -> 'IO' a@, as well as
-- functions for manipulating the effect environment type 'Env'. Most of the times, you won't need to use this module
-- directly; user-facing functionalities are all exported via the "Cleff" module.
--
-- __This is an /internal/ module and its API may change even between minor versions.__ Therefore you should be
-- extra careful if you're to depend on this module.
module Cleff.Internal.Monad
  ( -- * Core types
    InternalHandler (..), Env, Eff (..)
  , -- * Performing effect operations
    KnownList, Subset, send
  ) where

import           Cleff.Internal.Effect
import           Control.Monad.Fix          (MonadFix)
import           Control.Monad.Trans.Reader (ReaderT (ReaderT))
import           Data.Mem                   (Mem)
import qualified Data.Mem                   as Mem
import           Data.Rec                   (KnownList, Subset)
import           Type.Reflection            (Typeable, typeRep)

-- | The internal representation of effect handlers. This is just a natural transformation from the effect type
-- @e ('Eff' es)@ to the effect monad @'Eff' es@ for any effect stack @es@.
--
-- In interpreting functions (see "Cleff.Internal.Interpret"), the user-facing 'Cleff.Handler' type is transformed into
-- this type.
newtype InternalHandler e = InternalHandler
  { InternalHandler e
-> forall (es :: [(Type -> Type) -> Type -> Type]) a.
   e (Eff es) a -> Eff es a
runHandler :: forall es. e (Eff es) ~> Eff es }

-- | @
-- 'show' (handler :: 'InternalHandler' E) == "Handler E"
-- @
instance Typeable e => Show (InternalHandler e) where
  showsPrec :: Int -> InternalHandler e -> ShowS
showsPrec Int
p InternalHandler e
_ = (String
"Handler " String -> ShowS
forall a. [a] -> [a] -> [a]
++) ShowS -> ShowS -> ShowS
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> TypeRep e -> ShowS
forall a. Show a => Int -> a -> ShowS
showsPrec Int
p (Typeable e => TypeRep e
forall k (a :: k). Typeable a => TypeRep a
typeRep @e)

-- | The effect memironment that stores handlers of any effect present in the stack @es@.
type Env = Mem InternalHandler

-- | The extensible effect monad. A monad @'Eff' es@ is capable of performing any effect in the /effect stack/ @es@,
-- which is a type-level list that holds all effects available. However, most of the times, for flexibility, @es@
-- should be a polymorphic type variable, and you should use the '(:>)' and '(:>>)' operators in constraints to
-- indicate what effects are in the stack. For example,
--
-- @
-- 'Cleff.Reader.Reader' 'String' ':>' es, 'Cleff.State.State' 'Bool' ':>' es => 'Eff' es 'Integer'
-- @
--
-- allows you to perform operations of the @'Cleff.Reader.Reader' 'String'@ effect and the @'Cleff.State.State' 'Bool'@
-- effect in a computation returning an 'Integer'.
type role Eff nominal representational
newtype Eff es a = Eff { Eff es a -> Env es -> IO a
unEff :: Env es -> IO a }
  deriving newtype (b -> Eff es a -> Eff es a
NonEmpty (Eff es a) -> Eff es a
Eff es a -> Eff es a -> Eff es a
(Eff es a -> Eff es a -> Eff es a)
-> (NonEmpty (Eff es a) -> Eff es a)
-> (forall b. Integral b => b -> Eff es a -> Eff es a)
-> Semigroup (Eff es a)
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Semigroup a =>
NonEmpty (Eff es a) -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Semigroup a =>
Eff es a -> Eff es a -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
(Semigroup a, Integral b) =>
b -> Eff es a -> Eff es a
forall b. Integral b => b -> Eff es a -> Eff es a
forall a.
(a -> a -> a)
-> (NonEmpty a -> a)
-> (forall b. Integral b => b -> a -> a)
-> Semigroup a
stimes :: b -> Eff es a -> Eff es a
$cstimes :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
(Semigroup a, Integral b) =>
b -> Eff es a -> Eff es a
sconcat :: NonEmpty (Eff es a) -> Eff es a
$csconcat :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
Semigroup a =>
NonEmpty (Eff es a) -> Eff es a
<> :: Eff es a -> Eff es a -> Eff es a
$c<> :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
Semigroup a =>
Eff es a -> Eff es a -> Eff es a
Semigroup, Semigroup (Eff es a)
Eff es a
Semigroup (Eff es a)
-> Eff es a
-> (Eff es a -> Eff es a -> Eff es a)
-> ([Eff es a] -> Eff es a)
-> Monoid (Eff es a)
[Eff es a] -> Eff es a
Eff es a -> Eff es a -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
Semigroup (Eff es a)
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
[Eff es a] -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
Eff es a -> Eff es a -> Eff es a
forall a.
Semigroup a -> a -> (a -> a -> a) -> ([a] -> a) -> Monoid a
mconcat :: [Eff es a] -> Eff es a
$cmconcat :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
[Eff es a] -> Eff es a
mappend :: Eff es a -> Eff es a -> Eff es a
$cmappend :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
Eff es a -> Eff es a -> Eff es a
mempty :: Eff es a
$cmempty :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
Eff es a
$cp1Monoid :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
Monoid a =>
Semigroup (Eff es a)
Monoid)
  deriving (a -> Eff es b -> Eff es a
(a -> b) -> Eff es a -> Eff es b
(forall a b. (a -> b) -> Eff es a -> Eff es b)
-> (forall a b. a -> Eff es b -> Eff es a) -> Functor (Eff es)
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
a -> Eff es b -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
(a -> b) -> Eff es a -> Eff es b
forall a b. a -> Eff es b -> Eff es a
forall a b. (a -> b) -> Eff es a -> Eff es b
forall (f :: Type -> Type).
(forall a b. (a -> b) -> f a -> f b)
-> (forall a b. a -> f b -> f a) -> Functor f
<$ :: a -> Eff es b -> Eff es a
$c<$ :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
a -> Eff es b -> Eff es a
fmap :: (a -> b) -> Eff es a -> Eff es b
$cfmap :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
(a -> b) -> Eff es a -> Eff es b
Functor, Functor (Eff es)
a -> Eff es a
Functor (Eff es)
-> (forall a. a -> Eff es a)
-> (forall a b. Eff es (a -> b) -> Eff es a -> Eff es b)
-> (forall a b c.
    (a -> b -> c) -> Eff es a -> Eff es b -> Eff es c)
-> (forall a b. Eff es a -> Eff es b -> Eff es b)
-> (forall a b. Eff es a -> Eff es b -> Eff es a)
-> Applicative (Eff es)
Eff es a -> Eff es b -> Eff es b
Eff es a -> Eff es b -> Eff es a
Eff es (a -> b) -> Eff es a -> Eff es b
(a -> b -> c) -> Eff es a -> Eff es b -> Eff es c
forall (es :: [(Type -> Type) -> Type -> Type]). Functor (Eff es)
forall (es :: [(Type -> Type) -> Type -> Type]) a. a -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> Eff es b -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> Eff es b -> Eff es b
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es (a -> b) -> Eff es a -> Eff es b
forall (es :: [(Type -> Type) -> Type -> Type]) a b c.
(a -> b -> c) -> Eff es a -> Eff es b -> Eff es c
forall a. a -> Eff es a
forall a b. Eff es a -> Eff es b -> Eff es a
forall a b. Eff es a -> Eff es b -> Eff es b
forall a b. Eff es (a -> b) -> Eff es a -> Eff es b
forall a b c. (a -> b -> c) -> Eff es a -> Eff es b -> Eff es c
forall (f :: Type -> Type).
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
<* :: Eff es a -> Eff es b -> Eff es a
$c<* :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> Eff es b -> Eff es a
*> :: Eff es a -> Eff es b -> Eff es b
$c*> :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> Eff es b -> Eff es b
liftA2 :: (a -> b -> c) -> Eff es a -> Eff es b -> Eff es c
$cliftA2 :: forall (es :: [(Type -> Type) -> Type -> Type]) a b c.
(a -> b -> c) -> Eff es a -> Eff es b -> Eff es c
<*> :: Eff es (a -> b) -> Eff es a -> Eff es b
$c<*> :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es (a -> b) -> Eff es a -> Eff es b
pure :: a -> Eff es a
$cpure :: forall (es :: [(Type -> Type) -> Type -> Type]) a. a -> Eff es a
$cp1Applicative :: forall (es :: [(Type -> Type) -> Type -> Type]). Functor (Eff es)
Applicative, Applicative (Eff es)
a -> Eff es a
Applicative (Eff es)
-> (forall a b. Eff es a -> (a -> Eff es b) -> Eff es b)
-> (forall a b. Eff es a -> Eff es b -> Eff es b)
-> (forall a. a -> Eff es a)
-> Monad (Eff es)
Eff es a -> (a -> Eff es b) -> Eff es b
Eff es a -> Eff es b -> Eff es b
forall (es :: [(Type -> Type) -> Type -> Type]).
Applicative (Eff es)
forall (es :: [(Type -> Type) -> Type -> Type]) a. a -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> Eff es b -> Eff es b
forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> (a -> Eff es b) -> Eff es b
forall a. a -> Eff es a
forall a b. Eff es a -> Eff es b -> Eff es b
forall a b. Eff es a -> (a -> Eff es b) -> Eff es b
forall (m :: Type -> Type).
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 -> Eff es a
$creturn :: forall (es :: [(Type -> Type) -> Type -> Type]) a. a -> Eff es a
>> :: Eff es a -> Eff es b -> Eff es b
$c>> :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> Eff es b -> Eff es b
>>= :: Eff es a -> (a -> Eff es b) -> Eff es b
$c>>= :: forall (es :: [(Type -> Type) -> Type -> Type]) a b.
Eff es a -> (a -> Eff es b) -> Eff es b
$cp1Monad :: forall (es :: [(Type -> Type) -> Type -> Type]).
Applicative (Eff es)
Monad, Monad (Eff es)
Monad (Eff es)
-> (forall a. (a -> Eff es a) -> Eff es a) -> MonadFix (Eff es)
(a -> Eff es a) -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]). Monad (Eff es)
forall (es :: [(Type -> Type) -> Type -> Type]) a.
(a -> Eff es a) -> Eff es a
forall a. (a -> Eff es a) -> Eff es a
forall (m :: Type -> Type).
Monad m -> (forall a. (a -> m a) -> m a) -> MonadFix m
mfix :: (a -> Eff es a) -> Eff es a
$cmfix :: forall (es :: [(Type -> Type) -> Type -> Type]) a.
(a -> Eff es a) -> Eff es a
$cp1MonadFix :: forall (es :: [(Type -> Type) -> Type -> Type]). Monad (Eff es)
MonadFix) via (ReaderT (Env es) IO)

-- | Perform an effect operation, /i.e./ a value of an effect type @e :: 'Effect'@. This requires @e@ to be in the
-- effect stack.
send :: e :> es => e (Eff es) ~> Eff es
send :: e (Eff es) ~> Eff es
send e (Eff es) a
eff = (Env es -> IO a) -> Eff es a
forall (es :: [(Type -> Type) -> Type -> Type]) a.
(Env es -> IO a) -> Eff es a
Eff \Env es
handlers -> Eff es a -> Env es -> IO a
forall (es :: [(Type -> Type) -> Type -> Type]) a.
Eff es a -> Env es -> IO a
unEff (InternalHandler e -> e (Eff es) a -> Eff es a
forall (e :: (Type -> Type) -> Type -> Type).
InternalHandler e
-> forall (es :: [(Type -> Type) -> Type -> Type]) a.
   e (Eff es) a -> Eff es a
runHandler (Env es -> InternalHandler e
forall k (e :: k) (es :: [k]) (f :: k -> Type).
Elem e es =>
Mem f es -> f e
Mem.read Env es
handlers) e (Eff es) a
eff) Env es
handlers