-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Fast and concise extensible effects
--   
--   Please see the README on GitHub at
--   <a>https://github.com/re-xyr/cleff#readme</a>
@package cleff
@version 0.3.2.0


-- | This module contains common definitions for the <tt>cleff</tt>
--   internals.
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal

-- | The type of effects. An effect <tt>e m a</tt> takes an effect monad
--   type <tt>m :: <a>Type</a> -&gt; <a>Type</a></tt> and a result type
--   <tt>a :: <a>Type</a></tt>.
type Effect = (Type -> Type) -> Type -> Type

-- | A natural transformation from <tt>f</tt> to <tt>g</tt>. With this,
--   instead of writing
--   
--   <pre>
--   runSomeEffect :: <a>Eff</a> (SomeEffect : es) a -&gt; <a>Eff</a> es a
--   </pre>
--   
--   you can write:
--   
--   <pre>
--   runSomeEffect :: <a>Eff</a> (SomeEffect : es) ~&gt; <a>Eff</a> es
--   </pre>
type f ~> g = forall a. f a -> g a

-- | Type level list concatenation.
type family xs ++ ys
infixr 5 ++

-- | The type constructor <a>Any</a> is type to which you can unsafely
--   coerce any lifted type, and back. More concretely, for a lifted type
--   <tt>t</tt> and value <tt>x :: t</tt>, -- <tt>unsafeCoerce
--   (unsafeCoerce x :: Any) :: t</tt> is equivalent to <tt>x</tt>.
type family Any :: k

-- | Coerce <a>Any</a> to a boxed value. This is <i>generally unsafe</i>
--   and it is your responsibility to ensure that the type you're coercing
--   into is the original type that the <a>Any</a> is coerced from.
fromAny :: Any -> a

-- | Coerce any boxed value into <a>Any</a>.
toAny :: a -> Any


-- | This module defines an immutable extensible record type, similar to
--   <tt>vinyl</tt> and <tt>data-diverse</tt>. However this implementation
--   focuses on fast reads, hence has very different performance
--   characteristics from other libraries:
--   
--   <ul>
--   <li>Lookup: Amortized &lt;math&gt;.</li>
--   <li>Update: &lt;math&gt;.</li>
--   <li>Shrink: &lt;math&gt;.</li>
--   <li>Append: &lt;math&gt;.</li>
--   </ul>
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal.Rec

-- | A pointer to an effect handler.
newtype HandlerPtr (e :: Effect)
HandlerPtr :: Int -> HandlerPtr (e :: Effect)
[unHandlerPtr] :: HandlerPtr (e :: Effect) -> Int

-- | Extensible record type supporting efficient &lt;math&gt; reads. The
--   underlying implementation is <a>PrimArray</a> slices.
data Rec (es :: [Effect])

-- | Type level list concatenation.
type family xs ++ ys
infixr 5 ++

-- | Create an empty record. &lt;math&gt;.
empty :: Rec '[]

-- | Prepend one entry to the record. &lt;math&gt;.
cons :: HandlerPtr e -> Rec es -> Rec (e : es)

-- | Concatenate two records. &lt;math&gt;.
concat :: Rec es -> Rec es' -> Rec (es ++ es')

-- | <tt><a>KnownList</a> es</tt> means the list <tt>es</tt> is concrete,
--   <i>i.e.</i> is of the form <tt>'[a1, a2, ..., an]</tt> instead of a
--   type variable.
class KnownList (es :: [Effect])

-- | Get the head of the record. &lt;math&gt;.
head :: Rec (e : es) -> HandlerPtr e

-- | Take elements from the top of the record. &lt;math&gt;.
take :: forall es es'. KnownList es => Rec (es ++ es') -> Rec es

-- | Slice off one entry from the top of the record. &lt;math&gt;.
tail :: Rec (e : es) -> Rec es

-- | Slice off several entries from the top of the record. &lt;math&gt;.
drop :: forall es es'. KnownList es => Rec (es ++ es') -> Rec es'

-- | <tt>e <a>:&gt;</a> es</tt> means the effect <tt>e</tt> is present in
--   the effect stack <tt>es</tt>, and therefore can be <a>send</a>ed in an
--   <tt><a>Eff</a> es</tt> computation.
class (e :: Effect) :> (es :: [Effect])
infix 0 :>

