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


-- | Implementation of a friendly effect system for Haskell.
--   
--   An implementation of an effect system for Haskell (a fork of
--   <a>freer-effects</a>), which is based on the work of Oleg Kiselyov et
--   al.:
--   
--   <ul>
--   <li><a>Freer Monads, More Extensible Effects</a></li>
--   <li><a>Reflection without Remorse</a></li>
--   <li><a>Extensible Effects</a></li>
--   </ul>
--   
--   The key features are:
--   
--   <ul>
--   <li>An efficient effect system for Haskell - as a library!</li>
--   <li>Reimplementations of several common Haskell monad transformers as
--   effects.</li>
--   <li>Core components for defining your own Effects.</li>
--   </ul>
@package freer-simple
@version 1.2.1.0


-- | <ul>
--   <li>Constant-time append/(<a>&gt;&lt;</a>) and
--   snoc/(<a>|&gt;</a>)</li>
--   <li>Average constant-time <tt>viewL</tt> (left-edge
--   deconstruction).</li>
--   </ul>
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/FTCQueue1.hs</a> as a
--   starting point.
--   
--   A minimal version of FTCQueue from "Reflection w/o Remorse":
--   
--   <ul>
--   <li>Research: <a>http://okmij.org/ftp/Haskell/Reflection.html</a></li>
--   <li><a>type-aligned</a> (FTCQueue)</li>
--   </ul>
module Data.FTCQueue

-- | Non-empty tree. Deconstruction operations make it more and more
--   left-leaning
data FTCQueue m a b

-- | Build a leaf from a single operation. [O(1)]
tsingleton :: (a -> m b) -> FTCQueue m a b

-- | Append an operation to the right of the tree. [O(1)]
(|>) :: FTCQueue m a x -> (x -> m b) -> FTCQueue m a b

-- | An alias for '(|&gt;)'
snoc :: FTCQueue m a x -> (x -> m b) -> FTCQueue m a b

-- | Append two trees of operations. [O(1)]
(><) :: FTCQueue m a x -> FTCQueue m x b -> FTCQueue m a b

-- | An alias for '(&gt;&lt;)'
append :: FTCQueue m a x -> FTCQueue m x b -> FTCQueue m a b

-- | Left view deconstruction data structure.
data ViewL m a b
[TOne] :: (a -> m b) -> ViewL m a b
[:|] :: (a -> m x) -> FTCQueue m x b -> ViewL m a b

-- | Left view deconstruction. [average O(1)]
tviewl :: FTCQueue m a b -> ViewL m a b


-- | These are internal definitions and should be used with caution. There
--   are no guarantees that the API of this module will be preserved
--   between minor versions of this package.
--   
--   Open unions (type-indexed co-products, i.e. type-indexed sums) for
--   extensible effects All operations are constant-time.
--   
--   Based on <a>OpenUnion51.hs</a>.
--   
--   Type-list <tt>r :: [* -&gt; *]</tt> of open union components is a
--   small Universe. Therefore, we can use a <tt>Typeable</tt>-like
--   evidence in that universe. In our case a simple index of an element in
--   the type-list is sufficient substitution for <tt>Typeable</tt>.
module Data.OpenUnion.Internal

