-- 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.1.0.0


-- | This module contains utility functions for <a>Any</a>.
--   
--   <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 Data.Any

-- | 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 Data.Rec

-- | Extensible record type supporting efficient &lt;math&gt; reads. The
--   underlying implementation is <a>SmallArray</a> slices, therefore suits
--   small numbers of entries (<i>i.e.</i> less than 128).
data Rec (f :: k -> Type) (es :: [k])

-- | Get the length of the record.
length :: Rec f es -> Int

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

-- | Create a record with one entry. &lt;math&gt;.
singleton :: f e -> Rec f '[e]

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

-- | Infix version of <a>cons</a> that also supports destructuring.
pattern (:~:) :: f e -> Rec f es -> Rec f (e : es)
infixr 5 :~:

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

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

-- | Infix version of <a>concat</a> that also supports destructuring.
pattern (:++:) :: forall es es' f. KnownList es => Rec f es -> Rec f es' -> Rec f (es ++ es')
infixr 5 :++:

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

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

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

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

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

-- | The element <tt>e</tt> is present in the list <tt>es</tt>.
class Elem (e :: k) (es :: [k])

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

-- | <tt>es</tt> is a subset of <tt>es'</tt>.
class KnownList es => Subset (es :: [k]) (es' :: [k])

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

-- | Modify an entry in the record. &lt;math&gt;.
modify :: forall e es f. Elem e es => f e -> Rec f es -> Rec f es

-- | Infix version of <a>modify</a>.
(/~/) :: Elem e es => f e -> Rec f es -> Rec f es
infixl 9 /~/

-- | Merge a subset into the original record, updating several entries at
--   once. &lt;math&gt;.
batch :: forall es es' f. Subset es es' => Rec f es -> Rec f es' -> Rec f es'

-- | Infix version of <a>batch</a>.
(/++/) :: Subset es es' => Rec f es -> Rec f es' -> Rec f es'
infixl 9 /++/

-- | The type of natural transformations from functor <tt>f</tt> to
--   <tt>g</tt>.
type f ~> g = forall a. f a -> g a
infixr 0 ~>

-- | Apply a natural transformation to the record. &lt;math&gt;.
natural :: (f ~> g) -> Rec f es -> Rec g es

-- | Infix version of <a>natural</a>.
(<#>) :: (f ~> g) -> Rec f es -> Rec g es
infixl 4 <#>

-- | Zip two records with a natural transformation. &lt;math&gt;.
zipWith :: (forall x. f x -> g x -> h x) -> Rec f es -> Rec g es -> Rec h es

-- | Check if a predicate is true on all elements. &lt;math&gt;.
all :: (forall x. f x -> Bool) -> Rec f es -> Bool

-- | Check if a predicate is true on at least one element. &lt;math&gt;.
any :: (forall x. f x -> Bool) -> Rec f es -> Bool

-- | Convert a record that effectively contains a fixed type into a list of
--   the fixed type. &lt;math&gt;.
degenerate :: Rec (Const a) es -> [a]

-- | Map each element to a fixed type. &lt;math&gt;.
extract :: (forall x. f x -> a) -> Rec f es -> [a]

-- | Test all invariants.
invariant :: Rec f es -> Rec f es

-- | Test the size invariant of <a>Rec</a>.
sizeInvariant :: Rec f es -> Rec f es

-- | Test whether all fields of <a>Rec</a> are really set.
allAccessible :: Rec f es -> Rec f es
instance forall k (es :: [k]). Data.Rec.Subset '[] es
instance forall k (es :: [k]) (es' :: [k]) (e :: k). (Data.Rec.Subset es es', Data.Rec.Elem e es') => Data.Rec.Subset (e : es) es'
instance forall k (e :: k). (TypeError ...) => Data.Rec.Elem e '[]
instance forall a (e :: a) (es :: [a]). Data.Rec.Elem e (e : es)
instance forall a (e :: a) (es :: [a]) (e' :: a). Data.Rec.Elem e es => Data.Rec.Elem e (e' : es)
instance Data.Rec.KnownList '[]
instance forall k (es :: [k]) (e :: k). Data.Rec.KnownList es => Data.Rec.KnownList (e : es)
instance forall k (f :: k -> Type). GHC.Classes.Eq (Data.Rec.Rec f '[])
instance forall a (f :: a -> Type) (xs :: [a]) (x :: a). (GHC.Classes.Eq (Data.Rec.Rec f xs), GHC.Classes.Eq (f x)) => GHC.Classes.Eq (Data.Rec.Rec f (x : xs))
instance forall k (f :: k -> Type) (xs :: [k]). (forall (x :: k). GHC.Classes.Eq (f x)) => GHC.Classes.Eq (Data.Rec.Rec f xs)
instance forall k (f :: k -> Type). GHC.Show.Show (Data.Rec.Rec f '[])
instance forall k (f :: k -> Type). GHC.Read.Read (Data.Rec.Rec f '[])
instance forall a (f :: a -> Type) (x :: a) (xs :: [a]). (GHC.Show.Show (f x), GHC.Show.Show (Data.Rec.Rec f xs)) => GHC.Show.Show (Data.Rec.Rec f (x : xs))
instance forall a (f :: a -> Type) (x :: a) (xs :: [a]). (GHC.Read.Read (f x), GHC.Read.Read (Data.Rec.Rec f xs)) => GHC.Read.Read (Data.Rec.Rec f (x : xs))
instance forall k (f :: k -> Type) (xs :: [k]). (forall (x :: k). GHC.Show.Show (f x)) => GHC.Show.Show (Data.Rec.Rec f xs)
instance forall k (f :: k -> Type). GHC.Base.Semigroup (Data.Rec.Rec f '[])
instance forall a (f :: a -> Type) (x :: a) (xs :: [a]). (GHC.Base.Semigroup (f x), GHC.Base.Semigroup (Data.Rec.Rec f xs)) => GHC.Base.Semigroup (Data.Rec.Rec f (x : xs))
instance forall k (f :: k -> Type) (xs :: [k]). (forall (x :: k). GHC.Base.Semigroup (f x)) => GHC.Base.Semigroup (Data.Rec.Rec f xs)
instance forall k (f :: k -> Type). GHC.Base.Monoid (Data.Rec.Rec f '[])
instance forall a (f :: a -> Type) (x :: a) (xs :: [a]). (GHC.Base.Monoid (f x), GHC.Base.Monoid (Data.Rec.Rec f xs)) => GHC.Base.Monoid (Data.Rec.Rec f (x : xs))


-- | <a>Mem</a> is a data structure that is a simulation of an array of
--   thread-local pointers. This structure supports:
--   
--   <ul>
--   <li>&lt;math&gt; creation of a new pointer;</li>
--   <li>&lt;math&gt; changing the pointer in an array cell;</li>
--   <li>&lt;math&gt; modification of the memory a pointer points to;</li>
--   <li>&lt;math&gt; read.</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 Data.Mem

-- | A simulated array of thread-local pointers. This means for each array
--   cell, you can either change the pointer or change the memory the
--   pointer points to.
--   
--   Note that like real memory, any of the operations provided is not
--   generally safe and it is your responsibility to ensure the correctness
--   of your calls.
data Mem (f :: k -> Type) (es :: [k])

-- | The representation of a pointer in a <a>Mem</a>.
data MemPtr (f :: k -> Type) (a :: k)

-- | Create a <a>Mem</a> with no pointers.
empty :: Mem f '[]

-- | Adjust the array of pointers.
adjust :: forall es' es f. (Rec (MemPtr f) es -> Rec (MemPtr f) es') -> Mem f es -> Mem f es'

-- | Allocate a new address. &lt;math&gt;.
alloca :: forall e es f. Mem f es -> (# MemPtr f e, Mem f es #)

-- | Read a pointer. &lt;math&gt;.
read :: forall e es f. Elem e es => Mem f es -> f e

-- | Write to the memory a pointer points to. &lt;math&gt;.
write :: forall e es f. MemPtr f e -> f e -> Mem f es -> Mem f es

-- | Replace a pointer with a new one. &lt;math&gt;.
replace :: forall e es f. Elem e es => MemPtr f e -> f e -> Mem f es -> Mem f es

-- | Add a new pointer to the array. &lt;math&gt;.
append :: forall e es f. MemPtr f e -> f e -> Mem f es -> Mem f (e : es)

-- | Use the memory of LHS as a newer version for the memory of RHS.
--   &lt;math&gt;.
update :: forall es es' f. Mem f es' -> Mem f es -> Mem f es
instance forall k (f :: k -> Type) (a :: k). GHC.Classes.Ord (Data.Mem.MemPtr f a)
instance forall k (f :: k -> Type) (a :: k). GHC.Classes.Eq (Data.Mem.MemPtr f a)


-- | This module contains definitions of some basic types related to
--   effects. You won't need this module directly; these functionalities
--   are reexported 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.Effect

-- | 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

-- | <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 used in an
--   <tt><a>Eff</a> es</tt> computation.
type (:>) = Elem
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 :>>

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

-- | The type of natural transformations from functor <tt>f</tt> to
--   <tt>g</tt>.
type f ~> g = forall a. f a -> g a
infixr 0 ~>


-- | This module contains the definition of the <a>Eff</a> monad, which is
--   basically an <tt><a>Env</a> es -&gt; <a>IO</a> a</tt>, as well as
--   functions for manipulating the effect environment type <a>Env</a>.
--   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 effect memironment that stores handlers of any effect present in
--   the stack <tt>es</tt>.
type Env = Mem InternalHandler

-- | The extensible effect monad. A 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. However, most
--   of the times, for flexibility, <tt>es</tt> should be a polymorphic
--   type variable, and you should use the <a>(:&gt;)</a> and
--   <a>(:&gt;&gt;)</a> operators in constraints to indicate what effects
--   are 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>
--   
--   allows you to 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>.
newtype Eff es a
Eff :: (Env es -> IO a) -> Eff es a
[unEff] :: Eff es a -> Env es -> IO a

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

-- | <tt>es</tt> is a subset of <tt>es'</tt>.
class KnownList es => Subset (es :: [k]) (es' :: [k])

-- | 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
instance Control.Monad.Fix.MonadFix (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Monad (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Applicative (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Functor (Cleff.Internal.Monad.Eff es)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Cleff.Internal.Monad.Eff es a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Cleff.Internal.Monad.Eff es a)
instance Data.Typeable.Internal.Typeable e => GHC.Show.Show (Cleff.Internal.Monad.InternalHandler e)


-- | 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 functions defintions for
--   performing the operations of <tt>T</tt> via <a>send</a>. 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.
--   
--   Because of the limitations of Template Haskell, all constructors of
--   <tt>T</tt> should be <i>polymorphic in the monad type</i>, if they are
--   to be used by <a>makeEffect</a>. For example, this is not OK:
--   
--   <pre>
--   data Limited :: <a>Effect</a> where
--     Noop :: Limited (<a>Eff</a> es) ()
--   </pre>
--   
--   because the monad type <tt><a>Eff</a> es</tt> is not a fully
--   polymorphic type variable.
--   
--   This function is also "weaker" than <tt>polysemy</tt>'s
--   <tt>makeSem</tt>, because this function cannot properly handle some
--   cases involving complex higher order effects. Those cases are rare,
--   though. See the tests 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 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

-- | 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

-- | The typeclass that indicates 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 e es esSend | e -> es esSend, es -> e esSend, esSend -> e es

-- | Get the send-site <a>Env</a>.
sendEnv :: Handling e es esSend => 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 e es esSend => 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> 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 while being able to leave it unhandled (i.e. you
--   can resend the effects in the handler).
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>.
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.
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, like a bracketing effect:
--   
--   <pre>
--   data Resource m a where
--     Bracket :: m a -&gt; (a -&gt; m ()) -&gt; (a -&gt; m b) -&gt; Resource m b
--   </pre>
--   
--   <pre>
--   Bracket alloc dealloc use -&gt;
--     <a>bracket</a>
--       (<a>toEff</a> alloc)
--       (<a>toEff</a> . dealloc)
--       (<a>toEff</a> . use)
--   </pre>
toEff :: Handling e es esSend => Eff esSend ~> Eff es

-- | Run a computation in the current effect stack, but handles the current
--   effect inside the computation differently by providing a new
--   <a>Handler</a>. 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 :: Handling e es esSend => 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 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 e es esSend => ((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 for 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 in application code, as it is
--   too liberal and allows arbitrary IO. Ideally, this is only used in
--   interpreting more fine-grained effects.
--   
--   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>. It is
--   similar to Polysemy's <tt>Final</tt> effect which also cannot be
--   interpreted. 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.e. 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 e es esSend) => 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 useful for dealing with
--   higher-order effects that involves <a>IO</a>.
withToIO :: (Handling e es esSend, 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
--   useful for dealing with effect operations with the monad type in the
--   negative position within <a>IOE</a>, like <a>mask</a>ing.
fromIO :: (Handling e es esSend, IOE :> es) => IO ~> Eff esSend
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.IO.Class.MonadIO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.IO.Unlift.MonadUnliftIO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Catch.MonadThrow (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Catch.MonadCatch (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Catch.MonadMask (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Base.MonadBase GHC.Types.IO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO (Cleff.Internal.Monad.Eff es)
instance (Cleff.Internal.Base.IOE Cleff.Internal.Effect.:> es) => Control.Monad.Primitive.PrimMonad (Cleff.Internal.Monad.Eff es)


-- | 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
--   obtaining 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>
--   
--   So, this library allows 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 be
--   certain about what effects are involved in each function.</li>
--   <li><b>Effect decoupling:</b> You can decouple the implementation of
--   the effects from your application and swap them easily.</li>
--   </ul>
module Cleff

-- | The extensible effect monad. A 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. However, most
--   of the times, for flexibility, <tt>es</tt> should be a polymorphic
--   type variable, and you should use the <a>(:&gt;)</a> and
--   <a>(:&gt;&gt;)</a> operators in constraints to indicate what effects
--   are 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>
--   
--   allows you to 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>.
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 used in an
--   <tt><a>Eff</a> es</tt> computation.
type (:>) = Elem
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 for 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 in application code, as it is
--   too liberal and allows arbitrary IO. Ideally, this is only used in
--   interpreting more fine-grained effects.
--   
--   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>. It is
--   similar to Polysemy's <tt>Final</tt> effect which also cannot be
--   interpreted. 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

-- | For a datatype <tt>T</tt> representing an effect,
--   <tt><a>makeEffect</a> T</tt> generates functions defintions for
--   performing the operations of <tt>T</tt> via <a>send</a>. 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.
--   
--   Because of the limitations of Template Haskell, all constructors of
--   <tt>T</tt> should be <i>polymorphic in the monad type</i>, if they are
--   to be used by <a>makeEffect</a>. For example, this is not OK:
--   
--   <pre>
--   data Limited :: <a>Effect</a> where
--     Noop :: Limited (<a>Eff</a> es) ()
--   </pre>
--   
--   because the monad type <tt><a>Eff</a> es</tt> is not a fully
--   polymorphic type variable.
--   
--   This function is also "weaker" than <tt>polysemy</tt>'s
--   <tt>makeSem</tt>, because this function cannot properly handle some
--   cases involving complex higher order effects. Those cases are rare,
--   though. See the tests 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

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

-- | <tt>es</tt> is a subset of <tt>es'</tt>.
class KnownList es => Subset (es :: [k]) (es' :: [k])

-- | 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 e es esSend => 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> 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 while being able to leave it unhandled (i.e. you
--   can resend the effects in the handler).
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 e es esSend) => 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>.
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.
translate :: forall e' e es. Translator e e' -> Eff (e : es) ~> Eff (e' : es)

-- | The typeclass that indicates 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 e es esSend | e -> es esSend, es -> e esSend, esSend -> e es

-- | Run a computation in the current effect stack. This is useful for
--   interpreting higher-order effects, like a bracketing effect:
--   
--   <pre>
--   data Resource m a where
--     Bracket :: m a -&gt; (a -&gt; m ()) -&gt; (a -&gt; m b) -&gt; Resource m b
--   </pre>
--   
--   <pre>
--   Bracket alloc dealloc use -&gt;
--     <a>bracket</a>
--       (<a>toEff</a> alloc)
--       (<a>toEff</a> . dealloc)
--       (<a>toEff</a> . use)
--   </pre>
toEff :: Handling e es esSend => Eff esSend ~> Eff es

-- | Run a computation in the current effect stack, but handles the current
--   effect inside the computation differently by providing a new
--   <a>Handler</a>. 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 :: Handling e es esSend => 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 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 e es esSend => ((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 useful for dealing with
--   higher-order effects that involves <a>IO</a>.
withToIO :: (Handling e es esSend, 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
--   useful for dealing with effect operations with the monad type in the
--   negative position within <a>IOE</a>, like <a>mask</a>ing.
fromIO :: (Handling e es esSend, IOE :> es) => IO ~> Eff esSend

-- | The type of natural transformations from functor <tt>f</tt> to
--   <tt>g</tt>.
type f ~> g = forall a. f a -> g a
infixr 0 ~>

-- | 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.Writer

-- | An effect capable of accumulating outputs. This roughly corresponds to
--   the <tt>MonadWriter</tt> typeclass and <tt>WriterT</tt> monad
--   transformer in the <tt>mtl</tt> approach.
--   
--   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)
tell :: Writer w_ajRn :> es_ajWf => w_ajRn -> Eff es_ajWf ()
listen :: Writer w_ajRr :> es_ajWd => Eff es_ajWd a_XjRr -> Eff es_ajWd (a_XjRr, w_ajRr)

-- | 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.
--   
--   <b>Caveat</b>: 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)

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>
--   approach.
data State s :: Effect
[Get] :: State s m s
[Put] :: s -> State s m ()
[State] :: (s -> (a, s)) -> State s m a
get :: State s_akp0 :> es_akrc => Eff es_akrc s_akp0
put :: State s_akp2 :> es_akra => s_akp2 -> Eff es_akra ()
state :: State s_akp4 :> es_akr8 => (s_akp4 -> (a_akp5, s_akp4)) -> Eff es_akr8 a_akp5

-- | 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.
--   
--   <b>Caveat</b>: 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 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.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>
--   approach.
data Reader r :: Effect
[Ask] :: Reader r m r
[Local] :: (r -> r) -> m a -> Reader r m a
ask :: Reader r_al10 :> es_al2D => Eff es_al2D r_al10
local :: Reader r_al12 :> es_al2A => (r_al12 -> r_al12) -> Eff es_al2A a_al14 -> Eff es_al2A a_al14

-- | Apply a function on 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.Output

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

-- | Run an <a>Output</a> effect by accumulating a list.
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

module Cleff.Trace

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

-- | 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)

module Cleff.Mask

-- | An effect capable of <a>mask</a>ing and specifically,
--   <a>bracket</a>ing operations, <i>i.e.</i> allowing cleanup after
--   operations that my raise exceptions.
data Mask :: Effect
[Mask] :: ((m ~> m) -> m a) -> Mask m a
[UninterruptibleMask] :: ((m ~> m) -> m a) -> Mask m a
[Bracket] :: m a -> (a -> m c) -> (a -> m b) -> Mask m b
[BracketOnError] :: m a -> (a -> m c) -> (a -> m b) -> Mask m b
mask :: Mask :> es_alWM => ((~>) (Eff es_alWM) (Eff es_alWM) -> Eff es_alWM a_alTC) -> Eff es_alWM a_alTC
uninterruptibleMask :: Mask :> es_alWK => ((~>) (Eff es_alWK) (Eff es_alWK) -> Eff es_alWK a_alTE) -> Eff es_alWK a_alTE
bracket :: Mask :> es_alWG => Eff es_alWG a_XlTH -> (a_XlTH -> Eff es_alWG c_XlTJ) -> (a_XlTH -> Eff es_alWG b_alTI) -> Eff es_alWG b_alTI
bracketOnError :: Mask :> es_alWC => Eff es_alWC a_XlTL -> (a_XlTL -> Eff es_alWC c_XlTN) -> (a_XlTL -> Eff es_alWC b_alTM) -> Eff es_alWC b_alTM

-- | 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

-- | 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

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

-- | Attach an action that runs if the main computation throws an
--   exception.
onError :: Mask :> es => Eff es a -> Eff es b -> 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.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
input :: Input i_amwe :> es_amwX => Eff es_amwX i_amwe

-- | 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> effect by performing a computation for each input
--   request.
runInputEff :: 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
fresh :: Fresh u_amKA :> es_amLj => Eff es_amLj u_amKA

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

-- | Interpret a <tt><a>Fresh</a> <a>Unique</a></tt> effect in terms of IO
--   actions.
runFreshUnique :: IOE :> es => Eff (Fresh Unique : es) ~> Eff es

module Cleff.Error

-- | An effect capable of breaking out of current control flow by raising
--   an exceptional value <tt>e</tt>. 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
throwError :: Error e_amUL :> es_amWz => e_amUL -> Eff es_amWz a_amUN
catchError :: Error e_amUQ :> es_amWw => Eff es_amWw a_amUP -> (e_amUQ -> Eff es_amWw a_amUP) -> Eff es_amWw a_amUP

-- | 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.
--   
--   <b>Caveat</b>: <a>runError</a> is implemented with <a>Exception</a>s
--   therefore inherits some of its unexpected behavoirs. 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.e. 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.Effect.:> es) => Control.Monad.Fail.MonadFail (Cleff.Internal.Monad.Eff es)