-- | <tt>es</tt> is a subset of <tt>es'</tt>, <i>i.e.</i> all elements of
--   <tt>es</tt> are in <tt>es'</tt>.
class KnownList es => Subset (es :: [Effect]) (es' :: [Effect])

-- | Get an element in the record. Amortized &lt;math&gt;.
index :: forall e es. e :> es => Rec es -> HandlerPtr e

-- | Get a subset of the record. Amortized &lt;math&gt;.
pick :: forall es es'. Subset es es' => Rec es' -> Rec es

-- | Update an entry in the record. &lt;math&gt;.
update :: forall e es. e :> es => HandlerPtr e -> Rec es -> Rec es
instance Cleff.Internal.Rec.Subset '[] es
instance (Cleff.Internal.Rec.Subset es es', e Cleff.Internal.Rec.:> es') => Cleff.Internal.Rec.Subset (e : es) es'
instance (TypeError ...) => e Cleff.Internal.Rec.:> '[]
instance e Cleff.Internal.Rec.:> (e : es)
instance (e Cleff.Internal.Rec.:> es) => e Cleff.Internal.Rec.:> (e' : es)
instance Cleff.Internal.Rec.KnownList '[]
instance Cleff.Internal.Rec.KnownList es => Cleff.Internal.Rec.KnownList (e : es)


-- | This module contains the definition of the <a>Eff</a> monad. Most of
--   the times, you won't need to use this module directly; user-facing
--   functionalities are all exported via the <a>Cleff</a> module.
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal.Monad

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

-- | The extensible effects monad. The monad <tt><a>Eff</a> es</tt> is
--   capable of performing any effect in the <i>effect stack</i>
--   <tt>es</tt>, which is a type-level list that holds all effects
--   available.
--   
--   The best practice is to always use a polymorphic type variable for the
--   effect stack <tt>es</tt>, and then use the type operators
--   <a>(:&gt;)</a> and <a>(:&gt;&gt;)</a> in constraints to indicate what
--   effects are available in the stack. For example,
--   
--   <pre>
--   (<a>Reader</a> <a>String</a> <a>:&gt;</a> es, <a>State</a> <a>Bool</a> <a>:&gt;</a> es) =&gt; <a>Eff</a> es <a>Integer</a>
--   </pre>
--   
--   means you can perform operations of the <tt><a>Reader</a>
--   <a>String</a></tt> effect and the <tt><a>State</a> <a>Bool</a></tt>
--   effect in a computation returning an <a>Integer</a>. The reason why
--   you should always use a polymorphic effect stack as opposed to a
--   concrete list of effects are that
--   
--   <ul>
--   <li>it can contain other effects that are used by computations other
--   than the current one, and</li>
--   <li>it does not require you to run the effects in any particular
--   order.</li>
--   </ul>
newtype Eff es a

-- | The effect monad receives an effect environment <a>Env</a> that
--   contains all effect handlers and produces an <a>IO</a> action.
Eff :: (Env es -> IO a) -> Eff es a
[unEff] :: Eff es a -> Env es -> IO a

-- | The <i>effect environment</i> that corresponds effects in the stack to
--   their respective <a>InternalHandler</a>s. This structure simulates
--   memory: handlers are retrieved via pointers (<a>HandlerPtr</a>s), and
--   for each effect in the stack we can either change what pointer it uses
--   or change the handler the pointer points to. The former is used for
--   global effect interpretation (<a>reinterpretN</a>) and the latter for
--   local interpretation (<a>toEffWith</a>) in order to retain correct HO
--   semantics. For more details on this see
--   <a>https://github.com/re-xyr/cleff/issues/5</a>.
data Env (es :: [Effect])

-- | A pointer to an effect handler.
data HandlerPtr (e :: Effect)

-- | Create an empty <a>Env</a> with no address allocated.
emptyEnv :: Env '[]

-- | Adjust the effect stack via an function over <a>Rec</a>.
adjustEnv :: forall es' es. (Rec es -> Rec es') -> Env es -> Env es'

-- | Allocate a new, empty address for a handler. &lt;math&gt;.
allocaEnv :: forall e es. Env es -> (# HandlerPtr e, Env es #)

-- | Read the handler a pointer points to. &lt;math&gt;.
readEnv :: forall e es. e :> es => Env es -> InternalHandler e

-- | Overwrite the handler a pointer points to. &lt;math&gt;.
writeEnv :: forall e es. HandlerPtr e -> InternalHandler e -> Env es -> Env es

-- | Replace the handler pointer of an effect in the stack. &lt;math&gt;.
replaceEnv :: forall e es. e :> es => HandlerPtr e -> InternalHandler e -> Env es -> Env es

-- | Add a new effect to the stack with its corresponding handler pointer.
--   &lt;math&gt;.
appendEnv :: forall e es. HandlerPtr e -> InternalHandler e -> Env es -> Env (e : es)

-- | Use the state of LHS as a newer version for RHS. &lt;math&gt;.
updateEnv :: forall es es'. Env es' -> Env es -> Env es

-- | <tt>e <a>:&gt;</a> es</tt> means the effect <tt>e</tt> is present in
--   the effect stack <tt>es</tt>, and therefore can be <a>send</a>ed in an
--   <tt><a>Eff</a> es</tt> computation.
class (e :: Effect) :> (es :: [Effect])
infix 0 :>

-- | <tt>xs <a>:&gt;&gt;</a> es</tt> means the list of effects <tt>xs</tt>
--   are all present in the effect stack <tt>es</tt>. This is a convenient
--   type alias for <tt>(e1 <a>:&gt;</a> es, ..., en <a>:&gt;</a> es)</tt>.
type family xs :>> es :: Constraint
infix 0 :>>

-- | <tt><a>KnownList</a> es</tt> means the list <tt>es</tt> is concrete,
--   <i>i.e.</i> is of the form <tt>'[a1, a2, ..., an]</tt> instead of a
--   type variable.
class KnownList (es :: [Effect])

-- | <tt>es</tt> is a subset of <tt>es'</tt>, <i>i.e.</i> all elements of
--   <tt>es</tt> are in <tt>es'</tt>.
class KnownList es => Subset (es :: [Effect]) (es' :: [Effect])

-- | Perform an effect operation, <i>i.e.</i> a value of an effect type
--   <tt>e :: <a>Effect</a></tt>. This requires <tt>e</tt> to be in the
--   effect stack.
send :: e :> es => e (Eff es) ~> Eff es

-- | Perform an action in another effect stack via a transformation to that
--   stack; in other words, this function "maps" the effect operation from
--   effect stack <tt>es</tt> to <tt>es'</tt>. This is a largely
--   generalized version of <a>send</a>; only use this if you are sure
--   about what you're doing.
--   
--   <pre>
--   <a>send</a> = <a>sendVia</a> <a>id</a>
--   </pre>
sendVia :: e :> es' => (Eff es ~> Eff es') -> e (Eff es) ~> Eff es'
instance GHC.Base.Functor (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Applicative (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Monad (Cleff.Internal.Monad.Eff es)
instance Control.Monad.Fix.MonadFix (Cleff.Internal.Monad.Eff es)


-- | This module contains lifted instances of some typeclasses for
--   <a>Eff</a> for convenience. They are all exported in the <a>Cleff</a>
--   module so you shouldn't need to import this module.
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal.Instances
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Cleff.Internal.Monad.Eff es a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Cleff.Internal.Monad.Eff es a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Cleff.Internal.Monad.Eff es a)
instance GHC.Num.Num a => GHC.Num.Num (Cleff.Internal.Monad.Eff es a)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Cleff.Internal.Monad.Eff es a)
instance GHC.Float.Floating a => GHC.Float.Floating (Cleff.Internal.Monad.Eff es a)
instance Data.String.IsString a => Data.String.IsString (Cleff.Internal.Monad.Eff es a)
instance Control.Monad.Zip.MonadZip (Cleff.Internal.Monad.Eff es)


-- | This module contains functions for interpreting effects. Most of the
--   times you won't need to import this directly; the module <a>Cleff</a>
--   reexports most of the functionalities.
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal.Interpret

-- | Adjust the effect stack by a contravariant transformation function
--   over the stack. This function reveals the profunctorial nature of
--   <a>Eff</a>; in particular, <a>Eff</a> is a profunctor
--   <tt>[<a>Effect</a>] -&gt; <a>Type</a></tt>, <tt>lmap</tt> is
--   <a>adjust</a>, and <tt>rmap</tt> is <a>fmap</a>.
adjust :: forall es es'. (Rec es' -> Rec es) -> Eff es ~> Eff es'

-- | Lift a computation into a bigger effect stack with one more effect.
--   For a more general version see <a>raiseN</a>.
raise :: forall e es. Eff es ~> Eff (e : es)

-- | Lift a computation into a bigger effect stack with arbitrarily more
--   effects. This function requires <tt>TypeApplications</tt>.
raiseN :: forall es' es. KnownList es' => Eff es ~> Eff (es' ++ es)

-- | Lift a computation with a fixed, known effect stack into some superset
--   of the stack.
inject :: forall es' es. Subset es' es => Eff es' ~> Eff es

-- | Eliminate a duplicate effect from the top of the effect stack. For a
--   more general version see <a>subsumeN</a>.
subsume :: forall e es. e :> es => Eff (e : es) ~> Eff es

-- | Eliminate several duplicate effects from the top of the effect stack.
--   This function requires <tt>TypeApplications</tt>.
subsumeN :: forall es' es. Subset es' es => Eff (es' ++ es) ~> Eff es

-- | Like <a>raise</a>, but adds the new effect under the top effect. This
--   is useful for transforming an interpreter <tt>e' <a>:&gt;</a> es =&gt;
--   <a>Eff</a> (e : es) <a>~&gt;</a> <a>Eff</a> es</tt> into a
--   reinterpreter <tt><a>Eff</a> (e : es) <a>~&gt;</a> <a>Eff</a> (e' :
--   es)</tt>:
--   
--   <pre>
--   myInterpreter :: Bar <a>:&gt;</a> es =&gt; <a>Eff</a> (Foo : es) <a>~&gt;</a> <a>Eff</a> es
--   myInterpreter = ...
--   
--   myReinterpreter :: <a>Eff</a> (Foo : es) <a>~&gt;</a> <a>Eff</a> (Bar : es)
--   myReinterpreter = myInterpreter <a>.</a> <a>raiseUnder</a>
--   </pre>
--   
--   In other words,
--   
--   <pre>
--   <a>reinterpret</a> h == <a>interpret</a> h . <a>raiseUnder</a>
--   </pre>
--   
--   However, note that this function is suited for transforming an
--   existing interpreter into a reinterpreter; if you want to define a
--   reinterpreter from scratch, you should still prefer
--   <a>reinterpret</a>, which is both easier to use and more efficient.
raiseUnder :: forall e' e es. Eff (e : es) ~> Eff (e : (e' : es))

-- | Like <a>raiseUnder</a>, but allows introducing multiple effects. This
--   function requires <tt>TypeApplications</tt>.
raiseNUnder :: forall es' e es. KnownList es' => Eff (e : es) ~> Eff (e : (es' ++ es))

-- | Like <a>raiseUnder</a>, but allows introducing the effect under
--   multiple effects. This function requires <tt>TypeApplications</tt>.
raiseUnderN :: forall e es' es. KnownList es' => Eff (es' ++ es) ~> Eff (es' ++ (e : es))

-- | A generalization of both <a>raiseUnderN</a> and <a>raiseNUnder</a>,
--   allowing introducing multiple effects under multiple effects. This
--   function requires <tt>TypeApplications</tt> and is subject to serious
--   type ambiguity; you most likely will need to supply all three type
--   variables explicitly.
raiseNUnderN :: forall es'' es' es. (KnownList es', KnownList es'') => Eff (es' ++ es) ~> Eff (es' ++ (es'' ++ es))

-- | The typeclass that denotes a handler scope, handling effect <tt>e</tt>
--   sent from the effect stack <tt>esSend</tt> in the effect stack
--   <tt>es</tt>.
--   
--   You should not define instances for this typeclass whatsoever.
class Handling esSend e es | esSend -> e es

-- | Get the send-site <a>Env</a>.
esSend :: Handling esSend e es => Env esSend

-- | The type of an <i>effect handler</i>, which is a function that
--   transforms an effect <tt>e</tt> from an arbitrary effect stack into
--   computations in the effect stack <tt>es</tt>.
type Handler e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> Eff es

-- | The type of a simple transformation function from effect <tt>e</tt> to
--   <tt>e'</tt>.
type Translator e e' = forall esSend. e (Eff esSend) ~> e' (Eff esSend)

-- | Interpret an effect <tt>e</tt> in terms of effects in the effect stack
--   <tt>es</tt> with an effect handler.
interpret :: forall e es. Handler e es -> Eff (e : es) ~> Eff es

-- | Like <a>interpret</a>, but adds a new effect <tt>e'</tt> to the stack
--   that can be used in the handler.
reinterpret :: forall e' e es. Handler e (e' : es) -> Eff (e : es) ~> Eff (e' : es)

-- | Like <a>reinterpret</a>, but adds two new effects.
reinterpret2 :: forall e' e'' e es. Handler e (e' : (e'' : es)) -> Eff (e : es) ~> Eff (e' : (e'' : es))

-- | Like <a>reinterpret</a>, but adds three new effects.
reinterpret3 :: forall e' e'' e''' e es. Handler e (e' : (e'' : (e''' : es))) -> Eff (e : es) ~> Eff (e' : (e'' : (e''' : es)))

-- | Like <a>reinterpret</a>, but adds arbitrarily many new effects. This
--   function requires <tt>TypeApplications</tt>.
reinterpretN :: forall es' e es. KnownList es' => Handler e (es' ++ es) -> Eff (e : es) ~> Eff (es' ++ es)

-- | Respond to an effect, but does not eliminate it from the stack. This
--   means you can re-send the operations in the effect handler; it is
--   often useful when you need to "intercept" operations so you can add
--   extra behaviors like logging.
interpose :: forall e es. e :> es => Handler e es -> Eff es ~> Eff es

-- | Like <a>interpose</a>, but allows to introduce one new effect to use
--   in the handler.
impose :: forall e' e es. e :> es => Handler e (e' : es) -> Eff es ~> Eff (e' : es)

-- | Like <a>impose</a>, but allows introducing arbitrarily many effects.
--   This requires <tt>TypeApplications</tt>.
imposeN :: forall es' e es. (KnownList es', e :> es) => Handler e (es' ++ es) -> Eff es ~> Eff (es' ++ es)

-- | Interpret an effect in terms of another effect in the stack via a
--   simple <a>Translator</a>.
--   
--   <pre>
--   <a>transform</a> trans = <a>interpret</a> (<a>sendVia</a> <a>toEff</a> <a>.</a> trans)
--   </pre>
transform :: forall e e' es. e' :> es => Translator e e' -> Eff (e : es) ~> Eff es

