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


-- | A Typeable-free implementation of extensible effects
--   
--   This package implements extensible effects, an alternative to monad
--   transformers. The original paper can be found at
--   <a>http://okmij.org/ftp/Haskell/extensible/exteff.pdf</a>. The main
--   differences between this library and the one described in the paper
--   are that this library does not use the Typeable type class, does not
--   require that effects implement the Functor type class, and has a
--   simpler API for handling effects.
--   
--   For example, the following code implements a handler for exceptions:
--   
--   <pre>
--   newtype Exception e = Throw e
--   
--   runException :: Effect (Exception e :+ es) a -&gt; Effect es (Either e a)
--   runException = eliminate
--       (\x -&gt; return (Right x))
--       (\(Throw e) k -&gt; return (Left e))
--   </pre>
--   
--   Compare this to the corresponding code in extensible-effects
--   (<a>http://hackage.haskell.org/package/extensible-effects</a>):
--   
--   <pre>
--   runExc :: Typeable e =&gt; Eff (Exc e :&gt; r) a -&gt; Eff r (Either e a)
--   runExc = loop . admin
--     where
--       loop (Val x) = return (Right x)
--       loop (E u)   = handleRelay u loop (\(Exc e) -&gt; return (Left e))
--   </pre>
--   
--   In particular, effect implementors are not required to do any
--   recursion, thereby making effect handlers more composeable.
@package effin
@version 0.3.0.2

module Control.Monad.Effect

-- | An effectful computation. An <tt>Effect l a</tt> may perform any of
--   the effects specified by the list of effects <tt>l</tt> before
--   returning a result of type <tt>a</tt>. The definition is isomorphic to
--   the following GADT:
--   
--   <pre>
--   data Effect l a where
--       Done :: a -&gt; Effect l a
--       Side :: <a>Union</a> l (Effect l a) -&gt; Effect l a
--   </pre>
data Effect l a

-- | Converts an computation that produces no effects into a regular value.
runEffect :: Effect Nil a -> a

-- | Executes an effect of type <tt>f</tt> that produces a return value of
--   type <tt>a</tt>.
send :: Member f l => f a -> Effect l a

-- | Executes an effect of type <tt>f</tt> that produces a return value of
--   type <tt>r</tt>. Note that a specific instance of this function is of
--   type <tt>Member f l =&gt; f (Effect l a) -&gt; Effect l a</tt>, which
--   allows users to send effects parameterized by effects.
sendEffect :: (Member f l, Effectful l r) => f r -> r

-- | The class of types which result in an effect. That is:
--   
--   <pre>
--   Effect l r
--   a -&gt; Effect l r
--   a -&gt; b -&gt; Effect l r
--   ...
--   </pre>
class l ~ EffectsOf r => Effectful l r where type EffectsOf r :: Row (* -> *) relay = undefined where {
    type family EffectsOf r :: Row (* -> *);
}

-- | Completely handles an effect. The second function parameter is passed
--   an effect value and a continuation function.
--   
--   The most common instantiation of this function is:
--   
--   <pre>
--   (a -&gt; Effect l b) -&gt; (f (Effect l b) -&gt; Effect l b) -&gt; Effect (f ': l) a -&gt; Effect l b
--   </pre>
eliminate :: Effectful l r => (a -> r) -> (forall b. f b -> (b -> r) -> r) -> Effect (f :+ l) a -> r

-- | Handles an effect without eliminating it. The second function
--   parameter is passed an effect value and a continuation function.
--   
--   The most common instantiation of this function is:
--   
--   <pre>
--   (a -&gt; Effect l b) -&gt; (f (Effect l b) -&gt; Effect l b) -&gt; Effect l a -&gt; Effect l b
--   </pre>
intercept :: (Effectful l r, Member f l) => (a -> r) -> (forall b. f b -> (b -> r) -> r) -> Effect l a -> r

-- | Adds an arbitrary effect to the head of the effect list.
extend :: Effect l a -> Effect (f :+ l) a

-- | Enables an effect that was previously disabled.
enable :: Effect (f :- l) a -> Effect l a

-- | Hides an effect <tt>f</tt> by translating each instance of the effect
--   into an equivalent effect further into the effect list.
--   
--   <pre>
--   conceal = eliminate return (\x k -&gt; send x &gt;&gt;= k)
--   </pre>
conceal :: Member f l => Effect (f :+ l) a -> Effect l a

-- | Hides an effect <tt>f</tt> by translating each instance of the effect
--   into an equivalent effect at the head of the effect list.
reveal :: Member f l => Effect l a -> Effect (f :+ l) a

-- | Translates the first effect in the effect list into another effect.
--   
--   <pre>
--   rename f = eliminate return (\x k -&gt; send (f x) &gt;&gt;= k) . swap . extend
--   </pre>
rename :: (forall r. f r -> g r) -> Effect (f :+ l) a -> Effect (g :+ l) a

-- | Reorders the first two effects in a computation.
swap :: Effect (f :+ (g :+ l)) a -> Effect (g :+ (f :+ l)) a

-- | Rotates the first three effects in a computation.
rotate :: Effect (f :+ (g :+ (h :+ l))) a -> Effect (g :+ (h :+ (f :+ l))) a

-- | Converts a set of effects <tt>l</tt> into a single effect <tt>f</tt>.
--   
--   <pre>
--   mask f = <a>conceal</a> . <a>rename</a> f . <a>unflatten</a>
--   </pre>
mask :: (KnownLength l, Member f m) => (forall r. Union l r -> f r) -> Effect (l :++ m) a -> Effect m a

-- | Converts an effect <tt>f</tt> into a set of effects <tt>l</tt>.
--   
--   <pre>
--   unmask f = <a>flatten</a> . <a>rename</a> f . <a>reveal</a>
--   </pre>
unmask :: (Inclusive l, Member f m) => (forall r. f r -> Union l r) -> Effect m a -> Effect (l :++ m) a

-- | Represents a union of the list of type constructors in <tt>l</tt>
--   parameterized by <tt>a</tt>. As an effect, it represents the union of
--   each type constructor's corresponding effect. From the user's
--   perspective, it provides a way to encapsulate multiple effects.
data Union l a

-- | Distributes the sub-effects of a <a>Union</a> effect across a
--   computation.
flatten :: Inclusive l => Effect (Union l :+ m) a -> Effect (l :++ m) a

-- | Collects some effects in a computation into a <a>Union</a> effect.
unflatten :: KnownLength l => Effect (l :++ m) a -> Effect (Union l :+ m) a

-- | A constraint specifying that <tt>e</tt> is a member of the <a>Row</a>
--   <tt>l</tt>.
class KnownNat (IndexOf e l) => Member e l

-- | A refined <a>Member</a>ship constraint that can infer <tt>f</tt> from
--   <tt>l</tt>, given <tt>name</tt>. In order for this to be used,
--   <tt><a>Is</a> name f</tt> must be defined. For example:
--   
--   <pre>
--   data Reader r a = ...
--   
--   type instance Is Reader f = IsReader f
--   
--   type IsReader f where
--       IsReader (Reader r) = True
--       IsReader f = False
--   
--   type ReaderEffect r l = MemberEffect Reader (Reader r) l
--   
--   ask :: ReaderEffect r l =&gt; Effect l r
--   ask = ...
--   </pre>
--   
--   Given the constraint <tt>ReaderEffect r l</tt> in the above example,
--   <tt>r</tt> can be inferred from <tt>l</tt>.
class (Member f l, f ~ InstanceOf name l) => MemberEffect name f l

-- | Returns a boolean value indicating whether <tt>f</tt> belongs to the
--   group of effects identified by <tt>name</tt>. This allows
--   <tt>MemberEffect</tt> to infer the associated types for arbitrary
--   effects.

-- | A type level list with explicit removals.
data Row a

-- | The empty list.
Nil :: Row a

-- | Prepends an element (cons).
(:+) :: a -> Row a -> Row a

-- | Deletes the first instance an element.
(:-) :: a -> Row a -> Row a

-- | Appends two type level <a>Row</a>s.

-- | The class of <a>Row</a>s with statically known lengths.
class KnownNat (Length l) => KnownLength l

-- | The class of <a>Row</a>s that do not contain deletions (`<a>:-</a>).
class KnownLength l => Inclusive l
instance GHC.Base.Functor (Control.Monad.Effect.Effect l)
instance GHC.Base.Applicative (Control.Monad.Effect.Effect l)
instance GHC.Base.Monad (Control.Monad.Effect.Effect l)
instance Control.Monad.Effect.Effectful l (Control.Monad.Effect.Effect l a)
instance Control.Monad.Effect.Effectful l r => Control.Monad.Effect.Effectful l (a -> r)
instance forall k (f :: GHC.Types.* -> GHC.Types.*) (l :: Data.Type.Row.Row (GHC.Types.* -> GHC.Types.*)) (name :: k). (Data.Type.Row.Member f l, f ~ Data.Type.Row.InstanceOf name l) => Control.Monad.Effect.MemberEffect name f l

module Control.Effect.Witness
class MemberEffect Witness (Witness s) l => EffectWitness s l

-- | An effect describing the generation of unique identifiers.
data Witness s a

-- | Completely handles a <a>Witness</a> effect. The Rank-2 quantifier
--   ensures that unique identifiers cannot escape the context in which
--   they were created.
runWitness :: (forall s. Effect (Witness s :+ l) a) -> Effect l a

-- | A unique identifier associated with a type <tt>a</tt>. If two tokens
--   are equal, then so are their associated types. Use <a>testEquality</a>
--   to safely cast between types.
data Token s a

-- | Generates a new, unique <a>Token</a>.
newToken :: EffectWitness s l => Effect l (Token s a)
instance GHC.Classes.Eq (Control.Effect.Witness.Token s a)
instance Data.Type.Equality.TestEquality (Control.Effect.Witness.Token s)
instance Control.Monad.Effect.MemberEffect Control.Effect.Witness.Witness (Control.Effect.Witness.Witness s) l => Control.Effect.Witness.EffectWitness s l

module Control.Effect.State
class MemberEffect State (State s) l => EffectState s l

-- | An effect where a state value is threaded throughout the computation.
data State s a

-- | Completely handles a <a>State</a> effect by providing an initial
--   state, and making the final state explicit.
runState :: s -> Effect (State s :+ l) a -> Effect l (a, s)

-- | Completely handles a <a>State</a> effect, and discards the final
--   state.
evalState :: s -> Effect (State s :+ l) a -> Effect l a

-- | Completely handles a <a>State</a> effect, and discards the final
--   value.
execState :: s -> Effect (State s :+ l) a -> Effect l s

-- | Gets the current state.
get :: EffectState s l => Effect l s

-- | Gets a value that is a function of the current state.
gets :: EffectState s l => (s -> a) -> Effect l a

-- | Replaces the current state.
put :: EffectState s l => s -> Effect l ()

-- | Applies a pure modifier to the state value.
modify :: EffectState s l => (s -> s) -> Effect l ()

-- | Applies a pure modifier to the state value. The modified value is
--   converted to weak head normal form.
modify' :: EffectState s l => (s -> s) -> Effect l ()

-- | Lifts a stateful computation to the <a>Effect</a> monad.
state :: EffectState s l => (s -> (a, s)) -> Effect l a

-- | Runs a computation with a modified state value.
--   
--   <pre>
--   withState f x = modify f &gt;&gt; x
--   </pre>
withState :: EffectState s l => (s -> s) -> Effect l a -> Effect l a
instance (Data.Type.Row.Member (Control.Effect.State.State s) l, Control.Effect.State.State s ~ Data.Type.Row.InstanceOf Control.Effect.State.State l) => Control.Monad.State.Class.MonadState s (Control.Monad.Effect.Effect l)
instance Control.Monad.Effect.MemberEffect Control.Effect.State.State (Control.Effect.State.State s) l => Control.Effect.State.EffectState s l

module Control.Effect.Writer
class (Monoid w, MemberEffect Writer (Writer w) l) => EffectWriter w l

-- | An effect that allows accumulating output.
data Writer w a

-- | Completely handles a writer effect. The writer value must be a
--   <a>Monoid</a>. <a>mempty</a> is used as an initial value, and
--   <a>mappend</a> is used to combine values. Returns the result of the
--   computation and the final output value.
runWriter :: Monoid w => Effect (Writer w :+ l) a -> Effect l (a, w)

-- | Writes a value to the output.
tell :: EffectWriter w l => w -> Effect l ()

-- | Executes a computation, and obtains the writer output. The writer
--   output of the inner computation is still written to the writer output
--   of the outer computation.
listen :: EffectWriter w l => Effect l a -> Effect l (a, w)

-- | Like <a>listen</a>, but the writer output is run through a function.
listens :: EffectWriter w l => (w -> b) -> Effect l a -> Effect l (a, b)

-- | Runs a computation that returns a value and a function, applies the
--   function to the writer output, and then returns the value.
pass :: EffectWriter w l => Effect l (a, w -> w) -> Effect l a

-- | Applies a function to the writer output of a computation.
censor :: EffectWriter w l => (w -> w) -> Effect l a -> Effect l a

-- | Executes a writer computation which sends its output to a state
--   effect.
stateWriter :: (Monoid s, EffectState s l) => Effect (Writer s :+ l) a -> Effect l a
instance (GHC.Base.Monoid w, Data.Type.Row.Member (Control.Effect.Writer.Writer w) l, Control.Effect.Writer.Writer w ~ Data.Type.Row.InstanceOf Control.Effect.Writer.Writer l) => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Effect.Effect l)
instance (GHC.Base.Monoid w, Control.Monad.Effect.MemberEffect Control.Effect.Writer.Writer (Control.Effect.Writer.Writer w) l) => Control.Effect.Writer.EffectWriter w l

module Control.Effect.Reader
class MemberEffect Reader (Reader r) l => EffectReader r l

-- | An effect that provides an implicit environment.
data Reader r a

-- | Completely handles a <a>Reader</a> effect by providing an environment
--   value to be used throughout the computation.
runReader :: r -> Effect (Reader r :+ l) a -> Effect l a

-- | Retrieves the current environment.
ask :: EffectReader r l => Effect l r

-- | Retrieves a value that is a function of the current environment.
asks :: EffectReader r l => (r -> a) -> Effect l a

-- | Runs a computation with a modified environment.
local :: EffectReader r l => (r -> r) -> Effect l a -> Effect l a

-- | Executes a reader computation which obtains its environment value from
--   a state effect.
stateReader :: EffectState s l => Effect (Reader s :+ l) a -> Effect l a
instance (Data.Type.Row.Member (Control.Effect.Reader.Reader r) l, Control.Effect.Reader.Reader r ~ Data.Type.Row.InstanceOf Control.Effect.Reader.Reader l) => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Effect.Effect l)
instance Control.Monad.Effect.MemberEffect Control.Effect.Reader.Reader (Control.Effect.Reader.Reader r) l => Control.Effect.Reader.EffectReader r l

module Control.Effect.List
class Member List l => EffectList l

-- | A nondeterminism (backtracking) effect.
data List a

-- | Obtains all possible values from a computation parameterized by a
--   nondeterminism effect.
runList :: Effect (List :+ l) a -> Effect l [a]

-- | Nondeterministically chooses a value from the input list.
choose :: EffectList l => [a] -> Effect l a

-- | Describes a nondeterministic computation that never returns a value.
never :: EffectList l => Effect l a

-- | Nondeterministically chooses a value from a list of computations.
select :: EffectList l => [Effect l a] -> Effect l a
class (EffectList l, Member Cut l) => CutEffect l

-- | Describes a Prolog-like cut effect. This effect must be used with the
--   <a>List</a> effect.
data Cut a

-- | Handles the <a>Cut</a> effect. <a>cut</a>s have no effect beyond the
--   scope of the computation passed to this function.
runCut :: EffectList l => Effect (Cut :+ l) a -> Effect l a

-- | Prevents backtracking past the point this value was invoked, in the
--   style of Prolog's "!" operator.
cut :: CutEffect l => Effect l ()

-- | Prevents backtracking past the point this value was invoked. Unlike
--   Prolog's "!" operator, <a>cutFalse</a> will cause the current
--   computation to fail immediately, instead of when it backtracks.
cutFalse :: CutEffect l => Effect l a
instance Data.Type.Row.Member Control.Effect.List.List l => Control.Effect.List.EffectList l
instance Control.Effect.List.EffectList l => GHC.Base.Alternative (Control.Monad.Effect.Effect l)
instance Control.Effect.List.EffectList l => GHC.Base.MonadPlus (Control.Monad.Effect.Effect l)
instance (Control.Effect.List.EffectList l, Data.Type.Row.Member Control.Effect.List.Cut l) => Control.Effect.List.CutEffect l

module Control.Effect.Lift
class (Monad m, MemberEffect Lift (Lift m) l) => EffectLift m l

-- | An effect described by a monad.
newtype Lift m a
Lift :: m a -> Lift m a
[unLift] :: Lift m a -> m a

-- | Converts a computation containing only monadic effects into a monadic
--   computation.
runLift :: Monad m => Effect (Lift m :+ Nil) a -> m a

-- | Lifts a monadic value into an effect.
lift :: EffectLift m l => m a -> Effect l a

-- | Lifts a monadic value into an effect.
liftEffect :: EffectLift m l => m (Effect l a) -> Effect l a
instance Control.Effect.Lift.EffectLift GHC.Types.IO l => Control.Monad.IO.Class.MonadIO (Control.Monad.Effect.Effect l)
instance (GHC.Base.Monad m, Control.Monad.Effect.MemberEffect Control.Effect.Lift.Lift (Control.Effect.Lift.Lift m) l) => Control.Effect.Lift.EffectLift m l

module Control.Effect.Thread
class Member Thread l => EffectThread l

-- | An effect that describes concurrent computation.
data Thread a

-- | Executes a threaded computation synchronously. Completes when the main
--   thread exits.
runMain :: Effect (Thread :+ l) () -> Effect l ()

-- | Executes a threaded computation synchronously. Does not complete until
--   all threads have exited.
runSync :: Effect (Thread :+ l) () -> Effect l ()

-- | Executes a threaded computation asynchronously.
runAsync :: Effect (Thread :+ (Lift IO :+ Nil)) () -> IO ()

-- | Yields to the next available thread.
yield :: EffectThread l => Effect l ()

-- | Forks a child thread.
fork :: EffectThread l => Effect l () -> Effect l ()

-- | Immediately terminates the current thread.
abort :: EffectThread l => Effect l ()
instance Data.Type.Row.Member Control.Effect.Thread.Thread l => Control.Effect.Thread.EffectThread l

module Control.Effect.Coroutine
class MemberEffect Coroutine (Coroutine i o) l => EffectCoroutine i o l

-- | An effect describing a suspendable computation.
data Coroutine i o a

-- | Converts a <a>Coroutine</a> effect into an <a>Iterator</a>.
runCoroutine :: Effect (Coroutine i o :+ l) a -> Effect l (Iterator i o l a)

-- | Suspends the current computation by providing a value of type
--   <tt>i</tt> and then waiting for a value of type <tt>o</tt>.
suspend :: EffectCoroutine i o l => i -> Effect l o

-- | A suspended computation.
data Iterator i o l a

-- | Describes a finished computation.
Done :: a -> Iterator i o l a

-- | Describes a computation that provided a value of type <tt>i</tt> and
--   awaits a value of type <tt>o</tt>.
Next :: (o -> Effect l (Iterator i o l a)) -> i -> Iterator i o l a

-- | Evaluates an iterator by providing it with an input stream.
evalIterator :: Iterator i o l a -> [o] -> Effect l (Iterator i o l a, [i])
instance Control.Monad.Effect.MemberEffect Control.Effect.Coroutine.Coroutine (Control.Effect.Coroutine.Coroutine i o) l => Control.Effect.Coroutine.EffectCoroutine i o l

module Control.Effect.Bracket
class MemberEffect Bracket (Bracket s) l => EffectBracket s l

-- | Provides a base effect for exceptions. This effect allows the dynamic
--   generation of exception classes at runtime.
data Bracket s a

-- | Executes a <a>Bracket</a> effect. The Rank-2 type ensures that
--   <a>Tag</a>s do not escape their scope.
runBracket :: (forall s. Effect (Bracket s :+ l) a) -> Effect l a

-- | The type of placeholder values indicating an exception class.
data Tag s a

-- | Creates a new tag. The function parameter describes the error message
--   that is shown in the case of an uncaught exception.
newTag :: EffectBracket s l => (a -> String) -> Effect l (Tag s a)

-- | Raises an exception of the specified class and value.
raiseWith :: EffectBracket s l => Tag s b -> b -> Effect l a

-- | Specifies a handler for exceptions of a given class.
exceptWith :: EffectBracket s l => Tag s b -> Effect l a -> (b -> Effect l a) -> Effect l a

-- | A handler for an exception. Use with <a>exceptAny</a>.
data Handler s l a

-- | Specifies a number of handlers for exceptions thrown by the given
--   computation. This is prefered over chained calles to
--   <a>exceptWith</a>, i.e.
--   
--   <pre>
--   exceptWith t2 (exceptWith t1 m h1) h2
--   </pre>
--   
--   because <tt>h2</tt> could catch exceptions thrown by <tt>h1</tt>.
exceptAny :: EffectBracket s l => Effect l a -> [Handler s l a] -> Effect l a

-- | Executes a computation with a resource, and ensures that the resource
--   is cleaned up afterwards.
bracket :: EffectBracket s l => Effect l a -> (a -> Effect l ()) -> (a -> Effect l b) -> Effect l b

-- | A specialized version of <a>bracket</a> which does not require an
--   <tt>acquire</tt> operation.
finally :: EffectBracket s l => Effect l a -> Effect l () -> Effect l a
instance Data.Type.Equality.TestEquality (Control.Effect.Bracket.Tag s)
instance Control.Monad.Effect.MemberEffect Control.Effect.Bracket.Bracket (Control.Effect.Bracket.Bracket s) l => Control.Effect.Bracket.EffectBracket s l

module Control.Effect.Exception
class (EffectBracket s l, MemberEffect Exception (Exception s e) l) => EffectException s e l

-- | An effect that describes the possibility of failure.
data Exception s e a

-- | Completely handles an exception effect.
runException :: (EffectBracket s l, Show e) => Effect (Exception s e :+ l) a -> Effect l (Either e a)

-- | Raises an exception.
raise :: EffectException s e l => e -> Effect l a

-- | Handles an exception. Intended to be used in infix form.
--   
--   <pre>
--   myComputation `except` \ex -&gt; doSomethingWith ex
--   </pre>
except :: EffectException s e l => Effect l a -> (e -> Effect l a) -> Effect l a
instance (Control.Effect.Bracket.EffectBracket s l, Data.Type.Row.Member (Control.Effect.Exception.Exception s e) l, Control.Effect.Exception.Exception s e ~ Data.Type.Row.InstanceOf Control.Effect.Exception.Exception l) => Control.Monad.Error.Class.MonadError e (Control.Monad.Effect.Effect l)
instance (Control.Effect.Bracket.EffectBracket s l, Control.Monad.Effect.MemberEffect Control.Effect.Exception.Exception (Control.Effect.Exception.Exception s e) l) => Control.Effect.Exception.EffectException s e l

module Control.Effect