-- | Open union is a strong sum (existential with an evidence).
data Union (r :: [* -> *]) a
[Union] :: {-# UNPACK #-} !Word -> t a -> Union r a

-- | Takes a request of type <tt>t :: * -&gt; *</tt>, and injects it into
--   the <a>Union</a>.
--   
--   Summand is assigning a specified <a>Word</a> value, which is a
--   position in the type-list <tt>(t ': r) :: * -&gt; *</tt>.
--   
--   <b>This function is unsafe.</b>
--   
--   <i>O(1)</i>
unsafeInj :: Word -> t a -> Union r a

-- | Project a value of type <tt><a>Union</a> (t ': r) :: * -&gt; *</tt>
--   into a possible summand of the type <tt>t :: * -&gt; *</tt>.
--   <a>Nothing</a> means that <tt>t :: * -&gt; *</tt> is not the value
--   stored in the <tt><a>Union</a> (t ': r) :: * -&gt; *</tt>.
--   
--   It is assumed that summand is stored in the <a>Union</a> when the
--   <a>Word</a> value is the same value as is stored in the <a>Union</a>.
--   
--   <b>This function is unsafe.</b>
--   
--   <i>O(1)</i>
unsafePrj :: Word -> Union r a -> Maybe (t a)

-- | Represents position of element <tt>t :: * -&gt; *</tt> in a type list
--   <tt>r :: [* -&gt; *]</tt>.
newtype P t r
P :: Word -> P t r
[unP] :: P t r -> Word

-- | Find an index of an element <tt>t :: * -&gt; *</tt> in a type list
--   <tt>r :: [* -&gt; *]</tt>. The element must exist. The <tt>w :: [*
--   -&gt; *]</tt> type represents the entire list, prior to recursion, and
--   it is used to produce better type errors.
--   
--   This is essentially a compile-time computation without run-time
--   overhead.
class FindElem (t :: * -> *) (r :: [* -> *])

-- | Position of the element <tt>t :: * -&gt; *</tt> in a type list <tt>r
--   :: [* -&gt; *]</tt>.
--   
--   Position is computed during compilation, i.e. there is no run-time
--   overhead.
--   
--   <i>O(1)</i>
elemNo :: FindElem t r => P t r

-- | Instance resolution for this class fails with a custom type error if
--   <tt>t :: * -&gt; *</tt> is not in the list <tt>r :: [* -&gt; *]</tt>.
class IfNotFound (t :: * -> *) (r :: [* -> *]) (w :: [* -> *])

-- | A constraint that requires that a particular effect, <tt>eff</tt>, is
--   a member of the type-level list <tt>effs</tt>. This is used to
--   parameterize an <a>Eff</a> computation over an arbitrary list of
--   effects, so long as <tt>eff</tt> is <i>somewhere</i> in the list.
--   
--   For example, a computation that only needs access to a cell of mutable
--   state containing an <a>Integer</a> would likely use the following
--   type:
--   
--   <pre>
--   <a>Member</a> (<a>State</a> <a>Integer</a>) effs =&gt; <a>Eff</a> effs ()
--   </pre>
class FindElem eff effs => Member (eff :: * -> *) effs

-- | Takes a request of type <tt>t :: * -&gt; *</tt>, and injects it into
--   the <a>Union</a>.
--   
--   <i>O(1)</i>
inj :: Member eff effs => eff a -> Union effs a

-- | Project a value of type <tt><a>Union</a> (t ': r) :: * -&gt; *</tt>
--   into a possible summand of the type <tt>t :: * -&gt; *</tt>.
--   <a>Nothing</a> means that <tt>t :: * -&gt; *</tt> is not the value
--   stored in the <tt><a>Union</a> (t ': r) :: * -&gt; *</tt>.
--   
--   <i>O(1)</i>
prj :: Member eff effs => Union effs a -> Maybe (eff a)

-- | Orthogonal decomposition of a <tt><a>Union</a> (t ': r) :: * -&gt;
--   *</tt>. <a>Right</a> value is returned if the <tt><a>Union</a> (t ':
--   r) :: * -&gt; *</tt> contains <tt>t :: * -&gt; *</tt>, and <a>Left</a>
--   when it doesn't. Notice that <a>Left</a> value contains <tt>Union r ::
--   * -&gt; *</tt>, i.e. it can not contain <tt>t :: * -&gt; *</tt>.
--   
--   <i>O(1)</i>
decomp :: Union (t : r) a -> Either (Union r a) (t a)

-- | Specialized version of <a>decomp</a> for efficiency.
--   
--   <i>O(1)</i>
--   
--   TODO: Check that it actually adds on efficiency.
decomp0 :: Union '[t] a -> Either (Union '[] a) (t a)

-- | Specialised version of 'prj'\/'decomp' that works on an
--   <tt><a>Union</a> '[t] :: * -&gt; *</tt> which contains only one
--   specific summand. Hence the absence of <a>Maybe</a>, and
--   <a>Either</a>.
--   
--   <i>O(1)</i>
extract :: Union '[t] a -> t a

-- | Inject whole <tt><a>Union</a> r</tt> into a weaker <tt><a>Union</a>
--   (any ': r)</tt> that has one more summand.
--   
--   <i>O(1)</i>
weaken :: Union r a -> Union (any : r) a
type family xs :++: ys
infixr 5 :++:
class Weakens q
weakens :: Weakens q => Union r a -> Union (q :++: r) a
instance Data.OpenUnion.Internal.Weakens '[]
instance Data.OpenUnion.Internal.Weakens xs => Data.OpenUnion.Internal.Weakens (x : xs)
instance (TypeError ...) => Data.OpenUnion.Internal.IfNotFound t '[] w
instance (Data.OpenUnion.Internal.FindElem t r, Data.OpenUnion.Internal.IfNotFound t r r) => Data.OpenUnion.Internal.Member t r
instance Data.OpenUnion.Internal.IfNotFound t (t : r) w
instance Data.OpenUnion.Internal.IfNotFound t r w => Data.OpenUnion.Internal.IfNotFound t (t' : r) w
instance Data.OpenUnion.Internal.IfNotFound t r w
instance Data.OpenUnion.Internal.FindElem t (t : r)
instance Data.OpenUnion.Internal.FindElem t r => Data.OpenUnion.Internal.FindElem t (t' : r)


-- | Open unions (type-indexed co-products, i.e. type-indexed sums) for
--   extensible effects All operations are constant-time.
module Data.OpenUnion

-- | Open union is a strong sum (existential with an evidence).
data Union (r :: [* -> *]) a
class Weakens q
weakens :: Weakens q => Union r a -> Union (q :++: r) a
type family xs :++: ys
infixr 5 :++:

-- | Orthogonal decomposition of a <tt><a>Union</a> (t ': r) :: * -&gt;
--   *</tt>. <a>Right</a> value is returned if the <tt><a>Union</a> (t ':
--   r) :: * -&gt; *</tt> contains <tt>t :: * -&gt; *</tt>, and <a>Left</a>
--   when it doesn't. Notice that <a>Left</a> value contains <tt>Union r ::
--   * -&gt; *</tt>, i.e. it can not contain <tt>t :: * -&gt; *</tt>.
--   
--   <i>O(1)</i>
decomp :: Union (t : r) a -> Either (Union r a) (t a)

-- | Inject whole <tt><a>Union</a> r</tt> into a weaker <tt><a>Union</a>
--   (any ': r)</tt> that has one more summand.
--   
--   <i>O(1)</i>
weaken :: Union r a -> Union (any : r) a

-- | Specialised version of 'prj'\/'decomp' that works on an
--   <tt><a>Union</a> '[t] :: * -&gt; *</tt> which contains only one
--   specific summand. Hence the absence of <a>Maybe</a>, and
--   <a>Either</a>.
--   
--   <i>O(1)</i>
extract :: Union '[t] a -> t a

-- | A constraint that requires that a particular effect, <tt>eff</tt>, is
--   a member of the type-level list <tt>effs</tt>. This is used to
--   parameterize an <a>Eff</a> computation over an arbitrary list of
--   effects, so long as <tt>eff</tt> is <i>somewhere</i> in the list.
--   
--   For example, a computation that only needs access to a cell of mutable
--   state containing an <a>Integer</a> would likely use the following
--   type:
--   
--   <pre>
--   <a>Member</a> (<a>State</a> <a>Integer</a>) effs =&gt; <a>Eff</a> effs ()
--   </pre>
class FindElem eff effs => Member (eff :: * -> *) effs

-- | Takes a request of type <tt>t :: * -&gt; *</tt>, and injects it into
--   the <a>Union</a>.
--   
--   <i>O(1)</i>
inj :: Member eff effs => eff a -> Union effs a

-- | Project a value of type <tt><a>Union</a> (t ': r) :: * -&gt; *</tt>
--   into a possible summand of the type <tt>t :: * -&gt; *</tt>.
--   <a>Nothing</a> means that <tt>t :: * -&gt; *</tt> is not the value
--   stored in the <tt><a>Union</a> (t ': r) :: * -&gt; *</tt>.
--   
--   <i>O(1)</i>
prj :: Member eff effs => Union effs a -> Maybe (eff a)

-- | A shorthand constraint that represents a combination of multiple
--   <a>Member</a> constraints. That is, the following <a>Members</a>
--   constraint:
--   
--   <pre>
--   <a>Members</a> '[Foo, Bar, Baz] effs
--   </pre>
--   
--   …is equivalent to the following set of <a>Member</a> constraints:
--   
--   <pre>
--   (<a>Member</a> Foo effs, <a>Member</a> Bar effs, <a>Member</a> baz effs)
--   </pre>
--   
--   Note that, since each effect is translated into a separate
--   <a>Member</a> constraint, the order of the effects does <i>not</i>
--   matter.
type family Members effs effs' :: Constraint

-- | Like <a>Member</a>, <tt><a>LastMember</a> eff effs</tt> is a
--   constraint that requires that <tt>eff</tt> is in the type-level list
--   <tt>effs</tt>. However, <i>unlike</i> <a>Member</a>, <a>LastMember</a>
--   requires <tt>m</tt> be the <b>final</b> effect in <tt>effs</tt>.
--   
--   Generally, this is not especially useful, since it is preferable for
--   computations to be agnostic to the order of effects, but it is quite
--   useful in combination with <a>sendM</a> or <a>liftBase</a> to embed
--   ordinary monadic effects within an <a>Eff</a> computation.
class Member m effs => LastMember m effs | effs -> m
instance Data.OpenUnion.LastMember m effs => Data.OpenUnion.LastMember m (eff : effs)
instance Data.OpenUnion.LastMember m '[m]


-- | Internal machinery for this effects library. This includes:
--   
--   <ul>
--   <li><a>Eff</a> data type, for expressing effects.</li>
--   <li><a>NonDet</a> data type, for nondeterministic effects.</li>
--   <li>Functions for facilitating the construction of effects and their
--   handlers.</li>
--   </ul>
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Internal

-- | The <a>Eff</a> monad provides the implementation of a computation that
--   performs an arbitrary set of algebraic effects. In <tt><a>Eff</a> effs
--   a</tt>, <tt>effs</tt> is a type-level list that contains all the
--   effects that the computation may perform. For example, a computation
--   that produces an <a>Integer</a> by consuming a <a>String</a> from the
--   global environment and acting upon a single mutable cell containing a
--   <a>Bool</a> would have the following type:
--   
--   <pre>
--   <a>Eff</a> '[<a>Reader</a> <a>String</a>, <a>State</a> <a>Bool</a>] <a>Integer</a>
--   </pre>
--   
--   Normally, a concrete list of effects is not used to parameterize
--   <a>Eff</a>. Instead, the <a>Member</a> or <a>Members</a> constraints
--   are used to express constraints on the list of effects without
--   coupling a computation to a concrete list of effects. For example, the
--   above example would more commonly be expressed with the following
--   type:
--   
--   <pre>
--   <a>Members</a> '[<a>Reader</a> <a>String</a>, <a>State</a> <a>Bool</a>] effs =&gt; <a>Eff</a> effs <a>Integer</a>
--   </pre>
--   
--   This abstraction allows the computation to be used in functions that
--   may perform other effects, and it also allows the effects to be
--   handled in any order.
data Eff effs a

-- | Pure value (<tt><a>return</a> = <a>pure</a> = <a>Val</a></tt>).
Val :: a -> Eff effs a

-- | Sending a request of type <tt>Union effs</tt> with the continuation
--   <tt><a>Arrs</a> r b a</tt>.
E :: Union effs b -> Arrs effs b a -> Eff effs a

-- | Effectful arrow type: a function from <tt>a :: *</tt> to <tt>b ::
--   *</tt> that also does effects denoted by <tt>effs :: [* -&gt; *]</tt>.
type Arr effs a b = a -> Eff effs b

-- | An effectful function from <tt>a :: *</tt> to <tt>b :: *</tt> that is
--   a composition of several effectful functions. The paremeter <tt>eff ::
--   [* -&gt; *]</tt> describes the overall effect. The composition members
--   are accumulated in a type-aligned queue.
type Arrs effs a b = FTCQueue (Eff effs) a b

-- | “Sends” an effect, which should be a value defined as part of an
--   effect algebra (see the module documentation for
--   <a>Control.Monad.Freer</a>), to an effectful computation. This is used
--   to connect the definition of an effect to the <a>Eff</a> monad so that
--   it can be used and handled.
send :: Member eff effs => eff a -> Eff effs a

-- | Identical to <a>send</a>, but specialized to the final effect in
--   <tt>effs</tt> to assist type inference. This is useful for running
--   actions in a monad transformer stack used in conjunction with
--   <a>runM</a>.
sendM :: (Monad m, LastMember m effs) => m a -> Eff effs a

-- | Embeds a less-constrained <a>Eff</a> into a more-constrained one.
--   Analogous to MTL's <tt>lift</tt>.
raise :: Eff effs a -> Eff (e : effs) a

-- | Runs a pure <a>Eff</a> computation, since an <a>Eff</a> computation
--   that performs no effects (i.e. has no effects in its type-level list)
--   is guaranteed to be pure. This is usually used as the final step of
--   running an effectful computation, after all other effects have been
--   discharged using effect handlers.
--   
--   Typically, this function is composed as follows:
--   
--   <pre>
--   someProgram
--     <a>&amp;</a> runEff1 eff1Arg
--     <a>&amp;</a> runEff2 eff2Arg1 eff2Arg2
--     <a>&amp;</a> <a>run</a>
--   </pre>
run :: Eff '[] a -> a

-- | Like <a>run</a>, <a>runM</a> runs an <a>Eff</a> computation and
--   extracts the result. <i>Unlike</i> <a>run</a>, <a>runM</a> allows a
--   single effect to remain within the type-level list, which must be a
--   monad. The value returned is a computation in that monad, which is
--   useful in conjunction with <a>sendM</a> or <a>liftBase</a> for
--   plugging in traditional transformer stacks.
runM :: Monad m => Eff '[m] a -> m a

-- | Given a request, either handle it or relay it.
handleRelay :: (a -> Eff effs b) -> (forall v. eff v -> Arr effs v b -> Eff effs b) -> Eff (eff : effs) a -> Eff effs b

-- | Parameterized <a>handleRelay</a>. Allows sending along some state of
--   type <tt>s :: *</tt> to be handled for the target effect, or relayed
--   to a handler that can- handle the target effect.
handleRelayS :: s -> (s -> a -> Eff effs b) -> (forall v. s -> eff v -> (s -> Arr effs v b) -> Eff effs b) -> Eff (eff : effs) a -> Eff effs b

-- | Intercept the request and possibly reply to it, but leave it
--   unhandled.
interpose :: Member eff effs => (a -> Eff effs b) -> (forall v. eff v -> Arr effs v b -> Eff effs b) -> Eff effs a -> Eff effs b

-- | Like <a>interpose</a>, but with support for an explicit state to help
--   implement the interpreter.
interposeS :: Member eff effs => s -> (s -> a -> Eff effs b) -> (forall v. s -> eff v -> (s -> Arr effs v b) -> Eff effs b) -> Eff effs a -> Eff effs b

-- | Interpret an effect by transforming it into another effect on top of
--   the stack. The primary use case of this function is allow interpreters
--   to be defined in terms of other ones without leaking intermediary
--   implementation details through the type signature.
replaceRelay :: (a -> Eff (v : effs) w) -> (forall x. t x -> Arr (v : effs) x w -> Eff (v : effs) w) -> Eff (t : effs) a -> Eff (v : effs) w

-- | Like <a>replaceRelay</a>, but with support for an explicit state to
--   help implement the interpreter.
replaceRelayS :: s -> (s -> a -> Eff (v : effs) w) -> (forall x. s -> t x -> (s -> Arr (v : effs) x w) -> Eff (v : effs) w) -> Eff (t : effs) a -> Eff (v : effs) w
replaceRelayN :: forall gs t a effs w. Weakens gs => (a -> Eff (gs :++: effs) w) -> (forall x. t x -> Arr (gs :++: effs) x w -> Eff (gs :++: effs) w) -> Eff (t : effs) a -> Eff (gs :++: effs) w

-- | Function application in the context of an array of effects,
--   <tt><a>Arrs</a> effs b w</tt>.
qApp :: Arrs effs b w -> b -> Eff effs w

-- | Composition of effectful arrows (<a>Arrs</a>). Allows for the caller
--   to change the effect environment, as well.
qComp :: Arrs effs a b -> (Eff effs b -> Eff effs' c) -> Arr effs' a c

-- | A data type for representing nondeterminstic choice.
data NonDet a
[MZero] :: NonDet a
[MPlus] :: NonDet Bool
instance Data.OpenUnion.Internal.Member Control.Monad.Freer.Internal.NonDet effs => GHC.Base.Alternative (Control.Monad.Freer.Internal.Eff effs)
instance Data.OpenUnion.Internal.Member Control.Monad.Freer.Internal.NonDet effs => GHC.Base.MonadPlus (Control.Monad.Freer.Internal.Eff effs)
instance GHC.Base.Functor (Control.Monad.Freer.Internal.Eff effs)
instance GHC.Base.Applicative (Control.Monad.Freer.Internal.Eff effs)
instance GHC.Base.Monad (Control.Monad.Freer.Internal.Eff effs)
instance (Control.Monad.Base.MonadBase b m, Data.OpenUnion.LastMember m effs) => Control.Monad.Base.MonadBase b (Control.Monad.Freer.Internal.Eff effs)
instance (Control.Monad.IO.Class.MonadIO m, Data.OpenUnion.LastMember m effs) => Control.Monad.IO.Class.MonadIO (Control.Monad.Freer.Internal.Eff effs)


-- | <a>Writer</a> effects, for writing/appending values (line count, list
--   of messages, etc.) to an output. Current value of <a>Writer</a> effect
--   output is not accessible to the computation.
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Writer

-- | Writer effects - send outputs to an effect environment.
data Writer w r
[Tell] :: w -> Writer w ()

-- | Send a change to the attached environment.
tell :: forall w effs. Member (Writer w) effs => w -> Eff effs ()

-- | Simple handler for <a>Writer</a> effects.
runWriter :: forall w effs a. Monoid w => Eff (Writer w : effs) a -> Eff effs (a, w)


-- | Composable handler for <a>Trace</a> effects. Trace allows one to debug
--   the operation of sequences of effects by outputing to the console.
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Trace

-- | A Trace effect; takes a <a>String</a> and performs output.
data Trace a
[Trace] :: String -> Trace ()

-- | Printing a string in a trace.
trace :: Member Trace effs => String -> Eff effs ()

-- | An <a>IO</a> handler for <a>Trace</a> effects.
runTrace :: Eff '[Trace] a -> IO a


-- | Composable handler for <a>NonDet</a> effects.
module Control.Monad.Freer.NonDet

-- | A data type for representing nondeterminstic choice.
data NonDet a
[MZero] :: NonDet a
[MPlus] :: NonDet Bool

-- | A handler for nondeterminstic effects.
makeChoiceA :: Alternative f => Eff (NonDet : effs) a -> Eff effs (f a)
msplit :: Member NonDet effs => Eff effs a -> Eff effs (Maybe (a, Eff effs a))


-- | Composable handler for <a>Fresh</a> effects. This is likely to be of
--   use when implementing De Bruijn naming/scopes.
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Fresh

-- | Fresh effect model.
data Fresh r
[Fresh] :: Fresh Int

-- | Request a fresh effect.
fresh :: Member Fresh effs => Eff effs Int

-- | Handler for <a>Fresh</a> effects, with an <a>Int</a> for a starting
--   value. The return value includes the next fresh value.
runFresh :: Int -> Eff (Fresh : effs) a -> Eff effs (a, Int)

-- | Handler for <a>Fresh</a> effects, with an <a>Int</a> for a starting
--   value. Discards the next fresh value.
evalFresh :: Int -> Eff (Fresh : effs) a -> Eff effs a


-- | An effect to compose functions with the ability to yield.
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Coroutine

-- | A type representing a yielding of control.
--   
--   Type variables have following meaning:
--   
--   <ul>
--   <li><i><tt>a</tt></i> The current type.</li>
--   <li><i><tt>b</tt></i> The input to the continuation function.</li>
--   <li><i><tt>c</tt></i> The output of the continuation.</li>
--   </ul>
data Yield a b c
Yield :: a -> (b -> c) -> Yield a b c

-- | Lifts a value and a function into the Coroutine effect.
yield :: Member (Yield a b) effs => a -> (b -> c) -> Eff effs c

-- | Represents status of a coroutine.
data Status effs a b r

-- | Coroutine is done with a result value of type <tt>r</tt>.
Done :: r -> Status effs a b r

-- | Reporting a value of the type <tt>a</tt>, and resuming with the value
--   of type <tt>b</tt>, possibly ending with a value of type <tt>x</tt>.
Continue :: a -> (b -> Eff effs (Status effs a b r)) -> Status effs a b r

-- | Launch a coroutine and report its status.
runC :: Eff (Yield a b : effs) r -> Eff effs (Status effs a b r)

-- | Launch a coroutine and report its status, without handling (removing)
--   <a>Yield</a> from the typelist. This is useful for reducing nested
--   coroutines.
interposeC :: Member (Yield a b) effs => Eff effs r -> Eff effs (Status effs a b r)

-- | Reply to a coroutine effect by returning the Continue constructor.
replyC :: Yield a b c -> (c -> Eff effs (Status effs a b r)) -> Eff effs (Status effs a b r)
instance GHC.Base.Functor (Control.Monad.Freer.Coroutine.Yield a b)


-- | This library is an implementation of an <i>extensible effect
--   system</i> for Haskell, a general-purpose way of tracking effects at
--   the type level and handling them in different ways. The concept of an
--   “effect” is very general: it encompasses the things most people
--   consider side-effects, like generating random values, interacting with
--   the file system, and mutating state, but it also includes things like
--   access to an immutable global environment and exception handling.
--   
--   Traditional Haskell tracks and composes effects using <i>monad
--   transformers</i>, which involves modeling each effects using what is
--   conceptually a separate monad. In contrast, <tt>freer-simple</tt>
--   provides exactly <b>one</b> monad, <a>Eff</a>, parameterized by a
--   type-level list of effects. For example, a computation that produces
--   an <a>Integer</a> by consuming a <a>String</a> from the global
--   environment and acting upon a single mutable cell containing a
--   <a>Bool</a> would have the following type:
--   
--   <pre>
--   <a>Eff</a> '[<a>Reader</a> <a>String</a>, <a>State</a> <a>Bool</a>] <a>Integer</a>
--   </pre>
--   
--   For comparison, this is the equivalent stack of monad transformers:
--   
--   <pre>
--   ReaderT <a>String</a> (State <a>Bool</a>) <a>Integer</a>
--   </pre>
--   
--   However, this is slightly misleading: the example with <a>Eff</a> is
--   actually <i>more general</i> than the corresponding example using
--   transformers because the implementations of effects are not
--   <i>concrete</i>. While <tt>StateT</tt> specifies a <i>specific</i>
--   implementation of a pseudo-mutable cell, <a>State</a> is merely an
--   interface with a set of available operations. Using <a>runState</a>
--   will “run” the <a>State</a> effect much the same way that
--   <tt>StateT</tt> does, but a hypothetical handler function
--   <tt>runStateTVar</tt> could implement the state in terms of a STM
--   <a>TVar</a>.
--   
--   The <tt>freer-simple</tt> effect library is divided into three parts:
--   
--   <ol>
--   <li>First, <tt>freer-simple</tt> provides the <a>Eff</a> monad, an
--   implementation of extensible effects that allows effects to be tracked
--   at the type level and interleaved at runtime.</li>
--   <li>Second, it provides a built-in library of common effects, such as
--   <a>Reader</a>, <a>Writer</a>, <a>State</a>, and <a>Error</a>. These
--   effects can be used with <a>Eff</a> out of the box with an interface
--   that is similar to the equivalent monad transformers.</li>
--   <li>Third, it provides a set of combinators for implementing your
--   <i>own</i> effects, which can either be implemented entirely
--   independently, in terms of other existing effects, or even in terms of
--   existing monads, making it possible to use <tt>freer-simple</tt> with
--   existing monad transformer stacks.</li>
--   </ol>
--   
--   One of the core ideas of <tt>freer-simple</tt> is that <i>most</i>
--   effects that occur in practical applications are really different
--   incarnations of a small set of fundamental effect types. Therefore,
--   while it’s possible to write new effect handlers entirely from
--   scratch, it’s more common that you will wish to define new effects in
--   terms of other effects. <tt>freer-simple</tt> makes this possible by
--   providing the <a>reinterpret</a> function, which allows
--   <i>translating</i> an effect into another one.
--   
--   For example, imagine an effect that represents interactions with a
--   file system:
--   
--   <pre>
--   data FileSystem r where
--     ReadFile :: <a>FilePath</a> -&gt; FileSystem <a>String</a>
--     WriteFile :: <a>FilePath</a> -&gt; <a>String</a> -&gt; FileSystem ()
--   </pre>
--   
--   An implementation that uses the real file system would, of course, be
--   implemented in terms of <a>IO</a>. An alternate implementation,
--   however, might be implemented in-memory in terms of <a>State</a>. With
--   <a>reinterpret</a>, this implementation is trivial:
--   
--   <pre>
--   runInMemoryFileSystem :: [(<a>FilePath</a>, <a>String</a>)] -&gt; <a>Eff</a> (FileSystem ': effs) <a>~&gt;</a> <a>Eff</a> effs
--   runInMemoryFileSystem initVfs = <a>evalState</a> initVfs <a>.</a> fsToState where
--     fsToState :: <a>Eff</a> (FileSystem ': effs) <a>~&gt;</a> <a>Eff</a> (<a>State</a> [(<a>FilePath</a>, <a>String</a>)] ': effs)
--     fsToState = <a>reinterpret</a> <a>$</a> case
--       ReadFile path -&gt; <a>get</a> <a>&gt;&gt;=</a> \vfs -&gt; case <a>lookup</a> path vfs of
--         <a>Just</a> contents -&gt; <a>pure</a> contents
--         <a>Nothing</a> -&gt; <a>error</a> ("readFile: no such file " ++ path)
--       WriteFile path contents -&gt; <a>modify</a> $ \vfs -&gt;
--         (path, contents) : <a>deleteBy</a> ((<a>==</a>) `<a>on</a>` <a>fst</a>) (path, contents) vfs
--   </pre>
--   
--   This handler is easy to write, doesn’t require any knowledge of how
--   <a>State</a> is implemented, is entirely encapsulated, and is
--   composable with all other effect handlers. This idea—making it easy to
--   define new effects in terms of existing ones—is the concept around
--   which <tt>freer-simple</tt> is based.
--   
--   <h1>Effect Algebras</h1>
--   
--   In <tt>freer-simple</tt>, effects are defined using <i>effect
--   algebras</i>, which are representations of an effect’s operations as a
--   generalized algebraic datatype, aka GADT. This might sound
--   intimidating, but you really don’t need to know very much at all about
--   how GADTs work to use <tt>freer-simple</tt>; instead, you can just
--   learn the syntax entirely in terms of what it means for defining
--   effects.
--   
--   Consider the definition of the <tt>FileSystem</tt> effect from the
--   above example:
--   
--   <pre>
--   data FileSystem r where
--     ReadFile :: <a>FilePath</a> -&gt; FileSystem <a>String</a>
--     WriteFile :: <a>FilePath</a> -&gt; <a>String</a> -&gt; FileSystem ()
--   </pre>
--   
--   The first line, <tt>data FileSystem r where</tt>, defines a new
--   effect. All effects have at least one parameter, normally named
--   <tt>r</tt>, which represents the <i>result</i> or <i>return type</i>
--   of the operation. For example, take a look at the type of
--   <tt>ReadFile</tt>:
--   
--   <pre>
--   ReadFile :: <a>FilePath</a> -&gt; FileSystem <a>String</a>
--   </pre>
--   
--   This is very similar to the type of <a>readFile</a> from the standard
--   <a>Prelude</a>, which has type <tt><a>FilePath</a> -&gt; <a>IO</a>
--   <a>String</a></tt>. The only difference is that the name of the
--   effect, in this case <tt>FileSystem</tt>, replaces the use of the
--   monad, in this case <a>IO</a>.
--   
--   Also notice that <tt>ReadFile</tt> and <tt>WriteFile</tt> begin with
--   capital letters. This is because they are actually <i>data
--   constructors</i>. This means that <tt>ReadFile "foo.txt"</tt> actually
--   constructs a <i>value</i> of type <tt>FileSystem <a>String</a></tt>,
--   and this is useful, since it allows effect handlers like
--   <tt>runInMemoryFileSystem</tt> to pattern-match on the effect’s
--   constructors and get the values out.
--   
--   To actually <i>use</i> our <tt>FileSystem</tt> effect, however, we
--   have to write just a little bit of glue to connect our effect
--   definition to the <a>Eff</a> monad, which we do using the <a>send</a>
--   function. We can write an ordinary function for each of the
--   <tt>FileSystem</tt> constructors that mechanically calls <a>send</a>:
--   
--   <pre>
--   readFile :: <a>Member</a> FileSystem effs =&gt; <a>FilePath</a> -&gt; <a>Eff</a> effs <a>String</a>
--   readFile path = <a>send</a> (ReadFile path)
--   
--   writeFile :: <a>Member</a> FileSystem effs =&gt; <a>FilePath</a> -&gt; <a>String</a> -&gt; <a>Eff</a> effs ()
--   writeFile path contents = <a>send</a> (WriteFile path contents)
--   </pre>
--   
--   Notice the use of the <a>Member</a> constraint on these functions.
--   This constraint means that the <tt>FileSystem</tt> effect can be
--   anywhere within the type-level list represented by the <tt>effs</tt>
--   variable. If the signature of <a>readFile</a> were more concrete, like
--   this:
--   
--   <pre>
--   readFile :: <a>FilePath</a> -&gt; <a>Eff</a> '[FileSystem] <a>String</a>
--   </pre>
--   
--   …then <a>readFile</a> would <i>only</i> be usable with an <a>Eff</a>
--   computation that <i>only</i> performed <tt>FileSystem</tt> effects,
--   which isn’t especially useful.
--   
--   Since writing these functions is entirely mechanical, they can be
--   generated automatically using Template Haskell; see
--   <a>Control.Monad.Freer.TH</a> for more details.
module Control.Monad.Freer

-- | The <a>Eff</a> monad provides the implementation of a computation that
--   performs an arbitrary set of algebraic effects. In <tt><a>Eff</a> effs
--   a</tt>, <tt>effs</tt> is a type-level list that contains all the
--   effects that the computation may perform. For example, a computation
--   that produces an <a>Integer</a> by consuming a <a>String</a> from the
--   global environment and acting upon a single mutable cell containing a
--   <a>Bool</a> would have the following type:
--   
--   <pre>
--   <a>Eff</a> '[<a>Reader</a> <a>String</a>, <a>State</a> <a>Bool</a>] <a>Integer</a>
--   </pre>
--   
--   Normally, a concrete list of effects is not used to parameterize
--   <a>Eff</a>. Instead, the <a>Member</a> or <a>Members</a> constraints
--   are used to express constraints on the list of effects without
--   coupling a computation to a concrete list of effects. For example, the
--   above example would more commonly be expressed with the following
--   type:
--   
--   <pre>
--   <a>Members</a> '[<a>Reader</a> <a>String</a>, <a>State</a> <a>Bool</a>] effs =&gt; <a>Eff</a> effs <a>Integer</a>
--   </pre>
--   
--   This abstraction allows the computation to be used in functions that
--   may perform other effects, and it also allows the effects to be
--   handled in any order.
data Eff effs a

-- | A constraint that requires that a particular effect, <tt>eff</tt>, is
--   a member of the type-level list <tt>effs</tt>. This is used to
--   parameterize an <a>Eff</a> computation over an arbitrary list of
--   effects, so long as <tt>eff</tt> is <i>somewhere</i> in the list.
--   
--   For example, a computation that only needs access to a cell of mutable
--   state containing an <a>Integer</a> would likely use the following
--   type:
--   
--   <pre>
--   <a>Member</a> (<a>State</a> <a>Integer</a>) effs =&gt; <a>Eff</a> effs ()
--   </pre>
class FindElem eff effs => Member (eff :: * -> *) effs

-- | A shorthand constraint that represents a combination of multiple
--   <a>Member</a> constraints. That is, the following <a>Members</a>
--   constraint:
--   
--   <pre>
--   <a>Members</a> '[Foo, Bar, Baz] effs
--   </pre>
--   
--   …is equivalent to the following set of <a>Member</a> constraints:
--   
--   <pre>
--   (<a>Member</a> Foo effs, <a>Member</a> Bar effs, <a>Member</a> baz effs)
--   </pre>
--   
--   Note that, since each effect is translated into a separate
--   <a>Member</a> constraint, the order of the effects does <i>not</i>
--   matter.
type family Members effs effs' :: Constraint

-- | Like <a>Member</a>, <tt><a>LastMember</a> eff effs</tt> is a
--   constraint that requires that <tt>eff</tt> is in the type-level list
--   <tt>effs</tt>. However, <i>unlike</i> <a>Member</a>, <a>LastMember</a>
--   requires <tt>m</tt> be the <b>final</b> effect in <tt>effs</tt>.
--   
--   Generally, this is not especially useful, since it is preferable for
--   computations to be agnostic to the order of effects, but it is quite
--   useful in combination with <a>sendM</a> or <a>liftBase</a> to embed
--   ordinary monadic effects within an <a>Eff</a> computation.
class Member m effs => LastMember m effs | effs -> m

-- | “Sends” an effect, which should be a value defined as part of an
--   effect algebra (see the module documentation for
--   <a>Control.Monad.Freer</a>), to an effectful computation. This is used
--   to connect the definition of an effect to the <a>Eff</a> monad so that
--   it can be used and handled.
send :: Member eff effs => eff a -> Eff effs a

-- | Identical to <a>send</a>, but specialized to the final effect in
--   <tt>effs</tt> to assist type inference. This is useful for running
--   actions in a monad transformer stack used in conjunction with
--   <a>runM</a>.
sendM :: (Monad m, LastMember m effs) => m a -> Eff effs a

-- | Embeds a less-constrained <a>Eff</a> into a more-constrained one.
--   Analogous to MTL's <tt>lift</tt>.
raise :: Eff effs a -> Eff (e : effs) a

-- | Runs a pure <a>Eff</a> computation, since an <a>Eff</a> computation
--   that performs no effects (i.e. has no effects in its type-level list)
--   is guaranteed to be pure. This is usually used as the final step of
--   running an effectful computation, after all other effects have been
--   discharged using effect handlers.
--   
--   Typically, this function is composed as follows:
--   
--   <pre>
--   someProgram
--     <a>&amp;</a> runEff1 eff1Arg
--     <a>&amp;</a> runEff2 eff2Arg1 eff2Arg2
--     <a>&amp;</a> <a>run</a>
--   </pre>
run :: Eff '[] a -> a

-- | Like <a>run</a>, <a>runM</a> runs an <a>Eff</a> computation and
--   extracts the result. <i>Unlike</i> <a>run</a>, <a>runM</a> allows a
--   single effect to remain within the type-level list, which must be a
--   monad. The value returned is a computation in that monad, which is
--   useful in conjunction with <a>sendM</a> or <a>liftBase</a> for
--   plugging in traditional transformer stacks.
runM :: Monad m => Eff '[m] a -> m a

-- | The simplest way to produce an effect handler. Given a natural
--   transformation from some effect <tt>eff</tt> to some effectful
--   computation with effects <tt>effs</tt>, produces a natural
--   transformation from <tt><a>Eff</a> (eff ': effs)</tt> to
--   <tt><a>Eff</a> effs</tt>.
interpret :: forall eff effs. (eff ~> Eff effs) -> Eff (eff : effs) ~> Eff effs

-- | Like <a>interpret</a>, but instead of handling the effect, allows
--   responding to the effect while leaving it unhandled.
interpose :: forall eff effs. Member eff effs => (eff ~> Eff effs) -> Eff effs ~> Eff effs

-- | Interprets an effect in terms of another identical effect. This can be
--   used to eliminate duplicate effects.
subsume :: forall eff effs. Member eff effs => Eff (eff : effs) ~> Eff effs

-- | Like <a>interpret</a>, but instead of removing the interpreted effect
--   <tt>f</tt>, reencodes it in some new effect <tt>g</tt>.
reinterpret :: forall f g effs. (f ~> Eff (g : effs)) -> Eff (f : effs) ~> Eff (g : effs)

-- | Like <a>reinterpret</a>, but encodes the <tt>f</tt> effect in
--   <i>two</i> new effects instead of just one.
reinterpret2 :: forall f g h effs. (f ~> Eff (g : (h : effs))) -> Eff (f : effs) ~> Eff (g : (h : effs))

-- | Like <a>reinterpret</a>, but encodes the <tt>f</tt> effect in
--   <i>three</i> new effects instead of just one.
reinterpret3 :: forall f g h i effs. (f ~> Eff (g : (h : (i : effs)))) -> Eff (f : effs) ~> Eff (g : (h : (i : effs)))

-- | Like <a>interpret</a>, <a>reinterpret</a>, <a>reinterpret2</a>, and
--   <a>reinterpret3</a>, but allows the result to have any number of
--   additional effects instead of simply 0-3. The problem is that this
--   completely breaks type inference, so you will have to explicitly pick
--   <tt>gs</tt> using <tt>TypeApplications</tt>. Prefer <a>interpret</a>,
--   <a>reinterpret</a>, <a>reinterpret2</a>, or <a>reinterpret3</a> where
--   possible.
reinterpretN :: forall gs f effs. Weakens gs => (f ~> Eff (gs :++: effs)) -> Eff (f : effs) ~> Eff (gs :++: effs)

-- | Runs an effect by translating it into another effect. This is
--   effectively a more restricted form of <a>reinterpret</a>, since both
--   produce a natural transformation from <tt><a>Eff</a> (f ': effs)</tt>
--   to <tt><a>Eff</a> (g ': effs)</tt> for some effects <tt>f</tt> and
--   <tt>g</tt>, but <a>translate</a> does not permit using any of the
--   other effects in the implementation of the interpreter.
--   
--   In practice, this difference in functionality is not particularly
--   useful, and <a>reinterpret</a> easily subsumes all of the
--   functionality of <a>translate</a>, but the way <a>translate</a>
--   restricts the result leads to much better type inference.
--   
--   <pre>
--   <a>translate</a> f = <a>reinterpret</a> (<a>send</a> . f)
--   </pre>
translate :: forall f g effs. (f ~> g) -> Eff (f : effs) ~> Eff (g : effs)

-- | Like <a>interpret</a>, this function runs an effect without
--   introducing another one. Like <a>translate</a>, this function runs an
--   effect by translating it into another effect in isolation, without
--   access to the other effects in <tt>effs</tt>. Unlike either of those
--   functions, however, this runs the effect in a final monad in
--   <tt>effs</tt>, intended to be run with <a>runM</a>.
--   
--   <pre>
--   <a>interpretM</a> f = <a>interpret</a> (<a>sendM</a> . f)
--   </pre>
interpretM :: forall eff m effs. (Monad m, LastMember m effs) => (eff ~> m) -> Eff (eff : effs) ~> Eff effs

-- | A highly general way of handling an effect. Like <a>interpret</a>, but
--   explicitly passes the <i>continuation</i>, a function of type <tt>v
--   -&gt; <a>Eff</a> effs b</tt>, to the handler function. Most handlers
--   invoke this continuation to resume the computation with a particular
--   value as the result, but some handlers may return a value without
--   resumption, effectively aborting the computation to the point where
--   the handler is invoked. This is useful for implementing things like
--   <a>catchError</a>, for example.
--   
--   <pre>
--   <a>interpret</a> f = <a>interpretWith</a> (e -&gt; (f e <a>&gt;&gt;=</a>))
--   </pre>
interpretWith :: forall eff effs b. (forall v. eff v -> (v -> Eff effs b) -> Eff effs b) -> Eff (eff : effs) b -> Eff effs b

-- | Combines the interposition behavior of <a>interpose</a> with the
--   continuation-passing capabilities of <a>interpretWith</a>.
--   
--   <pre>
--   <a>interpose</a> f = <a>interposeWith</a> (e -&gt; (f e <a>&gt;&gt;=</a>))
--   </pre>
interposeWith :: forall eff effs b. Member eff effs => (forall v. eff v -> (v -> Eff effs b) -> Eff effs b) -> Eff effs b -> Eff effs b

-- | A natural transformation from <tt>f</tt> to <tt>g</tt>.
type (~>) (f :: k -> Type) (g :: k -> Type) = forall (x :: k). () => f x -> g x
infixr 0 ~>


-- | This module provides Template Haskell functions for automatically
--   generating effect operation functions (that is, functions that use
--   <a>send</a>) from a given effect algebra. For example, using the
--   <tt>FileSystem</tt> effect from the example in the module
--   documentation for <a>Control.Monad.Freer</a>, we can write the
--   following:
--   
--   <pre>
--   data FileSystem r where
--     ReadFile :: <a>FilePath</a> -&gt; FileSystem <a>String</a>
--     WriteFile :: <a>FilePath</a> -&gt; <a>String</a> -&gt; FileSystem ()
--   <a>makeEffect</a> ''FileSystem
--   </pre>
--   
--   This will automatically generate the following functions:
--   
--   <pre>
--   readFile :: <a>Member</a> FileSystem effs =&gt; <a>FilePath</a> -&gt; <a>Eff</a> effs <a>String</a>
--   readFile a = <a>send</a> (ReadFile a)
--   
--   writeFile :: <a>Member</a> FileSystem effs =&gt; <a>FilePath</a> -&gt; <a>String</a> -&gt; <a>Eff</a> effs ()
--   writeFile a b = <a>send</a> (WriteFile a b)
--   </pre>
module Control.Monad.Freer.TH

-- | If <tt>T</tt> is a GADT representing an effect algebra, as described
--   in the module documentation for <a>Control.Monad.Freer</a>,
--   <tt>$(<a>makeEffect</a> ''T)</tt> automatically generates a function
--   that uses <a>send</a> with each operation. For more information, see
--   the module documentation for <a>Control.Monad.Freer.TH</a>.
makeEffect :: Name -> Q [Dec]

-- | Like <a>makeEffect</a>, but does not provide type signatures. This can
--   be used to attach Haddock comments to individual arguments for each
--   generated function.
--   
--   <pre>
--   data Lang x where
--     Output :: String -&gt; Lang ()
--   
--   makeEffect_ ''Lang
--   
--   -- | Output a string.
--   output :: Member Lang effs
--          =&gt; String    -- ^ String to output.
--          -&gt; Eff effs ()  -- ^ No result.
--   </pre>
--   
--   Note that <a>makeEffect_</a> must be used <i>before</i> the explicit
--   type signatures.
makeEffect_ :: Name -> Q [Dec]


-- | Composable handler for <a>State</a> effects. Handy for passing an
--   updatable state through a computation.
--   
--   Some computations may not require the full power of <a>State</a>
--   effect:
--   
--   <ul>
--   <li>For a read-only state, see <a>Control.Monad.Freer.Reader</a>.</li>
--   <li>To accumulate a value without using it on the way, see
--   <a>Control.Monad.Freer.Writer</a>.</li>
--   </ul>
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.State

-- | Strict <a>State</a> effects: one can either <a>Get</a> values or
--   <a>Put</a> them.
data State s r
[Get] :: State s s
[Put] :: !s -> State s ()

-- | Retrieve the current value of the state of type <tt>s :: *</tt>.
get :: forall s effs. Member (State s) effs => Eff effs s

-- | Set the current state to a specified value of type <tt>s :: *</tt>.
put :: forall s effs. Member (State s) effs => s -> Eff effs ()

-- | Modify the current state of type <tt>s :: *</tt> using provided
--   function <tt>(s -&gt; s)</tt>.
modify :: forall s effs. Member (State s) effs => (s -> s) -> Eff effs ()

-- | Retrieve a specific component of the current state using the provided
--   projection function.
gets :: forall s a effs. Member (State s) effs => (s -> a) -> Eff effs a

-- | Handler for <a>State</a> effects.
runState :: forall s effs a. s -> Eff (State s : effs) a -> Eff effs (a, s)

-- | Run a State effect, discarding the final state.
evalState :: forall s effs a. s -> Eff (State s : effs) a -> Eff effs a

-- | Run a <a>State</a> effect, returning only the final state.
execState :: forall s effs a. s -> Eff (State s : effs) a -> Eff effs s

-- | An encapsulated State handler, for transactional semantics. The global
--   state is updated only if the <a>transactionState</a> finished
--   successfully.
--   
--   GHC cannot infer the <tt>s</tt> type parameter for this function, so
--   it must be specified explicitly with <tt>TypeApplications</tt>.
--   Alternatively, it can be specified by supplying a <a>Proxy</a> to
--   <a>transactionState'</a>.
transactionState :: forall s effs a. Member (State s) effs => Eff effs a -> Eff effs a

-- | Like <a>transactionState</a>, but <tt>s</tt> is specified by providing
--   a <a>Proxy</a> instead of requiring <tt>TypeApplications</tt>.
transactionState' :: forall s effs a. Member (State s) effs => Proxy s -> Eff effs a -> Eff effs a


-- | Composable handler for <a>Reader</a> effects. Handy for encapsulating
--   an environment with immutable state for interpreters.
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Reader

-- | Represents shared immutable environment of type <tt>(e :: *)</tt>
--   which is made available to effectful computation.
data Reader r a
[Ask] :: Reader r r

-- | Request a value of the environment.
ask :: forall r effs. Member (Reader r) effs => Eff effs r

-- | Request a value of the environment, and apply as selector/projection
--   function to it.
asks :: forall r effs a. Member (Reader r) effs => (r -> a) -> Eff effs a

-- | Locally rebind the value in the dynamic environment.
--   
--   This function is like a relay; it is both an admin for <a>Reader</a>
--   requests, and a requestor of them.
local :: forall r effs a. Member (Reader r) effs => (r -> r) -> Eff effs a -> Eff effs a

-- | Handler for <a>Reader</a> effects.
runReader :: forall r effs a. r -> Eff (Reader r : effs) a -> Eff effs a


-- | Composable handler for Error effects. Communicates success/failure via
--   an <a>Either</a> type.
--   
--   Using <a>http://okmij.org/ftp/Haskell/extensible/Eff1.hs</a> as a
--   starting point.
module Control.Monad.Freer.Error

-- | Exceptions of the type <tt>e :: *</tt> with no resumption.
newtype Error e r
[Error] :: e -> Error e r

-- | Throws an error carrying information of type <tt>e :: *</tt>.
throwError :: forall e effs a. Member (Error e) effs => e -> Eff effs a

-- | Handler for exception effects. If there are no exceptions thrown,
--   returns <a>Right</a>. If exceptions are thrown and not handled,
--   returns <a>Left</a>, while interrupting the execution of any other
--   effect handlers.
runError :: forall e effs a. Eff (Error e : effs) a -> Eff effs (Either e a)

-- | A catcher for Exceptions. Handlers are allowed to rethrow exceptions.
catchError :: forall e effs a. Member (Error e) effs => Eff effs a -> (e -> Eff effs a) -> Eff effs a

-- | A catcher for Exceptions. Handlers are <i>not</i> allowed to rethrow
--   exceptions.
handleError :: forall e effs a. Eff (Error e : effs) a -> (e -> Eff effs a) -> Eff effs a
