-- 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 <tt>lifted-base</tt> 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.1.0


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