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


-- | Lift control operations, like exception catching, through monad transformers
--   
--   This package defines the type class <tt>MonadBaseControl</tt>, a
--   subset of <tt>MonadBase</tt> into which generic control operations
--   such as <tt>catch</tt> can be lifted from <tt>IO</tt> or any other
--   base monad. Instances are based on monad transformers in
--   <tt>MonadTransControl</tt>, which includes all standard monad
--   transformers in the <tt>transformers</tt> library except
--   <tt>ContT</tt>.
--   
--   See the <a>lifted-base</a> package which uses <tt>monad-control</tt>
--   to lift <tt>IO</tt> operations from the <tt>base</tt> library (like
--   <tt>catch</tt> or <tt>bracket</tt>) into any monad that is an instance
--   of <tt>MonadBase</tt> or <tt>MonadBaseControl</tt>.
--   
--   Note that this package is a rewrite of Anders Kaseorg's
--   <tt>monad-peel</tt> library. The main difference is that this package
--   provides CPS style operators and exploits the <tt>RankNTypes</tt> and
--   <tt>TypeFamilies</tt> language extensions to simplify and speedup most
--   definitions.
@package monad-control
@version 1.0.2.1


-- | This module defines the type class <a>MonadBaseControl</a>, a subset
--   of <a>MonadBase</a> into which generic control operations such as
--   <tt>catch</tt> can be lifted from <tt>IO</tt> or any other base monad.
--   Instances are based on monad transformers in <a>MonadTransControl</a>,
--   which includes all standard monad transformers in the
--   <tt>transformers</tt> library except <tt>ContT</tt>.
--   
--   See the <a>lifted-base</a> package which uses <tt>monad-control</tt>
--   to lift <tt>IO</tt> operations from the <tt>base</tt> library (like
--   <tt>catch</tt> or <tt>bracket</tt>) into any monad that is an instance
--   of <tt>MonadBase</tt> or <tt>MonadBaseControl</tt>.
--   
--   See the following tutorial by Michael Snoyman on how to use this
--   package:
--   
--   <a>https://www.yesodweb.com/book/monad-control</a>
module Control.Monad.Trans.Control
class MonadTrans t => MonadTransControl t where type StT t a :: * where {
    type family StT t a :: *;
}

-- | <tt>liftWith</tt> is similar to <tt>lift</tt> in that it lifts a
--   computation from the argument monad to the constructed monad.
--   
--   Instances should satisfy similar laws as the <a>MonadTrans</a> laws:
--   
--   <pre>
--   liftWith . const . return = return
--   </pre>
--   
--   <pre>
--   liftWith (const (m &gt;&gt;= f)) = liftWith (const m) &gt;&gt;= liftWith . const . f
--   </pre>
--   
--   The difference with <tt>lift</tt> is that before lifting the
--   <tt>m</tt> computation <tt>liftWith</tt> captures the state of
--   <tt>t</tt>. It then provides the <tt>m</tt> computation with a
--   <a>Run</a> function that allows running <tt>t n</tt> computations in
--   <tt>n</tt> (for all <tt>n</tt>) on the captured state.
liftWith :: (MonadTransControl t, Monad m) => (Run t -> m a) -> t m a

-- | Construct a <tt>t</tt> computation from the monadic state of
--   <tt>t</tt> that is returned from a <a>Run</a> function.
--   
--   Instances should satisfy:
--   
--   <pre>
--   liftWith (\run -&gt; run t) &gt;&gt;= restoreT . return = t
--   </pre>
--   
--   Example type signatures:
--   
--   <pre>
--   restoreT :: <a>Monad</a> m             =&gt; m a            -&gt; <a>IdentityT</a> m a
--   restoreT :: <a>Monad</a> m             =&gt; m (<a>Maybe</a> a)    -&gt; <a>MaybeT</a> m a
--   restoreT :: (<a>Monad</a> m, <a>Error</a> e)  =&gt; m (<a>Either</a> e a) -&gt; <a>ErrorT</a> e m a
--   restoreT :: <a>Monad</a> m             =&gt; m (<a>Either</a> e a) -&gt; <a>ExceptT</a> e m a
--   restoreT :: <a>Monad</a> m             =&gt; m [a]          -&gt; <a>ListT</a> m a
--   restoreT :: <a>Monad</a> m             =&gt; m a            -&gt; <a>ReaderT</a> r m a
--   restoreT :: <a>Monad</a> m             =&gt; m (a, s)       -&gt; <a>StateT</a> s m a
--   restoreT :: (<a>Monad</a> m, <a>Monoid</a> w) =&gt; m (a, w)       -&gt; <a>WriterT</a> w m a
--   restoreT :: (<a>Monad</a> m, <a>Monoid</a> w) =&gt; m (a, s, w)    -&gt; <a>RWST</a> r w s m a
--   </pre>
restoreT :: (MonadTransControl t, Monad m) => m (StT t a) -> t m a

