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


-- | Parameterized monads
--   
--   Implements parameterized monads by overloading the monad sugar with
--   more liberal types.
@package monad-param
@version 0.0.2


-- | Implements a notion of parameterized monad by varying the monad
--   itself, this lets us avoid having to carry a parameter around for
--   monads that do not need it, and we can rederive the normal notion of a
--   parameterized monad from this variation for those that do. The
--   signature of <a>&gt;&gt;=</a> costs us type inference for the types of
--   <a>return</a> and <a>mzero</a>, so we restore that by defining
--   <a>return</a> as the unit of the <a>Identity</a> monad and
--   <a>mzero</a> as the unit of the trivial bottom monad, and appealing to
--   the monad laws to allow these to combine with all other monads
--   satisfying the monad laws through <a>&gt;&gt;=</a>
--   
--   Caveat: this currently does not permit types to vary under the
--   <tt>do</tt>-sugar because of assumptions in GHC about the shape of
--   <a>&gt;&gt;=</a>.
--   
--   This imports and defines the correct instances for a good portion of
--   the <tt>MTL</tt>, primarily because it is so awkward to import them
--   all otherwise due to the fact that most of them re-export the
--   <tt>Control.Monad.Monad</tt> syntax. Does not export
--   <a>Control.Monad.ST</a> or <a>Control.Monad.Writer</a> since it is
--   unclear if you want strict or lazy versions in scope
module Control.Monad.Parameterized

-- | The traditional <a>return</a>, note this probably has lost its type
--   inference where you want to use it.
class Return m
returnM :: (Return m) => a -> m a

-- | Restrict the cases where we allow pattern matching to <a>fail</a>. You
--   have to explicitly supply this for your <a>Monad</a>
class Fail m
fail :: (Fail m) => String -> m a