-- | Like <a>transform</a>, but instead of using an effect in stack, add a
--   new one to the top of it.
--   
--   <pre>
--   <a>translate</a> trans = <a>reinterpret</a> (<a>sendVia</a> <a>toEff</a> <a>.</a> trans)
--   </pre>
translate :: forall e e' es. Translator e e' -> Eff (e : es) ~> Eff (e' : es)

-- | Run a computation in the current effect stack; this is useful for
--   interpreting higher-order effects. For example, if you want to
--   interpret a bracketing effects in terms of <a>IO</a>:
--   
--   <pre>
--   data Resource m a where
--     Bracket :: m a -&gt; (a -&gt; m ()) -&gt; (a -&gt; m b) -&gt; Resource m b
--   </pre>
--   
--   You will not be able to simply write this for the effect:
--   
--   <pre>
--   runBracket :: IOE <a>:&gt;</a> es =&gt; <a>Eff</a> (Resource : es) a -&gt; <a>Eff</a> es a
--   runBracket = <a>interpret</a> \case
--     Bracket alloc dealloc use -&gt; UnliftIO.<a>bracket</a> alloc dealloc use
--   </pre>
--   
--   This is because effects are sended from all kinds of stacks that has
--   <tt>Resource</tt> in it, so effect handlers received the effect as
--   <tt>Resource esSend a</tt>, where <tt>esSend</tt> is an arbitrary
--   stack with <tt>Resource</tt>, instead of <tt>Resource es a</tt>. This
--   means <tt>alloc</tt>, <tt>dealloc</tt> and <tt>use</tt> are of type
--   <tt><a>Eff</a> esSend a</tt>, while <a>bracket</a> can only take and
--   return <tt><a>Eff</a> es a</tt>. So we need to use <a>toEff</a>, which
--   converts an <tt><a>Eff</a> esSend a</tt> into an <tt><a>Eff</a> es
--   a</tt>:
--   
--   <pre>
--   runBracket :: IOE <a>:&gt;</a> es =&gt; <a>Eff</a> (Resource : es) a -&gt; <a>Eff</a> es a
--   runBracket = <a>interpret</a> \case
--     Bracket alloc dealloc use -&gt; UnliftIO.<a>bracket</a>
--       (<a>toEff</a> alloc)
--       (<a>toEff</a> . dealloc)
--       (<a>toEff</a> . use)
--   </pre>
toEff :: Handling esSend e es => Eff esSend ~> Eff es

-- | Run a computation in the current effect stack, just like <a>toEff</a>,
--   but takes a <a>Handler</a> of the current effect being interpreted, so
--   that inside the computation being ran, the effect is interpreted
--   differently. This is useful for interpreting effects with local
--   contexts, like <a>Local</a>:
--   
--   <pre>
--   runReader :: r -&gt; <a>Eff</a> (<a>Reader</a> r : es) <a>~&gt;</a> <a>Eff</a> es
--   runReader x = <a>interpret</a> (handle x)
--     where
--       handle :: r -&gt; <a>Handler</a> (<a>Reader</a> r) es
--       handle r = \case
--         <a>Ask</a>       -&gt; <a>pure</a> r
--         <a>Local</a> f m -&gt; <a>toEffWith</a> (handle $ f r) m
--   </pre>
toEffWith :: forall esSend e es. Handling esSend e es => Handler e es -> Eff esSend ~> Eff es

-- | Temporarily gain the ability to lift some <tt><a>Eff</a> es</tt>
--   actions into <tt><a>Eff</a> esSend</tt>. This is only useful for
--   dealing with effect operations with the monad type in the negative
--   position, which means it's unlikely that you need to use this function
--   in implementing your effects.
withFromEff :: Handling esSend e es => ((Eff es ~> Eff esSend) -> Eff esSend a) -> Eff es a


-- | This module contains the <a>IOE</a> effect together with a few
--   primitives for using it, as well as interpretation combinators for
--   <a>IO</a>-related effects. It is not usually needed because safe
--   functionalities are re-exported in the <a>Cleff</a> module.
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal.Base

-- | The effect capable of lifting and unlifting the <a>IO</a> monad,
--   allowing you to use <a>MonadIO</a>, <a>MonadUnliftIO</a>,
--   <a>PrimMonad</a>, <a>MonadCatch</a>, <a>MonadThrow</a> and
--   <a>MonadMask</a> functionalities. This is the "final" effect that most
--   effects eventually are interpreted into. For example, you can do:
--   
--   <pre>
--   log :: <a>IOE</a> :&gt; es =&gt; <a>Eff</a> es ()
--   log = <a>liftIO</a> (<a>putStrLn</a> "Test logging")
--   </pre>
--   
--   It is not recommended to use this effect directly in application code,
--   as it is too liberal and allows arbitrary IO, therefore making it
--   harder to do proper effect management. Ideally, this is only used in
--   interpreting more fine-grained effects.
--   
--   <h3>Technical details</h3>
--   
--   Note that this is <i>not</i> a real effect and cannot be interpreted
--   in any way besides <a>thisIsPureTrustMe</a> and <a>runIOE</a>. This is
--   mainly for performance concern, but also that there doesn't really
--   exist reasonable interpretations other than the current one, given the
--   underlying implementation of the <a>Eff</a> monad.
--   
--   <a>IOE</a> can be a real effect though, and you can enable the
--   <tt>dynamic-ioe</tt> build flag to have that. However it is only for
--   reference purposes and should not be used in production code.
data IOE :: Effect

-- | Lift an <a>IO</a> computation into <a>Eff</a>. This function is
--   <i>highly unsafe</i> and should not be used directly; use
--   <a>liftIO</a> instead, or if you're interpreting higher-order effects,
--   use <a>fromIO</a>.
primLiftIO :: IO a -> Eff es a

-- | Give a runner function a way to run <a>Eff</a> actions as an <a>IO</a>
--   computation. This function is <i>highly unsafe</i> and should not be
--   used directly; use <a>withRunInIO</a> instead, or if you're
--   interpreting higher-order effects, use <a>withToIO</a>.
primUnliftIO :: ((Eff es ~> IO) -> IO a) -> Eff es a

-- | Unsafely eliminate an <a>IOE</a> effect from the top of the effect
--   stack. This is mainly for implementing effects that uses <a>IO</a> but
--   does not do anything really <i>impure</i> (<i>i.e.</i> can be safely
--   used <a>unsafeDupablePerformIO</a> on), such as a State effect.
thisIsPureTrustMe :: Eff (IOE : es) ~> Eff es

-- | Unwrap an <a>Eff</a> computation with side effects into an <a>IO</a>
--   computation, given that all effects other than <a>IOE</a> are
--   interpreted.
runIOE :: Eff '[IOE] ~> IO

-- | Unwrap a pure <a>Eff</a> computation into a pure value, given that all
--   effects are interpreted.
runPure :: Eff '[] a -> a

-- | The type of an <i><a>IO</a> effect handler</i>, which is a function
--   that transforms an effect <tt>e</tt> into <a>IO</a> computations. This
--   is used for <a>interpretIO</a>.
type HandlerIO e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> IO

-- | Interpret an effect in terms of <a>IO</a>, by transforming an effect
--   into <a>IO</a> computations.
--   
--   <pre>
--   <a>interpretIO</a> f = <a>interpret</a> (<a>liftIO</a> <a>.</a> f)
--   </pre>
interpretIO :: IOE :> es => HandlerIO e es -> Eff (e : es) ~> Eff es

-- | Temporarily gain the ability to unlift an <tt><a>Eff</a> esSend</tt>
--   computation into <a>IO</a>. This is analogous to <a>withRunInIO</a>,
--   and is useful in dealing with higher-order effects that involves
--   <a>IO</a>. For example, the <tt>Resource</tt> effect that supports
--   bracketing:
--   
--   <pre>
--   data Resource m a where
--     Bracket :: m a -&gt; (a -&gt; m ()) -&gt; (a -&gt; m b) -&gt; Resource m b
--   </pre>
--   
--   can be interpreted into <a>bracket</a> actions in <a>IO</a>, by
--   converting all effect computations into <a>IO</a> computations via
--   <a>withToIO</a>:
--   
--   <pre>
--   runResource :: <a>IOE</a> <a>:&gt;</a> es =&gt; <a>Eff</a> (Resource : es) a -&gt; <a>Eff</a> es a
--   runResource = <a>interpret</a> \case
--     Bracket alloc dealloc use -&gt; <a>withToIO</a> $ \toIO -&gt;
--       <a>bracket</a> (toIO alloc) (toIO . dealloc) (toIO . use)
--   </pre>
withToIO :: (Handling esSend e es, IOE :> es) => ((Eff esSend ~> IO) -> IO a) -> Eff es a

-- | Lift an <a>IO</a> computation into <tt><a>Eff</a> esSend</tt>. This is
--   analogous to <a>liftIO</a>, and is only useful in dealing with effect
--   operations with the monad type in the negative position, for example
--   <a>mask</a>ing:
--   
--   <pre>
--   data Mask :: <a>Effect</a> where
--     Mask :: ((m <a>~&gt;</a> m) -&gt; m a) -&gt; Mask m a
--                    ^ this "m" is in negative position
--   </pre>
--   
--   See how the <tt>restore :: IO a -&gt; IO a</tt> from <a>mask</a> is
--   "wrapped" into <tt><a>Eff</a> esSend a -&gt; <a>Eff</a> esSend a</tt>:
--   
--   <pre>
--   runMask :: <a>IOE</a> <a>:&gt;</a> es =&gt; <a>Eff</a> (Mask : es) a -&gt; <a>Eff</a> es a
--   runMask = <a>interpret</a> \case
--     Mask f -&gt; <a>withToIO</a> $ \toIO -&gt; <a>mask</a> $
--       \restore -&gt; f (<a>fromIO</a> . restore . toIO)
--   </pre>
--   
--   Here, <tt>toIO</tt> from <a>withToIO</a> takes an <tt><a>Eff</a>
--   esSend</tt> to <a>IO</a>, where it can be passed into the
--   <tt>restore</tt> function, and the returned <a>IO</a> computation is
--   recovered into <a>Eff</a> with <a>fromIO</a>.
fromIO :: (Handling esSend e es, IOE :> es) => IO ~> Eff esSend
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.IO.Class.MonadIO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.IO.Unlift.MonadUnliftIO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.Catch.MonadThrow (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.Catch.MonadCatch (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.Catch.MonadMask (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.Base.MonadBase GHC.Types.IO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Rec.:> es) => Control.Monad.Primitive.PrimMonad (Cleff.Internal.Monad.Eff es)


-- | This module contains Template Haskell functions for generating
--   definitions of functions that send effect operations. You mostly won't
--   want to import this module directly; The <a>Cleff</a> module reexports
--   the main functionalities of this module.
--   
--   <b>This is an <i>internal</i> module and its API may change even
--   between minor versions.</b> Therefore you should be extra careful if
--   you're to depend on this module.
module Cleff.Internal.TH

-- | For a datatype <tt>T</tt> representing an effect,
--   <tt><a>makeEffect</a> T</tt> generates function defintions for
--   performing the operations of <tt>T</tt> via <a>send</a>. For example,
--   
--   <pre>
--   <a>makeEffect</a> ''Filesystem
--   </pre>
--   
--   generates the following definitions:
--   
--   <pre>
--   readFile      :: Filesystem <a>:&gt;</a> es =&gt; <a>FilePath</a> -&gt; <a>Eff</a> es <a>String</a>
--   readFile  x   =  <a>send</a> (ReadFile x)
--   writeFile     :: Filesystem <a>:&gt;</a> es =&gt; <a>FilePath</a> -&gt; <a>String</a> -&gt; <a>Eff</a> es ()
--   writeFile x y =  <a>send</a> (WriteFile x y)
--   </pre>
--   
--   The naming rule is changing the first uppercase letter in the
--   constructor name to lowercase or removing the <tt>:</tt> symbol in the
--   case of operator constructors. Also, this function will preserve any
--   fixity declarations defined on the constructors.
--   
--   <h3>Technical details</h3>
--   
--   This function is also "weaker" than <tt>polysemy</tt>'s
--   <tt>makeSem</tt>, because this function cannot properly handle some
--   cases involving ambiguous types. Those cases are rare, though. See the
--   <tt>ThSpec</tt> test spec for more details.
makeEffect :: Name -> Q [Dec]

-- | Like <a>makeEffect</a>, but doesn't generate type signatures. This is
--   useful when you want to attach Haddock documentation to the function
--   signature, <i>e.g.</i>:
--   
--   <pre>
--   data Identity :: <a>Effect</a> where
--     Noop :: Identity m ()
--   <a>makeEffect_</a> ''Identity
--   
--   -- | Perform nothing at all.
--   noop :: Identity <a>:&gt;</a> es =&gt; <a>Eff</a> es ()
--   </pre>
--   
--   Be careful that the function signatures must be added <i>after</i> the
--   <a>makeEffect_</a> call.
makeEffect_ :: Name -> Q [Dec]


-- | This library implements an <i>extensible effects system</i>, where
--   sets of monadic actions ("effects") are encoded as datatypes, tracked
--   at the type level and can have multiple different implementations.
--   This means you can swap out implementations of certain monadic actions
--   in mock tests or in different environments. The notion of "effect" is
--   general here: it can be an <a>IO</a>-performing side effect, or just
--   reading the value of a static global environment.
--   
--   In particular, this library consists of
--   
--   <ul>
--   <li>The <a>Eff</a> monad, which is the core of an extensible effects
--   system. All effects are performed within it and it will be the "main"
--   monad of your application. This monad tracks effects at the type
--   level.</li>
--   <li>A set of predefined general effects, like <a>Reader</a> and
--   <a>State</a> that can be used out of the box.</li>
--   <li>Combinators for defining new effects and interpreting them <i>on
--   your own</i>. These effects can be translated in terms of other
--   already existing effects, or into operations in the <a>IO</a>
--   monad.</li>
--   </ul>
--   
--   In terms of structuring your application, this library helps you to do
--   two things:
--   
--   <ul>
--   <li><b>Effect management:</b> The <a>Eff</a> monad tracks what effects
--   are used explicitly at the type level, therefore you are able to
--   enforce what effects are involved in each function, and avoid
--   accidentally introduced behaviors.</li>
--   <li><b>Effect decoupling:</b> You can swap between the implementations
--   of the effects in your application easily, so you can refactor and
--   test your applications with less clutter.</li>
--   </ul>
module Cleff

-- | The extensible effects monad. The monad <tt><a>Eff</a> es</tt> is
--   capable of performing any effect in the <i>effect stack</i>
--   <tt>es</tt>, which is a type-level list that holds all effects
--   available.
--   
--   The best practice is to always use a polymorphic type variable for the
--   effect stack <tt>es</tt>, and then use the type operators
--   <a>(:&gt;)</a> and <a>(:&gt;&gt;)</a> in constraints to indicate what
--   effects are available in the stack. For example,
--   
--   <pre>
--   (<a>Reader</a> <a>String</a> <a>:&gt;</a> es, <a>State</a> <a>Bool</a> <a>:&gt;</a> es) =&gt; <a>Eff</a> es <a>Integer</a>
--   </pre>
--   
--   means you can perform operations of the <tt><a>Reader</a>
--   <a>String</a></tt> effect and the <tt><a>State</a> <a>Bool</a></tt>
--   effect in a computation returning an <a>Integer</a>. The reason why
--   you should always use a polymorphic effect stack as opposed to a
--   concrete list of effects are that
--   
--   <ul>
--   <li>it can contain other effects that are used by computations other
--   than the current one, and</li>
--   <li>it does not require you to run the effects in any particular
--   order.</li>
--   </ul>
data Eff es a

-- | <tt>e <a>:&gt;</a> es</tt> means the effect <tt>e</tt> is present in
--   the effect stack <tt>es</tt>, and therefore can be <a>send</a>ed in an
--   <tt><a>Eff</a> es</tt> computation.
class (e :: Effect) :> (es :: [Effect])
infix 0 :>

-- | <tt>xs <a>:&gt;&gt;</a> es</tt> means the list of effects <tt>xs</tt>
--   are all present in the effect stack <tt>es</tt>. This is a convenient
--   type alias for <tt>(e1 <a>:&gt;</a> es, ..., en <a>:&gt;</a> es)</tt>.
type family xs :>> es :: Constraint
infix 0 :>>

-- | The type of effects. An effect <tt>e m a</tt> takes an effect monad
--   type <tt>m :: <a>Type</a> -&gt; <a>Type</a></tt> and a result type
--   <tt>a :: <a>Type</a></tt>.
type Effect = (Type -> Type) -> Type -> Type

-- | The effect capable of lifting and unlifting the <a>IO</a> monad,
--   allowing you to use <a>MonadIO</a>, <a>MonadUnliftIO</a>,
--   <a>PrimMonad</a>, <a>MonadCatch</a>, <a>MonadThrow</a> and
--   <a>MonadMask</a> functionalities. This is the "final" effect that most
--   effects eventually are interpreted into. For example, you can do:
--   
--   <pre>
--   log :: <a>IOE</a> :&gt; es =&gt; <a>Eff</a> es ()
--   log = <a>liftIO</a> (<a>putStrLn</a> "Test logging")
--   </pre>
--   
--   It is not recommended to use this effect directly in application code,
--   as it is too liberal and allows arbitrary IO, therefore making it
--   harder to do proper effect management. Ideally, this is only used in
--   interpreting more fine-grained effects.
--   
--   <h3>Technical details</h3>
--   
--   Note that this is <i>not</i> a real effect and cannot be interpreted
--   in any way besides <a>thisIsPureTrustMe</a> and <a>runIOE</a>. This is
--   mainly for performance concern, but also that there doesn't really
--   exist reasonable interpretations other than the current one, given the
--   underlying implementation of the <a>Eff</a> monad.
--   
--   <a>IOE</a> can be a real effect though, and you can enable the
--   <tt>dynamic-ioe</tt> build flag to have that. However it is only for
--   reference purposes and should not be used in production code.
data IOE :: Effect

-- | Unwrap a pure <a>Eff</a> computation into a pure value, given that all
--   effects are interpreted.
runPure :: Eff '[] a -> a

-- | Unwrap an <a>Eff</a> computation with side effects into an <a>IO</a>
--   computation, given that all effects other than <a>IOE</a> are
--   interpreted.
runIOE :: Eff '[IOE] ~> IO

-- | Perform an effect operation, <i>i.e.</i> a value of an effect type
--   <tt>e :: <a>Effect</a></tt>. This requires <tt>e</tt> to be in the
--   effect stack.
send :: e :> es => e (Eff es) ~> Eff es

-- | Perform an action in another effect stack via a transformation to that
--   stack; in other words, this function "maps" the effect operation from
--   effect stack <tt>es</tt> to <tt>es'</tt>. This is a largely
--   generalized version of <a>send</a>; only use this if you are sure
--   about what you're doing.
--   
--   <pre>
--   <a>send</a> = <a>sendVia</a> <a>id</a>
--   </pre>
sendVia :: e :> es' => (Eff es ~> Eff es') -> e (Eff es) ~> Eff es'

-- | For a datatype <tt>T</tt> representing an effect,
--   <tt><a>makeEffect</a> T</tt> generates function defintions for
--   performing the operations of <tt>T</tt> via <a>send</a>. For example,
--   
--   <pre>
--   <a>makeEffect</a> ''Filesystem
--   </pre>
--   
--   generates the following definitions:
--   
--   <pre>
--   readFile      :: Filesystem <a>:&gt;</a> es =&gt; <a>FilePath</a> -&gt; <a>Eff</a> es <a>String</a>
--   readFile  x   =  <a>send</a> (ReadFile x)
--   writeFile     :: Filesystem <a>:&gt;</a> es =&gt; <a>FilePath</a> -&gt; <a>String</a> -&gt; <a>Eff</a> es ()
--   writeFile x y =  <a>send</a> (WriteFile x y)
--   </pre>
--   
--   The naming rule is changing the first uppercase letter in the
--   constructor name to lowercase or removing the <tt>:</tt> symbol in the
--   case of operator constructors. Also, this function will preserve any
--   fixity declarations defined on the constructors.
--   
--   <h3>Technical details</h3>
--   
--   This function is also "weaker" than <tt>polysemy</tt>'s
--   <tt>makeSem</tt>, because this function cannot properly handle some
--   cases involving ambiguous types. Those cases are rare, though. See the
--   <tt>ThSpec</tt> test spec for more details.
makeEffect :: Name -> Q [Dec]

-- | Like <a>makeEffect</a>, but doesn't generate type signatures. This is
--   useful when you want to attach Haddock documentation to the function
--   signature, <i>e.g.</i>:
--   
--   <pre>
--   data Identity :: <a>Effect</a> where
--     Noop :: Identity m ()
--   <a>makeEffect_</a> ''Identity
--   
--   -- | Perform nothing at all.
--   noop :: Identity <a>:&gt;</a> es =&gt; <a>Eff</a> es ()
--   </pre>
--   
--   Be careful that the function signatures must be added <i>after</i> the
--   <a>makeEffect_</a> call.
makeEffect_ :: Name -> Q [Dec]

-- | Lift a computation into a bigger effect stack with one more effect.
--   For a more general version see <a>raiseN</a>.
raise :: forall e es. Eff es ~> Eff (e : es)

-- | Lift a computation into a bigger effect stack with arbitrarily more
--   effects. This function requires <tt>TypeApplications</tt>.
raiseN :: forall es' es. KnownList es' => Eff es ~> Eff (es' ++ es)

-- | Lift a computation with a fixed, known effect stack into some superset
--   of the stack.
inject :: forall es' es. Subset es' es => Eff es' ~> Eff es

-- | Eliminate a duplicate effect from the top of the effect stack. For a
--   more general version see <a>subsumeN</a>.
subsume :: forall e es. e :> es => Eff (e : es) ~> Eff es

-- | Eliminate several duplicate effects from the top of the effect stack.
--   This function requires <tt>TypeApplications</tt>.
subsumeN :: forall es' es. Subset es' es => Eff (es' ++ es) ~> Eff es

-- | <tt><a>KnownList</a> es</tt> means the list <tt>es</tt> is concrete,
--   <i>i.e.</i> is of the form <tt>'[a1, a2, ..., an]</tt> instead of a
--   type variable.
class KnownList (es :: [Effect])

-- | <tt>es</tt> is a subset of <tt>es'</tt>, <i>i.e.</i> all elements of
--   <tt>es</tt> are in <tt>es'</tt>.
class KnownList es => Subset (es :: [Effect]) (es' :: [Effect])

-- | The type of an <i>effect handler</i>, which is a function that
--   transforms an effect <tt>e</tt> from an arbitrary effect stack into
--   computations in the effect stack <tt>es</tt>.
type Handler e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> Eff es

-- | Interpret an effect <tt>e</tt> in terms of effects in the effect stack
--   <tt>es</tt> with an effect handler.
interpret :: forall e es. Handler e es -> Eff (e : es) ~> Eff es

-- | Like <a>interpret</a>, but adds a new effect <tt>e'</tt> to the stack
--   that can be used in the handler.
reinterpret :: forall e' e es. Handler e (e' : es) -> Eff (e : es) ~> Eff (e' : es)

-- | Like <a>reinterpret</a>, but adds two new effects.
reinterpret2 :: forall e' e'' e es. Handler e (e' : (e'' : es)) -> Eff (e : es) ~> Eff (e' : (e'' : es))

-- | Like <a>reinterpret</a>, but adds three new effects.
reinterpret3 :: forall e' e'' e''' e es. Handler e (e' : (e'' : (e''' : es))) -> Eff (e : es) ~> Eff (e' : (e'' : (e''' : es)))

-- | Like <a>reinterpret</a>, but adds arbitrarily many new effects. This
--   function requires <tt>TypeApplications</tt>.
reinterpretN :: forall es' e es. KnownList es' => Handler e (es' ++ es) -> Eff (e : es) ~> Eff (es' ++ es)

-- | Respond to an effect, but does not eliminate it from the stack. This
--   means you can re-send the operations in the effect handler; it is
--   often useful when you need to "intercept" operations so you can add
--   extra behaviors like logging.
interpose :: forall e es. e :> es => Handler e es -> Eff es ~> Eff es

-- | Like <a>interpose</a>, but allows to introduce one new effect to use
--   in the handler.
impose :: forall e' e es. e :> es => Handler e (e' : es) -> Eff es ~> Eff (e' : es)

-- | Like <a>impose</a>, but allows introducing arbitrarily many effects.
--   This requires <tt>TypeApplications</tt>.
imposeN :: forall es' e es. (KnownList es', e :> es) => Handler e (es' ++ es) -> Eff es ~> Eff (es' ++ es)