-- | A function that runs a transformed monad <tt>t n</tt> on the monadic
--   state that was captured by <a>liftWith</a>
--   
--   A <tt>Run t</tt> function yields a computation in <tt>n</tt> that
--   returns the monadic state of <tt>t</tt>. This state can later be used
--   to restore a <tt>t</tt> computation using <a>restoreT</a>.
--   
--   Example type equalities:
--   
--   <pre>
--   Run <a>IdentityT</a>    ~ forall n b. <a>Monad</a> n             =&gt; <a>IdentityT</a>  n b -&gt; n b
--   Run <a>MaybeT</a>       ~ forall n b. <a>Monad</a> n             =&gt; <a>MaybeT</a>     n b -&gt; n (<a>Maybe</a> b)
--   Run (<a>ErrorT</a> e)   ~ forall n b. (<a>Monad</a> n, <a>Error</a> e)  =&gt; <a>ErrorT</a> e   n b -&gt; n (<a>Either</a> e b)
--   Run (<a>ExceptT</a> e)  ~ forall n b. <a>Monad</a> n             =&gt; <a>ExceptT</a> e  n b -&gt; n (<a>Either</a> e b)
--   Run <a>ListT</a>        ~ forall n b. <a>Monad</a> n             =&gt; <a>ListT</a>      n b -&gt; n [b]
--   Run (<a>ReaderT</a> r)  ~ forall n b. <a>Monad</a> n             =&gt; <a>ReaderT</a> r  n b -&gt; n b
--   Run (<a>StateT</a> s)   ~ forall n b. <a>Monad</a> n             =&gt; <a>StateT</a> s   n b -&gt; n (a, s)
--   Run (<a>WriterT</a> w)  ~ forall n b. (<a>Monad</a> n, <a>Monoid</a> w) =&gt; <a>WriterT</a> w  n b -&gt; n (a, w)
--   Run (<a>RWST</a> r w s) ~ forall n b. (<a>Monad</a> n, <a>Monoid</a> w) =&gt; <a>RWST</a> r w s n b -&gt; n (a, s, w)
--   </pre>
type Run t = forall n b. Monad n => t n b -> n (StT t b)

-- | A function like <a>Run</a> that runs a monad transformer <tt>t</tt>
--   which wraps the monad transformer <tt>t'</tt>. This is used in
--   <a>defaultLiftWith</a>.
type RunDefault t t' = forall n b. Monad n => t n b -> n (StT t' b)

-- | Default definition for the <a>liftWith</a> method.
defaultLiftWith :: (Monad m, MonadTransControl n) => (forall b. n m b -> t m b) -> (forall o b. t o b -> n o b) -> (RunDefault t n -> m a) -> t m a

-- | Default definition for the <a>restoreT</a> method.
defaultRestoreT :: (Monad m, MonadTransControl n) => (n m a -> t m a) -> m (StT n a) -> t m a