-- | Implement parameterized monads like Oleg's restricted monads, but vary
--   the monad itself rather than restrict its parameters
class (Functor m, Functor m', Functor m'') => Bind m m' m'' | m m' -> m''
(>>=) :: (Bind m m' m'') => m a -> (a -> m' b) -> (m'' b)
(>>) :: (Bind m m' m'') => m a -> m' b -> m'' b
(=<<) :: (Bind m m' m'') => (a -> m' b) -> m a -> m'' b

-- | Break out mplus
class MPlus m m' m'' | m m' -> m''
mplus :: (MPlus m m' m'') => m a -> m' a -> m'' a

-- | Traditional <tt>Control.Monad.mzero</tt>, note this probably has lost
--   its type inference. You probably want <a>mzero</a>.
class MonadZero m
mzeroM :: (MonadZero m) => m a

-- | Same trick using with <a>Identity</a> to build a canonical
--   <a>return</a>, here we exploit the <a>MonadPlus</a> laws to make a
--   canonical <a>mzero</a>. Has no members except bottom.
data MZero a

-- | When a parameterized monad can be used without varying its parameter,
--   we can get the ease of use of the original <tt>Monad</tt> class.
class (Fail m, Return m, Bind m m m) => Monad m

-- | Class alias to get back an approximation of the original,
--   easy-to-specify <a>MonadPlus</a> class where available
class (MPlus m m m, MonadZero m) => MonadPlus m

-- | Now of course we can have <a>MZero</a>s and <a>Identity</a>s float to
--   the top of a <tt>do</tt> expression, so we need a way to convert them
--   to any <a>Monad</a> or <a>MonadPlus</a> instance respectively
class Go n m
go :: (Go n m) => n a -> m a

-- | An inferable version of <tt>Prelude.return</tt>
return :: a -> Identity a

-- | An inferable version of <tt>Control.Monad.mzero</tt>
mzero :: MZero a

-- | <tt><a>mapM</a> f</tt> is equivalent to <tt><a>sequence</a> .
--   <a>map</a> f</tt>.
mapM :: (Monad m) => (a -> m b) -> [a] -> m [b]

-- | <tt><a>mapM_</a> f</tt> is equivalent to <tt><a>sequence_</a> .
--   <a>map</a> f</tt>.
mapM_ :: (Monad m) => (a -> m b) -> [a] -> m ()

-- | <a>forM</a> is <a>mapM</a> with its arguments flipped
forM :: (Monad m) => [a] -> (a -> m b) -> m [b]

-- | <a>forM_</a> is <a>mapM_</a> with its arguments flipped
forM_ :: (Monad m) => [a] -> (a -> m b) -> m ()

-- | Evaluate each action in the sequence from left to right, and collect
--   the results.
sequence :: (Monad m) => [m a] -> m [a]

-- | Evaluate each action in the sequence from left to right, and ignore
--   the results.
sequence_ :: (Monad m) => [m a] -> m ()

-- | The <a>join</a> function is the conventional monad join operator. It
--   is used to remove one level of monadic structure, projecting its bound
--   argument into the outer level.
join :: (Monad m) => m (m a) -> m a

-- | This generalizes the list-based <a>concat</a> function.
msum :: (MonadPlus m) => [m a] -> m a

-- | This generalizes the list-based <a>filter</a> function.
filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]

-- | The <a>mapAndUnzipM</a> function maps its first argument over a list,
--   returning the result as a pair of lists. This function is mainly used
--   with complicated data structures or a state-transforming monad.
mapAndUnzipM :: (Monad m) => (a -> m (b, c)) -> [a] -> m ([b], [c])

-- | The <a>zipWithM</a> function generalizes <a>zipWith</a> to arbitrary
--   monads.
zipWithM :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]

-- | <a>zipWithM_</a> is the extension of <a>zipWithM</a> which ignores the
--   final result.
zipWithM_ :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()

-- | The <a>foldM</a> function is analogous to <a>foldl</a>, except that
--   its result is encapsulated in a monad. Note that <a>foldM</a> works
--   from left-to-right over the list arguments. This could be an issue
--   where '(&gt;&gt;)' and the `folded function' are not commutative.
--   
--   <tt> foldM f a1 [x1, x2, ..., xm ] </tt>
--   
--   ==
--   
--   <tt> do a2 &lt;- f a1 x1 a3 &lt;- f a2 x2 ... f am xm </tt>
--   
--   If right-to-left evaluation is required, the input list should be
--   reversed.
foldM :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a

-- | Like <a>foldM</a>, but discards the result.
foldM_ :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m ()

-- | <tt><a>replicateM</a> n act</tt> performs the action <tt>n</tt> times,
--   gathering the results.
replicateM :: (Monad m) => Int -> m a -> m [a]

-- | Like <a>replicateM</a>, but discards the result.
replicateM_ :: (Monad m) => Int -> m a -> m ()

-- | <tt><a>guard</a> b</tt> is <tt><a>return</a> ()</tt> if <tt>b</tt> is
--   <a>True</a>, and <a>mzero</a> if <tt>b</tt> is <a>False</a>.
guard :: (MonadPlus m) => Bool -> m ()

-- | Conditional execution of monadic expressions. For example,
--   
--   <tt> when debug (putStr "Debugging\n") </tt>
--   
--   will output the string <tt>Debugging\n</tt> if the Boolean value
--   <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: (Monad m) => Bool -> m () -> m ()

-- | The reverse of <a>when</a>.
unless :: (Monad m) => Bool -> m () -> m ()

-- | Promote a function to a monad.
liftM :: (Monad m) => (a1 -> r) -> m a1 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right. For example,
--   
--   <tt> liftM2 (+) [0,1] [0,2] = [0,2,1,3] liftM2 (+) (Just 1) Nothing =
--   Nothing </tt>
liftM2 :: (Monad m) => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM3 :: (Monad m) => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM4 :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM5 :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r

-- | In many situations, the <a>liftM</a> operations can be replaced by
--   uses of <a>ap</a>, which promotes function application.
--   
--   <tt> return f `ap` x1 `ap` ... `ap` xn </tt>
--   
--   is equivalent to
--   
--   <tt> liftMn f x1 x2 ... xn </tt>
ap :: (Monad m) => m (a -> b) -> m a -> m b
instance [overlap ok] Bind [] IO (ListT IO)
instance [overlap ok] Bind IO STM IO
instance [overlap ok] Bind STM IO IO
instance [overlap ok] Bind [] Maybe []
instance [overlap ok] Bind Maybe [] []
instance [overlap ok] (Monad m) => Bind (ContT r m) (ContT r m) (ContT r m)
instance [overlap ok] (Monad m) => Fail (ContT r m)
instance [overlap ok] (Monad m) => Return (ContT r m)
instance [overlap ok] (Monad m, Error e) => MPlus (ErrorT e m) (ErrorT e m) (ErrorT e m)
instance [overlap ok] (Monad m, Error e) => MonadZero (ErrorT e m)
instance [overlap ok] (Monad m, Error e) => Bind (ErrorT e m) (ErrorT e m) (ErrorT e m)
instance [overlap ok] (Monad m, Error e) => Fail (ErrorT e m)
instance [overlap ok] (Monad m, Error e) => Return (ErrorT e m)
instance [overlap ok] (Monad m, Monoid w) => Bind (WriterT w m) (WriterT w m) (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => Fail (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => Return (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => Bind (WriterT w m) (WriterT w m) (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => Fail (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => Return (WriterT w m)
instance [overlap ok] (Monad m) => Bind (ReaderT e m) (ReaderT e m) (ReaderT e m)
instance [overlap ok] (Monad m) => Fail (ReaderT e m)
instance [overlap ok] (Monad m) => Return (ReaderT e m)
instance [overlap ok] (Monad m) => Bind (StateT s m) (StateT s m) (StateT s m)
instance [overlap ok] (Monad m) => Fail (StateT s m)
instance [overlap ok] (Monad m) => Return (StateT s m)
instance [overlap ok] (Monad m) => MPlus (ListT m) (ListT m) (ListT m)
instance [overlap ok] (Monad m) => MonadZero (ListT m)
instance [overlap ok] (Monad m) => Bind (ListT m) (ListT m) (ListT m)
instance [overlap ok] (Monad m) => Fail (ListT m)
instance [overlap ok] (Monad m) => Return (ListT m)
instance [overlap ok] (Monoid w) => Bind (Writer w) (Writer w) (Writer w)
instance [overlap ok] (Monoid w) => Fail (Writer w)
instance [overlap ok] (Monoid w) => Return (Writer w)
instance [overlap ok] (Monoid w) => Bind (Writer w) (Writer w) (Writer w)
instance [overlap ok] (Monoid w) => Fail (Writer w)
instance [overlap ok] (Monoid w) => Return (Writer w)
instance [overlap ok] Bind (ST s) (ST s) (ST s)
instance [overlap ok] Fail (ST s)
instance [overlap ok] Return (ST s)
instance [overlap ok] Bind (ST s) (ST s) (ST s)
instance [overlap ok] Fail (ST s)
instance [overlap ok] Return (ST s)
instance [overlap ok] Bind (Cont r) (Cont r) (Cont r)
instance [overlap ok] Fail (Cont r)
instance [overlap ok] Return (Cont r)
instance [overlap ok] Bind (Reader e) (Reader e) (Reader e)
instance [overlap ok] Fail (Reader e)
instance [overlap ok] Return (Reader e)
instance [overlap ok] Bind (State s) (State s) (State s)
instance [overlap ok] Fail (State s)
instance [overlap ok] Return (State s)
instance [overlap ok] Bind IO IO IO
instance [overlap ok] Fail IO
instance [overlap ok] Return IO
instance [overlap ok] Bind STM STM STM
instance [overlap ok] Fail STM
instance [overlap ok] Return STM
instance [overlap ok] MPlus [] [] []
instance [overlap ok] MonadZero []
instance [overlap ok] Bind [] [] []
instance [overlap ok] Fail []
instance [overlap ok] Return []
instance [overlap ok] MPlus Maybe Maybe Maybe
instance [overlap ok] MonadZero Maybe
instance [overlap ok] Bind Maybe Maybe Maybe
instance [overlap ok] Fail Maybe
instance [overlap ok] Return Maybe
instance [overlap ok] (MPlus m m m, MonadZero m) => MonadPlus m
instance [overlap ok] Return MZero
instance [overlap ok] Return Identity
instance [overlap ok] Go a a
instance [overlap ok] (MonadZero a) => Go MZero a
instance [overlap ok] (Return a) => Go Identity a
instance [overlap ok] Bind MZero Identity MZero
instance [overlap ok] Bind Identity MZero MZero
instance [overlap ok] Bind MZero MZero MZero
instance [overlap ok] (Functor a) => Bind a MZero MZero
instance [overlap ok] (Functor a) => Bind MZero a MZero
instance [overlap ok] MPlus MZero MZero MZero
instance [overlap ok] MPlus a MZero a
instance [overlap ok] MPlus MZero a a
instance [overlap ok] Functor MZero
instance [overlap ok] (Fail m, Return m, Bind m m m) => Monad m
instance [overlap ok] Bind Identity Identity Identity
instance [overlap ok] (Functor a) => Bind a Identity a
instance [overlap ok] (Functor a) => Bind Identity a a