-- | The type of an <i><a>IO</a> effect handler</i>, which is a function
--   that transforms an effect <tt>e</tt> into <a>IO</a> computations. This
--   is used for <a>interpretIO</a>.
type HandlerIO e es = forall esSend. Handling esSend e es => e (Eff esSend) ~> IO

-- | Interpret an effect in terms of <a>IO</a>, by transforming an effect
--   into <a>IO</a> computations.
--   
--   <pre>
--   <a>interpretIO</a> f = <a>interpret</a> (<a>liftIO</a> <a>.</a> f)
--   </pre>
interpretIO :: IOE :> es => HandlerIO e es -> Eff (e : es) ~> Eff es

-- | The type of a simple transformation function from effect <tt>e</tt> to
--   <tt>e'</tt>.
type Translator e e' = forall esSend. e (Eff esSend) ~> e' (Eff esSend)

-- | Interpret an effect in terms of another effect in the stack via a
--   simple <a>Translator</a>.
--   
--   <pre>
--   <a>transform</a> trans = <a>interpret</a> (<a>sendVia</a> <a>toEff</a> <a>.</a> trans)
--   </pre>
transform :: forall e e' es. e' :> es => Translator e e' -> Eff (e : es) ~> Eff es

-- | Like <a>transform</a>, but instead of using an effect in stack, add a
--   new one to the top of it.
--   
--   <pre>
--   <a>translate</a> trans = <a>reinterpret</a> (<a>sendVia</a> <a>toEff</a> <a>.</a> trans)
--   </pre>
translate :: forall e e' es. Translator e e' -> Eff (e : es) ~> Eff (e' : es)

-- | Like <a>raise</a>, but adds the new effect under the top effect. This
--   is useful for transforming an interpreter <tt>e' <a>:&gt;</a> es =&gt;
--   <a>Eff</a> (e : es) <a>~&gt;</a> <a>Eff</a> es</tt> into a
--   reinterpreter <tt><a>Eff</a> (e : es) <a>~&gt;</a> <a>Eff</a> (e' :
--   es)</tt>:
--   
--   <pre>
--   myInterpreter :: Bar <a>:&gt;</a> es =&gt; <a>Eff</a> (Foo : es) <a>~&gt;</a> <a>Eff</a> es
--   myInterpreter = ...
--   
--   myReinterpreter :: <a>Eff</a> (Foo : es) <a>~&gt;</a> <a>Eff</a> (Bar : es)
--   myReinterpreter = myInterpreter <a>.</a> <a>raiseUnder</a>
--   </pre>
--   
--   In other words,
--   
--   <pre>
--   <a>reinterpret</a> h == <a>interpret</a> h . <a>raiseUnder</a>
--   </pre>
--   
--   However, note that this function is suited for transforming an
--   existing interpreter into a reinterpreter; if you want to define a
--   reinterpreter from scratch, you should still prefer
--   <a>reinterpret</a>, which is both easier to use and more efficient.
raiseUnder :: forall e' e es. Eff (e : es) ~> Eff (e : (e' : es))