-- | A function like <a>Run</a> that runs a monad transformer <tt>t</tt>
--   which wraps the monad transformers <tt>n</tt> and <tt>n'</tt>. This is
--   used in <a>defaultLiftWith2</a>.
type RunDefault2 t n n' = forall m b. (Monad m, Monad (n' m)) => t m b -> m (StT n' (StT n b))

-- | Default definition for the <a>liftWith</a> method.
defaultLiftWith2 :: (Monad m, Monad (n' m), MonadTransControl n, MonadTransControl n') => (forall b. n (n' m) b -> t m b) -> (forall o b. t o b -> n (n' o) b) -> (RunDefault2 t n n' -> m a) -> t m a

-- | Default definition for the <a>restoreT</a> method for double
--   <a>MonadTransControl</a>.
defaultRestoreT2 :: (Monad m, Monad (n' m), MonadTransControl n, MonadTransControl n') => (n (n' m) a -> t m a) -> m (StT n' (StT n a)) -> t m a
class MonadBase b m => MonadBaseControl b m | m -> b where type StM m a :: * where {
    type family StM m a :: *;
}

-- | <tt>liftBaseWith</tt> is similar to <tt>liftIO</tt> and
--   <tt>liftBase</tt> in that it lifts a base computation to the
--   constructed monad.
--   
--   Instances should satisfy similar laws as the <tt>MonadIO</tt> and
--   <a>MonadBase</a> laws:
--   
--   <pre>
--   liftBaseWith . const . return = return
--   </pre>
--   
--   <pre>
--   liftBaseWith (const (m &gt;&gt;= f)) = liftBaseWith (const m) &gt;&gt;= liftBaseWith . const . f
--   </pre>
--   
--   The difference with <tt>liftBase</tt> is that before lifting the base
--   computation <tt>liftBaseWith</tt> captures the state of <tt>m</tt>. It
--   then provides the base computation with a <a>RunInBase</a> function
--   that allows running <tt>m</tt> computations in the base monad on the
--   captured state.
liftBaseWith :: MonadBaseControl b m => (RunInBase m b -> b a) -> m a

-- | Construct a <tt>m</tt> computation from the monadic state of
--   <tt>m</tt> that is returned from a <a>RunInBase</a> function.
--   
--   Instances should satisfy:
--   
--   <pre>
--   liftBaseWith (\runInBase -&gt; runInBase m) &gt;&gt;= restoreM = m
--   </pre>
restoreM :: MonadBaseControl b m => StM m a -> m a

-- | A function that runs a <tt>m</tt> computation on the monadic state
--   that was captured by <a>liftBaseWith</a>
--   
--   A <tt>RunInBase m</tt> function yields a computation in the base monad
--   of <tt>m</tt> that returns the monadic state of <tt>m</tt>. This state
--   can later be used to restore the <tt>m</tt> computation using
--   <a>restoreM</a>.
--   
--   Example type equalities:
--   
--   <pre>
--   RunInBase (<a>IdentityT</a>  m) b ~ forall a.             <a>IdentityT</a>  m a -&gt; b (<a>StM</a> m a)
--   RunInBase (<a>MaybeT</a>     m) b ~ forall a.             <a>MaybeT</a>     m a -&gt; b (<a>StM</a> m (<a>Maybe</a> a))
--   RunInBase (<a>ErrorT</a> e   m) b ~ forall a. <a>Error</a> e =&gt;  <a>ErrorT</a> e   m a -&gt; b (<a>StM</a> m (<a>Either</a> e a))
--   RunInBase (<a>ExceptT</a> e  m) b ~ forall a.             <a>ExceptT</a> e  m a -&gt; b (<a>StM</a> m (<a>Either</a> e a))
--   RunInBase (<a>ListT</a>      m) b ~ forall a.             <a>ListT</a>      m a -&gt; b (<a>StM</a> m [a])
--   RunInBase (<a>ReaderT</a> r  m) b ~ forall a.             <a>ReaderT</a>    m a -&gt; b (<a>StM</a> m a)
--   RunInBase (<a>StateT</a> s   m) b ~ forall a.             <a>StateT</a> s   m a -&gt; b (<a>StM</a> m (a, s))
--   RunInBase (<a>WriterT</a> w  m) b ~ forall a. <a>Monoid</a> w =&gt; <a>WriterT</a> w  m a -&gt; b (<a>StM</a> m (a, w))
--   RunInBase (<a>RWST</a> r w s m) b ~ forall a. <a>Monoid</a> w =&gt; <a>RWST</a> r w s m a -&gt; b (<a>StM</a> m (a, s, w))
--   </pre>
type RunInBase m b = forall a. m a -> b (StM m a)

-- | Handy type synonym that composes the monadic states of <tt>t</tt> and
--   <tt>m</tt>.
--   
--   It can be used to define the <a>StM</a> for new
--   <a>MonadBaseControl</a> instances.
type ComposeSt t m a = StM m (StT t a)

-- | A function like <a>RunInBase</a> that runs a monad transformer
--   <tt>t</tt> in its base monad <tt>b</tt>. It is used in
--   <a>defaultLiftBaseWith</a>.
type RunInBaseDefault t m b = forall a. t m a -> b (ComposeSt t m a)

-- | Default defintion for the <a>liftBaseWith</a> method.
--   
--   Note that it composes a <a>liftWith</a> of <tt>t</tt> with a
--   <a>liftBaseWith</a> of <tt>m</tt> to give a <a>liftBaseWith</a> of
--   <tt>t m</tt>:
--   
--   <pre>
--   defaultLiftBaseWith = \f -&gt; <a>liftWith</a> $ \run -&gt;
--                                 <a>liftBaseWith</a> $ \runInBase -&gt;
--                                   f $ runInBase . run
--   </pre>
defaultLiftBaseWith :: (MonadTransControl t, MonadBaseControl b m) => (RunInBaseDefault t m b -> b a) -> t m a

-- | Default definition for the <a>restoreM</a> method.
--   
--   Note that: <tt>defaultRestoreM = <a>restoreT</a> .
--   <a>restoreM</a></tt>
defaultRestoreM :: (MonadTransControl t, MonadBaseControl b m) => ComposeSt t m a -> t m a

-- | An often used composition: <tt>control f = <a>liftBaseWith</a> f
--   &gt;&gt;= <a>restoreM</a></tt>
control :: MonadBaseControl b m => (RunInBase m b -> b (StM m a)) -> m a

-- | Embed a transformer function as an function in the base monad
--   returning a mutated transformer state.
embed :: MonadBaseControl b m => (a -> m c) -> m (a -> b (StM m c))

-- | Performs the same function as <a>embed</a>, but discards transformer
--   state from the embedded function.
embed_ :: MonadBaseControl b m => (a -> m ()) -> m (a -> b ())

-- | Capture the current state of a transformer
captureT :: (MonadTransControl t, Monad (t m), Monad m) => t m (StT t ())

-- | Capture the current state above the base monad
captureM :: MonadBaseControl b m => m (StM m ())

-- | <tt>liftBaseOp</tt> is a particular application of <a>liftBaseWith</a>
--   that allows lifting control operations of type:
--   
--   <tt>((a -&gt; b c) -&gt; b c)</tt> to: <tt>(<a>MonadBaseControl</a> b
--   m =&gt; (a -&gt; m c) -&gt; m c)</tt>.
--   
--   For example:
--   
--   <pre>
--   liftBaseOp alloca :: <a>MonadBaseControl</a> <a>IO</a> m =&gt; (Ptr a -&gt; m c) -&gt; m c
--   </pre>
liftBaseOp :: MonadBaseControl b m => ((a -> b (StM m c)) -> b (StM m d)) -> ((a -> m c) -> m d)

-- | <tt>liftBaseOp_</tt> is a particular application of
--   <a>liftBaseWith</a> that allows lifting control operations of type:
--   
--   <tt>(b a -&gt; b a)</tt> to: <tt>(<a>MonadBaseControl</a> b m =&gt; m
--   a -&gt; m a)</tt>.
--   
--   For example:
--   
--   <pre>
--   liftBaseOp_ mask_ :: <a>MonadBaseControl</a> <a>IO</a> m =&gt; m a -&gt; m a
--   </pre>
liftBaseOp_ :: MonadBaseControl b m => (b (StM m a) -> b (StM m c)) -> (m a -> m c)

-- | <tt>liftBaseDiscard</tt> is a particular application of
--   <a>liftBaseWith</a> that allows lifting control operations of type:
--   
--   <tt>(b () -&gt; b a)</tt> to: <tt>(<a>MonadBaseControl</a> b m =&gt; m
--   () -&gt; m a)</tt>.
--   
--   Note that, while the argument computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in the base monad <tt>b</tt>.
--   
--   For example:
--   
--   <pre>
--   liftBaseDiscard forkIO :: <a>MonadBaseControl</a> <a>IO</a> m =&gt; m () -&gt; m ThreadId
--   </pre>
liftBaseDiscard :: MonadBaseControl b m => (b () -> b a) -> (m () -> m a)

-- | <tt>liftBaseOpDiscard</tt> is a particular application of
--   <a>liftBaseWith</a> that allows lifting control operations of type:
--   
--   <tt>((a -&gt; b ()) -&gt; b c)</tt> to: <tt>(<a>MonadBaseControl</a> b
--   m =&gt; (a -&gt; m ()) -&gt; m c)</tt>.
--   
--   Note that, while the argument computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in the base monad <tt>b</tt>.
--   
--   For example:
--   
--   <pre>
--   liftBaseDiscard (runServer addr port) :: <a>MonadBaseControl</a> <a>IO</a> m =&gt; m () -&gt; m ()
--   </pre>
liftBaseOpDiscard :: MonadBaseControl b m => ((a -> b ()) -> b c) -> (a -> m ()) -> m c

-- | Transform an action in <tt>t m</tt> using a transformer that operates
--   on the underlying monad <tt>m</tt>
liftThrough :: (MonadTransControl t, Monad (t m), Monad m) => (m (StT t a) -> m (StT t b)) -> t m a -> t m b
instance Control.Monad.Trans.Control.MonadTransControl Control.Monad.Trans.Identity.IdentityT
instance Control.Monad.Trans.Control.MonadTransControl Control.Monad.Trans.Maybe.MaybeT
instance Control.Monad.Trans.Error.Error e => Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.Error.ErrorT e)
instance Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.Except.ExceptT e)
instance Control.Monad.Trans.Control.MonadTransControl Control.Monad.Trans.List.ListT
instance Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.Reader.ReaderT r)
instance Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.State.Lazy.StateT s)
instance Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.State.Strict.StateT s)
instance GHC.Base.Monoid w => Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.Writer.Lazy.WriterT w)
instance GHC.Base.Monoid w => Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.Writer.Strict.WriterT w)
instance GHC.Base.Monoid w => Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.RWS.Lazy.RWST r w s)
instance GHC.Base.Monoid w => Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Trans.RWS.Strict.RWST r w s)
instance Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO GHC.Types.IO
instance Control.Monad.Trans.Control.MonadBaseControl GHC.Base.Maybe GHC.Base.Maybe
instance Control.Monad.Trans.Control.MonadBaseControl (Data.Either.Either e) (Data.Either.Either e)
instance Control.Monad.Trans.Control.MonadBaseControl [] []
instance Control.Monad.Trans.Control.MonadBaseControl ((->) r) ((->) r)
instance Control.Monad.Trans.Control.MonadBaseControl Data.Functor.Identity.Identity Data.Functor.Identity.Identity
instance Control.Monad.Trans.Control.MonadBaseControl GHC.Conc.Sync.STM GHC.Conc.Sync.STM
instance Control.Monad.Trans.Control.MonadBaseControl (GHC.ST.ST s) (GHC.ST.ST s)
instance Control.Monad.Trans.Control.MonadBaseControl (Control.Monad.ST.Lazy.Imp.ST s) (Control.Monad.ST.Lazy.Imp.ST s)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Except.ExceptT e m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Trans.Control.MonadBaseControl b m) => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Error.ErrorT e m)
instance (GHC.Base.Monoid w, Control.Monad.Trans.Control.MonadBaseControl b m) => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Trans.Control.MonadBaseControl b m) => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Trans.Control.MonadBaseControl b m) => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Trans.Control.MonadBaseControl b m) => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
