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


-- | Control
--   
--   This library implements a monad transformer for suspendable
--   computations, similar and related to free comonads. It allows to write
--   continuation-based web frameworks, command line applications and
--   similar interfaces.
@package continue
@version 0.1.0


module Control.Continue.Class

-- | Type class for monads that support suspension and continuation spots.
class (Plus f, Monad m, Monoid e) => MonadContinue e f m | m -> e, m -> f
addCont :: MonadContinue e f m => Either e a -> f (m a) -> m a
instance (MonadContinue e f m, Monoid l) => MonadContinue e f (WriterT l m)
instance (MonadContinue e f m, Monoid l) => MonadContinue e f (WriterT l m)
instance MonadContinue e f m => MonadContinue e f (StateT s m)
instance MonadContinue e f m => MonadContinue e f (StateT s m)
instance MonadContinue e f m => MonadContinue e f (ReaderT r m)
instance MonadContinue e f m => MonadContinue e f (MaybeT m)
instance MonadContinue e f m => MonadContinue e f (IdentityT m)


-- | Types used in the continue library.
module Control.Continue.Types

-- | This monad transformer adds continuations under <tt>f</tt> and
--   <tt>e</tt>-typed suspensions to <tt>m</tt>.
newtype ContinueT e f m a
ContinueT :: m (Either e a, f (ContinueT e f m a)) -> ContinueT e f m a
runContinueT :: ContinueT e f m a -> m (Either e a, f (ContinueT e f m a))

-- | <a>ContinueT</a> over <a>Identity</a>.
type Continue e f = ContinueT e f Identity

-- | Type alias for the common case of using <tt><a>Last</a>
--   <a>SomeException</a></tt> as the suspension monoid.
type LastEx = Last SomeException
instance (MonadWriter l m, Monoid e, Plus f) => MonadWriter l (ContinueT e f m)
instance Plus f => MonadTrans (ContinueT e f)
instance (MonadState s m, Monoid e, Plus f) => MonadState s (ContinueT e f m)
instance (MonadReader r m, Monoid e, Plus f) => MonadReader r (ContinueT e f m)
instance (Monad m, Monoid e, Plus f) => MonadPlus (ContinueT e f m)
instance (MonadIO m, Monoid e, Plus f) => MonadIO (ContinueT e f m)
instance (MonadFix m, Monoid e, Plus f) => MonadFix (ContinueT e f m)
instance (Monad m, Monoid e, Plus f) => MonadError e (ContinueT e f m)
instance (Monad m, Monoid e, Plus f) => MonadContinue e f (ContinueT e f m)
instance (MonadBaseControl b m, Monoid e, Plus f) => MonadBaseControl b (ContinueT e f m)
instance (MonadBase b m, Monoid e, Plus f) => MonadBase b (ContinueT e f m)
instance (Monad m, Monoid e, Plus f) => Monad (ContinueT e f m)
instance (Functor f, Monad m) => Functor (ContinueT e f m)
instance (Monad m, Plus f) => Applicative (ContinueT e f m)
instance (Monad m, Monoid e, Plus f) => Alternative (ContinueT e f m)


-- | Suspension/continuation utilities.
module Control.Continue.Utils

-- | Add the given set of continuations without suspending.
addCont_ :: MonadContinue e f m => f (m ()) -> m ()

-- | Allow to continue here with the given value.
continue :: MonadContinue e f m => Either e a -> f (Either e a) -> m a

-- | Allow to continue here.
continue_ :: MonadContinue e f m => f () -> m ()

-- | Suspend with the given value. Does not register any continuation
--   spots. Note that <tt>suspend mempty</tt> is equivalent to
--   <tt>empty</tt>.
suspend :: MonadContinue e f m => e -> m a


-- | Proxy to the various modules of the continue package.
module Control.Continue

-- | Laws:
--   
--   <pre>
--   &lt;!&gt; is associative:             (a &lt;!&gt; b) &lt;!&gt; c = a &lt;!&gt; (b &lt;!&gt; c)
--   &lt;$&gt; left-distributes over &lt;!&gt;:  f &lt;$&gt; (a &lt;!&gt; b) = (f &lt;$&gt; a) &lt;!&gt; (f &lt;$&gt; b)
--   </pre>
--   
--   If extended to an <a>Alternative</a> then <a>&lt;!&gt;</a> should
--   equal <a>&lt;|&gt;</a>.
--   
--   Ideally, an instance of <a>Alt</a> also satisfies the "left
--   distributon" law of MonadPlus with respect to <a>.</a>:
--   
--   <pre>
--   &lt;.&gt; right-distributes over &lt;!&gt;: (a &lt;!&gt; b) &lt;.&gt; c = (a &lt;.&gt; c) &lt;!&gt; (b &lt;.&gt; c)
--   </pre>
--   
--   But <a>Maybe</a>, <a>IO</a>, <tt><a>Either</a> a</tt>,
--   <tt><a>ErrorT</a> e m</tt>, and <tt>STM</tt> satisfy the alternative
--   "left catch" law instead:
--   
--   <pre>
--   pure a &lt;!&gt; b = pure a
--   </pre>
--   
--   However, this variation cannot be stated purely in terms of the
--   dependencies of <a>Alt</a>.
--   
--   When and if MonadPlus is successfully refactored, this class should
--   also be refactored to remove these instances.
--   
--   The right distributive law should extend in the cases where the a
--   <a>Bind</a> or <a>Monad</a> is provided to yield variations of the
--   right distributive law:
--   
--   <pre>
--   (m &lt;!&gt; n) &gt;&gt;- f = (m &gt;&gt;- f) &lt;!&gt; (m &gt;&gt;- f)
--   (m &lt;!&gt; n) &gt;&gt;= f = (m &gt;&gt;= f) &lt;!&gt; (m &gt;&gt;= f)
--   </pre>
class Functor f => Alt (f :: * -> *)
(<!>) :: Alt f => f a -> f a -> f a
some :: (Alt f, Applicative f) => f a -> f [a]
many :: (Alt f, Applicative f) => f a -> f [a]

-- | Laws:
--   
--   <pre>
--   zero &lt;!&gt; m = m
--   m &lt;!&gt; zero = m
--   </pre>
--   
--   If extended to an <a>Alternative</a> then <a>zero</a> should equal
--   <a>empty</a>.
class Alt f => Plus (f :: * -> *)
zero :: Plus f => f a