-- | Like <a>raiseUnder</a>, but allows introducing multiple effects. This
--   function requires <tt>TypeApplications</tt>.
raiseNUnder :: forall es' e es. KnownList es' => Eff (e : es) ~> Eff (e : (es' ++ es))

-- | Like <a>raiseUnder</a>, but allows introducing the effect under
--   multiple effects. This function requires <tt>TypeApplications</tt>.
raiseUnderN :: forall e es' es. KnownList es' => Eff (es' ++ es) ~> Eff (es' ++ (e : es))

-- | A generalization of both <a>raiseUnderN</a> and <a>raiseNUnder</a>,
--   allowing introducing multiple effects under multiple effects. This
--   function requires <tt>TypeApplications</tt> and is subject to serious
--   type ambiguity; you most likely will need to supply all three type
--   variables explicitly.
raiseNUnderN :: forall es'' es' es. (KnownList es', KnownList es'') => Eff (es' ++ es) ~> Eff (es' ++ (es'' ++ es))

-- | The typeclass that denotes a handler scope, handling effect <tt>e</tt>
--   sent from the effect stack <tt>esSend</tt> in the effect stack
--   <tt>es</tt>.
--   
--   You should not define instances for this typeclass whatsoever.
class Handling esSend e es | esSend -> e es

-- | Run a computation in the current effect stack; this is useful for
--   interpreting higher-order effects. For example, if you want to
--   interpret a bracketing effects in terms of <a>IO</a>:
--   
--   <pre>
--   data Resource m a where
--     Bracket :: m a -&gt; (a -&gt; m ()) -&gt; (a -&gt; m b) -&gt; Resource m b
--   </pre>
--   
--   You will not be able to simply write this for the effect:
--   
--   <pre>
--   runBracket :: IOE <a>:&gt;</a> es =&gt; <a>Eff</a> (Resource : es) a -&gt; <a>Eff</a> es a
--   runBracket = <a>interpret</a> \case
--     Bracket alloc dealloc use -&gt; UnliftIO.<a>bracket</a> alloc dealloc use
--   </pre>
--   
--   This is because effects are sended from all kinds of stacks that has
--   <tt>Resource</tt> in it, so effect handlers received the effect as
--   <tt>Resource esSend a</tt>, where <tt>esSend</tt> is an arbitrary
--   stack with <tt>Resource</tt>, instead of <tt>Resource es a</tt>. This
--   means <tt>alloc</tt>, <tt>dealloc</tt> and <tt>use</tt> are of type
--   <tt><a>Eff</a> esSend a</tt>, while <a>bracket</a> can only take and
--   return <tt><a>Eff</a> es a</tt>. So we need to use <a>toEff</a>, which
--   converts an <tt><a>Eff</a> esSend a</tt> into an <tt><a>Eff</a> es
--   a</tt>:
--   
--   <pre>
--   runBracket :: IOE <a>:&gt;</a> es =&gt; <a>Eff</a> (Resource : es) a -&gt; <a>Eff</a> es a
--   runBracket = <a>interpret</a> \case
--     Bracket alloc dealloc use -&gt; UnliftIO.<a>bracket</a>
--       (<a>toEff</a> alloc)
--       (<a>toEff</a> . dealloc)
--       (<a>toEff</a> . use)
--   </pre>
toEff :: Handling esSend e es => Eff esSend ~> Eff es

-- | Run a computation in the current effect stack, just like <a>toEff</a>,
--   but takes a <a>Handler</a> of the current effect being interpreted, so
--   that inside the computation being ran, the effect is interpreted
--   differently. This is useful for interpreting effects with local
--   contexts, like <a>Local</a>:
--   
--   <pre>
--   runReader :: r -&gt; <a>Eff</a> (<a>Reader</a> r : es) <a>~&gt;</a> <a>Eff</a> es
--   runReader x = <a>interpret</a> (handle x)
--     where
--       handle :: r -&gt; <a>Handler</a> (<a>Reader</a> r) es
--       handle r = \case
--         <a>Ask</a>       -&gt; <a>pure</a> r
--         <a>Local</a> f m -&gt; <a>toEffWith</a> (handle $ f r) m
--   </pre>
toEffWith :: forall esSend e es. Handling esSend e es => Handler e es -> Eff esSend ~> Eff es

-- | Temporarily gain the ability to lift some <tt><a>Eff</a> es</tt>
--   actions into <tt><a>Eff</a> esSend</tt>. This is only useful for
--   dealing with effect operations with the monad type in the negative
--   position, which means it's unlikely that you need to use this function
--   in implementing your effects.
withFromEff :: Handling esSend e es => ((Eff es ~> Eff esSend) -> Eff esSend a) -> Eff es a

-- | Temporarily gain the ability to unlift an <tt><a>Eff</a> esSend</tt>
--   computation into <a>IO</a>. This is analogous to <a>withRunInIO</a>,
--   and is useful in dealing with higher-order effects that involves
--   <a>IO</a>. For example, the <tt>Resource</tt> effect that supports
--   bracketing:
--   
--   <pre>
--   data Resource m a where
--     Bracket :: m a -&gt; (a -&gt; m ()) -&gt; (a -&gt; m b) -&gt; Resource m b
--   </pre>
--   
--   can be interpreted into <a>bracket</a> actions in <a>IO</a>, by
--   converting all effect computations into <a>IO</a> computations via
--   <a>withToIO</a>:
--   
--   <pre>
--   runResource :: <a>IOE</a> <a>:&gt;</a> es =&gt; <a>Eff</a> (Resource : es) a -&gt; <a>Eff</a> es a
--   runResource = <a>interpret</a> \case
--     Bracket alloc dealloc use -&gt; <a>withToIO</a> $ \toIO -&gt;
--       <a>bracket</a> (toIO alloc) (toIO . dealloc) (toIO . use)
--   </pre>
withToIO :: (Handling esSend e es, IOE :> es) => ((Eff esSend ~> IO) -> IO a) -> Eff es a

-- | Lift an <a>IO</a> computation into <tt><a>Eff</a> esSend</tt>. This is
--   analogous to <a>liftIO</a>, and is only useful in dealing with effect
--   operations with the monad type in the negative position, for example
--   <a>mask</a>ing:
--   
--   <pre>
--   data Mask :: <a>Effect</a> where
--     Mask :: ((m <a>~&gt;</a> m) -&gt; m a) -&gt; Mask m a
--                    ^ this "m" is in negative position
--   </pre>
--   
--   See how the <tt>restore :: IO a -&gt; IO a</tt> from <a>mask</a> is
--   "wrapped" into <tt><a>Eff</a> esSend a -&gt; <a>Eff</a> esSend a</tt>:
--   
--   <pre>
--   runMask :: <a>IOE</a> <a>:&gt;</a> es =&gt; <a>Eff</a> (Mask : es) a -&gt; <a>Eff</a> es a
--   runMask = <a>interpret</a> \case
--     Mask f -&gt; <a>withToIO</a> $ \toIO -&gt; <a>mask</a> $
--       \restore -&gt; f (<a>fromIO</a> . restore . toIO)
--   </pre>
--   
--   Here, <tt>toIO</tt> from <a>withToIO</a> takes an <tt><a>Eff</a>
--   esSend</tt> to <a>IO</a>, where it can be passed into the
--   <tt>restore</tt> function, and the returned <a>IO</a> computation is
--   recovered into <a>Eff</a> with <a>fromIO</a>.
fromIO :: (Handling esSend e es, IOE :> es) => IO ~> Eff esSend

-- | A natural transformation from <tt>f</tt> to <tt>g</tt>. With this,
--   instead of writing
--   
--   <pre>
--   runSomeEffect :: <a>Eff</a> (SomeEffect : es) a -&gt; <a>Eff</a> es a
--   </pre>
--   
--   you can write:
--   
--   <pre>
--   runSomeEffect :: <a>Eff</a> (SomeEffect : es) ~&gt; <a>Eff</a> es
--   </pre>
type f ~> g = forall a. f a -> g a

-- | Type level list concatenation.
type family xs ++ ys
infixr 5 ++

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: Type -> Type)

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => IO a -> m a

