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


-- | Monad morphisms
--   
--   This library provides monad morphism utilities, most commonly used for
--   manipulating monad transformer stacks.
@package mmorph
@version 1.0.0


-- | A monad morphism is a natural transformation:
--   
--   <pre>
--   morph :: forall a . m a -&gt; n a
--   </pre>
--   
--   ... that obeys the following two laws:
--   
--   <pre>
--   morph $ do x &lt;- m  =  do x &lt;- morph m
--              f x           morph (f x)
--   
--   morph (return x) = return x
--   </pre>
--   
--   ... which are equivalent to the following two functor laws:
--   
--   <pre>
--   morph . (f &gt;=&gt; g) = morph . f &gt;=&gt; morph . g
--   
--   morph . return = return
--   </pre>
--   
--   Examples of monad morphisms include:
--   
--   <ul>
--   <li><a>lift</a> (from <a>MonadTrans</a>)</li>
--   <li><a>squash</a> (See below)</li>
--   <li><tt><a>hoist</a> f</tt> (See below), if <tt>f</tt> is a monad
--   morphism</li>
--   <li><tt>(f . g)</tt>, if <tt>f</tt> and <tt>g</tt> are both monad
--   morphisms</li>
--   <li><a>id</a></li>
--   </ul>
--   
--   Monad morphisms commonly arise when manipulating existing monad
--   transformer code for compatibility purposes. The <a>MFunctor</a>,
--   <a>MonadTrans</a>, and <a>MMonad</a> classes define standard ways to
--   change monad transformer stacks:
--   
--   <ul>
--   <li><a>lift</a> introduces a new monad transformer layer of any
--   type.</li>
--   <li><a>squash</a> flattens two identical monad transformer layers into
--   a single layer of the same type.</li>
--   <li><a>hoist</a> maps monad morphisms to modify deeper layers of the
--   monad transformer stack.</li>
--   </ul>
module Control.Monad.Morph

-- | A functor in the category of monads, using <a>hoist</a> as the analog
--   of <a>fmap</a>:
--   
--   <pre>
--   hoist (f . g) = hoist f . hoist g
--   
--   hoist id = id
--   </pre>
class MFunctor t
hoist :: (MFunctor t, Monad m) => (forall a. m a -> n a) -> t m b -> t n b

-- | A monad in the category of monads, using <a>lift</a> from
--   <a>MonadTrans</a> as the analog of <a>return</a> and <a>embed</a> as
--   the analog of (<a>=&lt;&lt;</a>):
--   
--   <pre>
--   embed lift = id
--   
--   embed f (lift m) = f m
--   
--   embed g (embed f t) = embed (\m -&gt; embed g (f m)) t
--   </pre>
class (MFunctor t, MonadTrans t) => MMonad t
embed :: (MMonad t, Monad n) => (forall a. m a -> t n a) -> t m b -> t n b

-- | The class of monad transformers. Instances should satisfy the
--   following laws, which state that <a>lift</a> is a transformer of
--   monads:
--   
--   <ul>
--   <li><pre><a>lift</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>lift</a> (m &gt;&gt;= f) = <a>lift</a> m &gt;&gt;=
--   (<a>lift</a> . f)</pre></li>
--   </ul>
class MonadTrans (t :: (* -> *) -> * -> *)
lift :: (MonadTrans t, Monad m) => m a -> t m a

-- | Squash two <a>MMonad</a> layers into a single layer
--   
--   <a>squash</a> is analogous to <a>join</a>
squash :: (Monad m, MMonad t) => t (t m) a -> t m a

-- | Compose two <a>MMonad</a> layer-building functions
--   
--   (<a>&gt;|&gt;</a>) is analogous to (<a>&gt;=&gt;</a>)
(>|>) :: (Monad m3, MMonad t) => (forall a. m1 a -> t m2 a) -> (forall b. m2 b -> t m3 b) -> m1 c -> t m3 c

-- | Equivalent to (<a>&gt;|&gt;</a>) with the arguments flipped
--   
--   (<a>&lt;|&lt;</a>) is analogous to (<a>&lt;=&lt;</a>)
(<|<) :: (Monad m3, MMonad t) => (forall b. m2 b -> t m3 b) -> (forall a. m1 a -> t m2 a) -> m1 c -> t m3 c

-- | An infix operator equivalent to <a>embed</a>
--   
--   (<a>=&lt;|</a>) is analogous to (<a>=&lt;&lt;</a>)
(=<|) :: (Monad n, MMonad t) => (forall a. m a -> t n a) -> t m b -> t n b

-- | Equivalent to (<a>=&lt;|</a>) with the arguments flipped
--   
--   (<a>|&gt;=</a>) is analogous to (<a>&gt;&gt;=</a>)
(|>=) :: (Monad n, MMonad t) => t m b -> (forall a. m a -> t n a) -> t n b
instance Monoid w => MMonad (WriterT w)
instance Monoid w => MMonad (WriterT w)
instance MMonad (ReaderT r)
instance MMonad MaybeT
instance MMonad IdentityT
instance Error e => MMonad (ErrorT e)
instance MFunctor (WriterT w)
instance MFunctor (WriterT w)
instance MFunctor (StateT s)
instance MFunctor (StateT s)
instance MFunctor (RWST r w s)
instance MFunctor (RWST r w s)
instance MFunctor (ReaderT r)
instance MFunctor MaybeT
instance MFunctor IdentityT
instance MFunctor (ErrorT e)