-- | Monads which allow their actions to be run in <a>IO</a>.
--   
--   While <a>MonadIO</a> allows an <a>IO</a> action to be lifted into
--   another monad, this class captures the opposite concept: allowing you
--   to capture the monadic context. Note that, in order to meet the laws
--   given below, the intuition is that a monad must have no monadic state,
--   but may have monadic context. This essentially limits
--   <a>MonadUnliftIO</a> to <a>ReaderT</a> and <a>IdentityT</a>
--   transformers on top of <a>IO</a>.
--   
--   Laws. For any value <tt>u</tt> returned by <a>askUnliftIO</a>, it must
--   meet the monad transformer laws as reformulated for
--   <tt>MonadUnliftIO</tt>:
--   
--   <ul>
--   <li><pre>unliftIO u . return = return</pre></li>
--   <li><pre>unliftIO u (m &gt;&gt;= f) = unliftIO u m &gt;&gt;= unliftIO
--   u . f</pre></li>
--   </ul>
--   
--   Instances of <tt>MonadUnliftIO</tt> must also satisfy the idempotency
--   law:
--   
--   <ul>
--   <li><pre>askUnliftIO &gt;&gt;= \u -&gt; (liftIO . unliftIO u) m =
--   m</pre></li>
--   </ul>
--   
--   This law showcases two properties. First, <a>askUnliftIO</a> doesn't
--   change the monadic context, and second, <tt>liftIO . unliftIO u</tt>
--   is equivalent to <tt>id</tt> IF called in the same monadic context as
--   <a>askUnliftIO</a>.
class MonadIO m => MonadUnliftIO (m :: Type -> Type)

-- | Convenience function for capturing the monadic context and running an
--   <a>IO</a> action with a runner function. The runner function is used
--   to run a monadic action <tt>m</tt> in <tt>IO</tt>.
withRunInIO :: MonadUnliftIO m => ((forall a. () => m a -> IO a) -> IO b) -> m b


module Cleff.Error

-- | An effect capable of breaking out of current control flow by throwing
--   an error of type <tt>e</tt>, and handling the errors thrown from
--   computations. This effect roughly corresponds to the
--   <tt>MonadError</tt> typeclass and <tt>ExceptT</tt> monad transformer
--   in <tt>mtl</tt>.
data Error e :: Effect
[ThrowError] :: e -> Error e m a
[CatchError] :: m a -> (e -> m a) -> Error e m a

-- | Throw an error in the current computation.
throwError :: Error e :> es => e -> Eff es a

-- | Handle an error if one is thrown from a computation, and then return
--   to normal control flow.
catchError :: Error e :> es => Eff es a -> (e -> Eff es a) -> Eff es a

-- | Lift an <a>Either</a> value into the <a>Error</a> effect.
fromEither :: Error e :> es => Either e a -> Eff es a

-- | Lift exceptions generated by an <a>IO</a> computation into the
--   <a>Error</a> effect.
fromException :: forall e es a. (Exception e, '[Error e, IOE] :>> es) => IO a -> Eff es a

-- | Like <a>fromException</a>, but allows to transform the exception into
--   another error type.
fromExceptionVia :: (Exception ex, '[Error er, IOE] :>> es) => (ex -> er) -> IO a -> Eff es a

-- | Lift exceptions generated by an <a>Eff</a> computation into the
--   <a>Error</a> effect.
fromExceptionEff :: forall e es a. (Exception e, '[Error e, IOE] :>> es) => Eff es a -> Eff es a

-- | Like <a>fromExceptionEff</a>, but allows to transform the exception
--   into another error type.
fromExceptionEffVia :: (Exception ex, '[Error er, IOE] :>> es) => (ex -> er) -> Eff es a -> Eff es a

-- | Try to extract a value from <a>Maybe</a>, throw an error otherwise.
note :: Error e :> es => e -> Maybe a -> Eff es a

-- | A variant of <a>catchError</a> that allows a predicate to choose
--   whether to catch (<a>Just</a>) or rethrow (<a>Nothing</a>) the error.
catchErrorJust :: Error e :> es => (e -> Maybe b) -> Eff es a -> (b -> Eff es a) -> Eff es a

-- | A variant of <a>catchError</a> that allows a predicate to choose
--   whether to catch (<a>True</a>) or rethrow (<a>False</a>) the error.
catchErrorIf :: Error e :> es => (e -> Bool) -> Eff es a -> (e -> Eff es a) -> Eff es a

-- | Flipped version of <a>catchError</a>.
handleError :: Error e :> es => (e -> Eff es a) -> Eff es a -> Eff es a

-- | Flipped version of <a>catchErrorJust</a>.
handleErrorJust :: Error e :> es => (e -> Maybe b) -> (b -> Eff es a) -> Eff es a -> Eff es a

-- | Flipped version of <a>catchErrorIf</a>.
handleErrorIf :: Error e :> es => (e -> Bool) -> (e -> Eff es a) -> Eff es a -> Eff es a

-- | Runs a computation, returning a <a>Left</a> value if an error was
--   thrown.
tryError :: Error e :> es => Eff es a -> Eff es (Either e a)

-- | A variant of <a>tryError</a> that allows a predicate to choose whether
--   to catch (<a>True</a>) or rethrow (<a>False</a>) the error.
tryErrorJust :: Error e :> es => (e -> Maybe b) -> Eff es a -> Eff es (Either b a)

-- | Run an <a>Error</a> effect.
--   
--   <h3>Caveats</h3>
--   
--   <a>runError</a> is implemented with <a>Exception</a>s therefore
--   inherits some of its unexpected behaviors. Errors thrown in forked
--   threads will <i>not</i> be directly caught by <a>catchError</a>s in
--   the parent thread. Instead it will incur an exception, and we won't be
--   quite able to display the details of that exception properly at that
--   point. Therefore please properly handle the errors in the forked
--   threads separately.
--   
--   However if you use <tt>async</tt> and <tt>wait</tt> for the action in
--   the same effect scope (<i>i.e.</i> they get to be interpreted by the
--   same <a>runError</a> handler), the error <i>will</i> be caught in the
--   parent thread even if you don't deal with it in the forked thread. But
--   if you passed the <tt>Async</tt> value out of the effect scope and
--   <tt>wait</tt>ed for it elsewhere, the error will again not be caught.
--   The best choice is <i>not to pass <tt>Async</tt> values around
--   randomly</i>.
runError :: forall e es a. Eff (Error e : es) a -> Eff es (Either e a)

-- | Transform an <a>Error</a> into another. This is useful for aggregating
--   multiple errors into one type.
mapError :: forall e e' es. Error e' :> es => (e -> e') -> Eff (Error e : es) ~> Eff es
instance GHC.Exception.Type.Exception Cleff.Error.ErrorExc
instance GHC.Show.Show Cleff.Error.ErrorExc


module Cleff.Fail

-- | An effect that expresses failure with a message. This effect allows
--   the use of the <a>MonadFail</a> class.
data Fail :: Effect
[Fail] :: String -> Fail m a

-- | Run a <a>Fail</a> effect in terms of <a>Error</a>.
runFail :: Eff (Fail : es) a -> Eff es (Either String a)

-- | Run a <a>Fail</a> effect in terms of throwing exceptions in <a>IO</a>.
runFailIO :: IOE :> es => Eff (Fail : es) ~> Eff es
instance (Cleff.Fail.Fail Cleff.Internal.Rec.:> es) => Control.Monad.Fail.MonadFail (Cleff.Internal.Monad.Eff es)


module Cleff.Mask

-- | An effect capable of <a>mask</a>ing and performing cleanup operations
--   when an computation is interrupted. In particular, this effects allows
--   the use of <a>bracket</a>.
--   
--   <h3>Technical details</h3>
--   
--   Regarding the nuances of <a>bracket</a> semantics, this effect uses
--   the semantics of <a>UnliftIO.Exception</a> rather than
--   <a>Control.Exception</a>. They are more sensible defaults and users
--   can implement other semantics out of the primitive operations if they
--   want to.
data Mask :: Effect
[Mask] :: ((m ~> m) -> m a) -> Mask m a
[UninterruptibleMask] :: ((m ~> m) -> m a) -> Mask m a
[OnException] :: m a -> m b -> Mask m a

-- | Run a computation that acquires a resource (<tt>alloc</tt>), then a
--   main computation using that resource, then a cleanup computation
--   (<tt>dealloc</tt>). <a>bracket</a> guarantees that <tt>alloc</tt> and
--   <tt>dealloc</tt> will always run, regardless of whether an exception
--   is thrown in the main computation. Note that if an exception is thrown
--   in the main computation, it will be rethrown after <a>bracket</a>
--   finishes.
--   
--   <h3>Technical details</h3>
--   
--   Note that this function uses <tt>unliftio</tt> semantics: resource
--   acquiring action is interruptibly <a>mask</a>ed while resource cleanup
--   is <a>uninterruptibleMask</a>ed. Most of the times, this will be what
--   you want. Other functions in this module use <tt>unliftio</tt>
--   semantics too.
bracket :: Mask :> es => Eff es a -> (a -> Eff es c) -> (a -> Eff es b) -> Eff es b

-- | Like <a>bracket</a>, but only runs cleanup if an exception is thrown
--   in the main computation.
bracketOnError :: Mask :> es => Eff es a -> (a -> Eff es c) -> (a -> Eff es b) -> Eff es b

-- | Variant of <a>bracket</a> that does not pass the allocated resource to
--   the cleanup action.
bracket_ :: Mask :> es => Eff es a -> Eff es c -> (a -> Eff es b) -> Eff es b

-- | Variant of <a>bracketOnError</a> that does not pass the allocated
--   resource to the cleanup action.
bracketOnError_ :: Mask :> es => Eff es a -> Eff es c -> (a -> Eff es b) -> Eff es b

-- | Attach an action that runs if the main computation throws an
--   exception. Note that this will rethrow the exception instead of
--   returning to normal control flow.
--   
--   The cleanup action is guaranteed not to be interrupted halfways.
onError :: Mask :> es => Eff es a -> Eff es b -> Eff es a

-- | Attach a cleanup action that will always run after a potentially
--   throwing computation.
finally :: Mask :> es => Eff es a -> Eff es b -> Eff es a

-- | Prevents a computation from receiving asynchronous exceptions,
--   <i>i.e.</i> being interrupted by another thread. Also provides a
--   function to restore receiving async exceptions for a computation.
--   
--   However, some potentially blocking actions like <tt>takeMVar</tt> can
--   still be interrupted, and for them also not to be interrupted in any
--   case you'll need <a>uninterruptibleMask</a>. See <a>mask</a> for
--   details.
mask :: Mask :> es => ((Eff es ~> Eff es) -> Eff es a) -> Eff es a

-- | Prevents a computation from receiving asynchronous exceptions, even if
--   there is an interruptible operation (operations that potentially
--   deadlocks or otherwise blocks indefinitely). Therefore this function
--   is potentially dangerous in the sense that it can make a thread both
--   unresponsive and unkillable. See <a>uninterruptibleMask</a> for
--   details.
uninterruptibleMask :: Mask :> es => ((Eff es ~> Eff es) -> Eff es a) -> Eff es a

-- | Like <a>onError</a>, but without <a>uninterruptibleMask</a>ing the
--   cleanup action, making it possible that a cleanup action is
--   interrupted. Use <a>onError</a> is usually the safer option.
onException :: Mask :> es => Eff es a -> Eff es b -> Eff es a

-- | Variant of <a>mask</a> that does not provide a restoring function.
mask_ :: Mask :> es => Eff es a -> Eff es a

-- | Variant of <a>uninterruptibleMask</a> that does not provide a
--   restoring function.
uninterruptibleMask_ :: Mask :> es => Eff es a -> Eff es a

-- | Interpret the <a>Mask</a> effect in terms of primitive <a>IO</a>
--   actions.
runMask :: Eff (Mask : es) ~> Eff es


module Cleff.Reader

-- | An effect capable of providing an immutable environment <tt>r</tt>
--   that can be read. This roughly corresponds to the <tt>MonadReader</tt>
--   typeclass and <tt>ReaderT</tt> monad transformer in the <tt>mtl</tt>
--   library.
data Reader r :: Effect
[Ask] :: Reader r m r
[Local] :: (r -> r) -> m a -> Reader r m a

-- | Obtain the environment value.
ask :: Reader r :> es => Eff es r

-- | Modify the environment value temporarily for a computation.
local :: Reader r :> es => (r -> r) -> Eff es a -> Eff es a

-- | Apply a function to the result of <a>ask</a>.
asks :: Reader r :> es => (r -> s) -> Eff es s

-- | Run a <a>Reader</a> effect with a given environment value.
runReader :: r -> Eff (Reader r : es) ~> Eff es

-- | Run a <a>Reader</a> effect in terms of a larger <a>Reader</a> via a
--   <a>Lens'</a>.
magnify :: Reader t :> es => Lens' t r -> Eff (Reader r : es) ~> Eff es


module Cleff.State

-- | An effect capable of providing a mutable state <tt>s</tt> that can be
--   read and written. This roughly corresponds to the <tt>MonadState</tt>
--   typeclass and <tt>StateT</tt> monad transformer in the <tt>mtl</tt>
--   library.
data State s :: Effect
[Get] :: State s m s
[Put] :: s -> State s m ()
[State] :: (s -> (a, s)) -> State s m a

-- | Read the current state.
get :: State s :> es => Eff es s

-- | Update the state with a new value.
put :: State s :> es => s -> Eff es ()

-- | Modify the state <i>and</i> produce a value from the state via a
--   function.
state :: State s :> es => (s -> (a, s)) -> Eff es a

-- | Apply a function to the result of <a>get</a>.
gets :: State s :> es => (s -> t) -> Eff es t

-- | Modify the value of the state via a function.
modify :: State s :> es => (s -> s) -> Eff es ()

-- | Run the <a>State</a> effect.
--   
--   <h3>Caveats</h3>
--   
--   The <a>runState</a> interpreter is implemented with <a>IORef</a>s and
--   there is no way to do arbitrary atomic transactions. The <a>state</a>
--   operation is atomic though and it is implemented with
--   <a>atomicModifyIORefCAS</a>, which can be faster than
--   <tt>atomicModifyIORef</tt> in contention. For any more complicated
--   cases of atomicity, please build your own effect that uses either
--   <tt>MVar</tt>s or <tt>TVar</tt>s based on your need.
--   
--   Unlike <tt>mtl</tt>, in <tt>cleff</tt> the state <i>will not
--   revert</i> when an error is thrown.
--   
--   <a>runState</a> will stop taking care of state operations done on
--   forked threads as soon as the main thread finishes its computation.
--   Any state operation done <i>before main thread finishes</i> is still
--   taken into account.
runState :: s -> Eff (State s : es) a -> Eff es (a, s)

-- | Run the <a>State</a> effect in terms of operations on a supplied
--   <a>IORef</a>. The <a>state</a> operation is atomic.
runStateIORef :: IOE :> es => IORef s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect in terms of operations on a supplied
--   <a>MVar</a>.
runStateMVar :: IOE :> es => MVar s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect in terms of operations on a supplied
--   <a>TVar</a>.
runStateTVar :: IOE :> es => TVar s -> Eff (State s : es) a -> Eff es a

-- | Run a <a>State</a> effect in terms of a larger <a>State</a> via a
--   <a>Lens'</a>.
zoom :: State t :> es => Lens' t s -> Eff (State s : es) ~> Eff es


module Cleff.Input

-- | An effect that is capable of reading from some input source, such as
--   an input stream.
data Input i :: Effect
[Input] :: Input i m i

-- | Read an input value from an input source.
input :: Input i :> es => Eff es i

-- | Apply a function to the result of <a>input</a>.
inputs :: Input i :> es => (i -> i') -> Eff es i'

-- | Run an <a>Input</a> effect by giving a constant input value.
runInputConst :: i -> Eff (Input i : es) ~> Eff es

-- | Run an <a>Input</a> effect by going through a list of values.
inputToListState :: Eff (Input (Maybe i) : es) ~> Eff (State [i] : es)

-- | Run an <a>Input</a> in terms of a <a>Reader</a>.
inputToReader :: Eff (Input i : es) ~> Eff (Reader i : es)

-- | Run an <a>Input</a> effect by performing a computation for each input
--   request.
runInputEff :: Eff es i -> Eff (Input i : es) ~> Eff es

-- | Transform an <a>Input</a> effect into another one already in the
--   effect stack, by a pure function.
mapInput :: Input i' :> es => (i' -> i) -> Eff (Input i : es) ~> Eff es

-- | Transform an <a>Input</a> effect into another one already in the
--   effect stack, by an effectful computation.
bindInput :: Input i' :> es => (i' -> Eff es i) -> Eff (Input i : es) ~> Eff es


module Cleff.Fresh

-- | An effect capable of generating unique values. This effect can be
--   useful in generating variable indices.
data Fresh u :: Effect
[Fresh] :: Fresh u m u

-- | Obtain a fresh unique value.
fresh :: Fresh u :> es => Eff es u

-- | Interpret a <tt><a>Fresh</a> <a>Int</a></tt> effect in terms of
--   <tt><a>State</a> <a>Int</a></tt>. This is a specialized version of
--   <a>freshEnumToState</a>.
freshIntToState :: Eff (Fresh Int : es) ~> Eff (State Int : es)

-- | Interpret a <tt><a>Fresh</a> a</tt> in terms of <tt><a>State</a>
--   a</tt> for any <a>Enum</a>. Every time <a>succ</a> is called to
--   generate the next value.
freshEnumToState :: Enum a => Eff (Fresh a : es) ~> Eff (State a : es)

-- | Interpret a <tt><a>Fresh</a> <a>Int</a></tt> effect in terms of a
--   <a>AtomicCounter</a>. This is usually faster than
--   <a>runFreshUnique</a>.
runFreshAtomicCounter :: Eff (Fresh Int : es) ~> Eff es

-- | Interpret a <tt><a>Fresh</a> <a>Unique</a></tt> effect in terms of IO
--   actions. This is slower than <a>runFreshAtomicCounter</a>, but it
--   won't overflow on <tt><a>maxBound</a> :: <a>Int</a></tt>.
runFreshUnique :: IOE :> es => Eff (Fresh Unique : es) ~> Eff es


module Cleff.Writer

-- | An effect capable of accumulating monoidal outputs. This roughly
--   corresponds to the <tt>MonadWriter</tt> typeclass and <tt>WriterT</tt>
--   monad transformer in the <tt>mtl</tt> library.
--   
--   However, note that this does not have a <tt>pass</tt> operation as we
--   are not sure what its semantics should be. In fact, the <tt>pass</tt>
--   semantics in <tt>mtl</tt> is also unclear and will change when
--   handlers are put in different orders. To avoid any confusion we
--   decided it is best that we don't include it because no one seems to be
--   relying on it anyway.
data Writer w :: Effect
[Tell] :: w -> Writer w m ()
[Listen] :: m a -> Writer w m (a, w)

-- | Produces an output that is appended to the accumulated value.
tell :: Writer w :> es => w -> Eff es ()

-- | Monitor the output of a computation, and return the output alongside
--   the computation's result.
listen :: Writer w :> es => Eff es a -> Eff es (a, w)

-- | Apply a function to the accumulated output of <a>listen</a>.
listens :: Writer w :> es => (w -> x) -> Eff es a -> Eff es (a, x)

-- | Run a monoidal <a>Writer</a> effect.
--   
--   <h3>Caveats</h3>
--   
--   Both <a>runWriter</a> and <a>listen</a>s under <a>runWriter</a> will
--   stop taking care of writer operations done on forked threads as soon
--   as the main thread finishes its computation. Any writer operation done
--   <i>before main thread finishes</i> is still taken into account.
runWriter :: forall w es a. Monoid w => Eff (Writer w : es) a -> Eff es (a, w)

-- | Run a monoidal <a>Writer</a> effect, but appends the listened output
--   to the parent value only when the listen operation finishes. This
--   means that when you run two <a>listen</a>s on two threads, the values
--   <a>tell</a>ed inside will not be appended to the parent value in real
--   time, but only after the thread finishes <a>listen</a>ing. For
--   example, this code
--   
--   <pre>
--   <a>concurrently_</a>
--     (<a>listen</a> <a>$</a> <a>tell</a> "1" <a>&gt;&gt;</a> <a>tell</a> "2" <a>&gt;&gt;</a> <a>tell</a> "3")
--     (<a>listen</a> <a>$</a> <a>tell</a> "4" <a>&gt;&gt;</a> <a>tell</a> "5" <a>&gt;&gt;</a> <a>tell</a> "6")
--   </pre>
--   
--   will produce either <tt>"123456"</tt> or <tt>"456123"</tt> with
--   <a>runWriterBatch</a>, but may produce these digits in any order with
--   <a>runWriter</a>.
--   
--   This version of interpreter can be faster than <a>runWriter</a> in
--   <a>listen</a>-intense code. It is subject to all caveats of
--   <a>runWriter</a>.
runWriterBatch :: forall w es a. Monoid w => Eff (Writer w : es) a -> Eff es (a, w)


module Cleff.Output

-- | An effect that is capable of producing outputs, for example writing to
--   a log file or an output stream.
data Output o :: Effect
[Output] :: o -> Output o m ()

-- | Produce an output value.
output :: Output o :> es => o -> Eff es ()

-- | Run an <a>Output</a> effect by accumulating a list. Note that outputs
--   are being prepended to the head of the list, so in many cases you
--   would want to <a>reverse</a> the result.
outputToListState :: Eff (Output o : es) ~> Eff (State [o] : es)

-- | Run an <a>Output</a> effect by translating it into a <a>Writer</a>.
outputToWriter :: (o -> o') -> Eff (Output o : es) ~> Eff (Writer o' : es)

-- | Ignore outputs of an <a>Output</a> effect altogether.
ignoreOutput :: Eff (Output o : es) ~> Eff es

-- | Run an <a>Output</a> effect by performing a computation for each
--   output.
runOutputEff :: (o -> Eff es ()) -> Eff (Output o : es) ~> Eff es

-- | Transform an <a>Output</a> effect into another one already in the
--   effect stack, by a pure function.
mapOutput :: Output o' :> es => (o -> o') -> Eff (Output o : es) ~> Eff es

-- | Transform an <a>Output</a> effect into another one already in the
--   effect stack, by an effectful computation.
bindOutput :: Output o' :> es => (o -> Eff es o') -> Eff (Output o : es) ~> Eff es


module Cleff.Trace

-- | An effect capable of logging messages, mostly for debugging purposes.
data Trace :: Effect
[Trace] :: String -> Trace m ()

-- | Output a trace message.
trace :: Trace :> es => String -> Eff es ()

-- | Run the <a>Trace</a> effect by writing to a <a>Handle</a>.
runTraceHandle :: IOE :> es => Handle -> Eff (Trace : es) a -> Eff es a

-- | Run the <a>Trace</a> effect by writing to <a>stdout</a>.
runTraceStdout :: IOE :> es => Eff (Trace : es) ~> Eff es

-- | Run the <a>Trace</a> effect by writing to <a>stderr</a>.
runTraceStderr :: IOE :> es => Eff (Trace : es) ~> Eff es

-- | Run the <a>Trace</a> effect by ignoring all outputs altogether.
ignoreTrace :: Eff (Trace : es) ~> Eff es

-- | Transform the <a>Trace</a> effect into an <tt><a>Output</a>
--   <a>String</a></tt> effect.
traceToOutput :: Eff (Trace : es) ~> Eff (Output String : es)