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


-- | Extra utility functions for working with monads
--   
--   Extra utility functions for working with monads
@package monad-extras
@version 0.6.0

module Control.Monad.Extra

-- | Synonym for <tt>return ()</tt>.
skip :: Monad m => m ()

-- | Discards a value
discard :: Monad m => a -> m ()

-- | Synonym for <tt>pure ()</tt>.
obvious :: Applicative f => f ()

-- | Function name for <a>&gt;&gt;=</a>, as <a>fmap</a> is to
--   <a>&lt;$&gt;</a>.
bind :: Monad m => m a -> (a -> m b) -> m b

-- | Combinator for working with monadic values:
--   
--   <pre>
--   &gt;&gt;&gt; om when (return True) $ print "Hello"
--   "Hello"
--   
--   &gt;&gt;&gt; return True &gt;&gt;= flip when (print "Hello")
--   "Hello"
--   
--   &gt;&gt;&gt; om forM_ (return [True]) print
--   True
--   
--   &gt;&gt;&gt; flip forM_ print =&lt;&lt; return [True]
--   True
--   
--   &gt;&gt;&gt; mapM_ print =&lt;&lt; return [True]
--   True
--   </pre>
--   
--   Subsumes the need for individual functions for <tt>whenM</tt>,
--   <tt>unlessM</tt>, etc.
om :: Monad m => (a -> b -> m c) -> m a -> b -> m c

-- | Variant of <a>om</a> which changes the roles of the 2nd and 3rd
--   arguments.
--   
--   <pre>
--   &gt;&gt;&gt; nom mapM_ print $ return [True]
--   True
--   
--   &gt;&gt;&gt; mapM_ print =&lt;&lt; return [True]
--   True
--   </pre>
nom :: Monad m => (a -> b -> m c) -> a -> m b -> m c

-- | Convenience function if all you want to use is <a>callCC</a>.
doCallCC :: Monad m => ((r -> ContT r m b) -> ContT r m r) -> m r

-- | Return a continuation that one can jump back to within <a>ContT</a>.
--   
--   <pre>
--   &gt;&gt;&gt; flip runContT return $ do { k &lt;- label; ...; k }
--   </pre>
label :: ContT r m (ContT r m a)

-- | Short-hand for <tt>liftIO</tt>.
io :: MonadIO m => IO a -> m a

-- | Lift a <a>Maybe</a> value into the <tt>MaybeT</tt> monad transformer.
liftMaybe :: MonadPlus m => Maybe a -> m a

-- | A monadic version of <tt>mapMaybe :: (a -&gt; Maybe b) -&gt; [a] -&gt;
--   [b]</tt>.
mapMaybeM :: (Monad m, Functor m) => (a -> m (Maybe b)) -> [a] -> m [b]

-- | A transformer-friendly version of <a>atomically</a>.
atomicallyM :: MonadIO m => STM a -> m a

-- | Embed a transformer (Kleisli) arrow as an arrow in the base monad
--   returning a mutated transformer state. If you do not want the
--   transformation and your base monad is IO, use <a>embedIO</a>.
embed :: (MonadBaseControl base m) => (a -> m b) -> m (a -> base (StM m b))

-- | Return an IO action that closes over the current monad transformer,
--   but throws away any residual effects within that transformer.
embedIO :: (MonadBaseControl IO m, MonadIO m) => (a -> m b) -> m (a -> IO b)
embedIO2 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> m r) -> m (a -> b -> IO r)
embedIO3 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> m r) -> m (a -> b -> c -> IO r)
embedIO4 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> d -> m r) -> m (a -> b -> c -> d -> IO r)
embedIO5 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> d -> e -> m r) -> m (a -> b -> c -> d -> e -> IO r)
embedIO6 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> d -> e -> f -> m r) -> m (a -> b -> c -> d -> e -> f -> IO r)
embedIO7 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> d -> e -> f -> g -> m r) -> m (a -> b -> c -> d -> e -> f -> g -> IO r)
embedIO8 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> d -> e -> f -> g -> h -> m r) -> m (a -> b -> c -> d -> e -> f -> g -> h -> IO r)
embedIO9 :: (MonadBaseControl IO m, MonadIO m) => (a -> b -> c -> d -> e -> f -> g -> h -> i -> m r) -> m (a -> b -> c -> d -> e -> f -> g -> h -> i -> IO r)

-- | Draw monadic actions from a list until one of them yields a value
--   satisfying the predicate, and then return all the values up to and
--   including the first that succeeds in a list within that monad.
sequenceUntil :: Monad m => (a -> Bool) -> [m a] -> m [a]

-- | Draw monadic actions from a list until one of them yields a value
--   failing the predicate, and then return all the passing values
--   (discarding the final, failing value) in a list within that monad.
sequenceWhile :: Monad m => (a -> Bool) -> [m a] -> m [a]

-- | Monadic equivalent to <a>iterate</a>. Note that it will not terminate,
--   but may still be useful in the main event loop of a program, for
--   example.
iterateM :: Monad m => (a -> m a) -> a -> m [a]

-- | Monadic equivalent to <a>iterate</a>, which uses Maybe to know when to
--   terminate.
iterateMaybeM :: Monad m => (a -> m (Maybe a)) -> a -> m [a]

-- | A monadic unfold.
unfoldM :: Monad m => (s -> m (Maybe (a, s))) -> s -> m [a]

-- | A monadic unfold which does not interact with the result. The only
--   action this function provides therefore is to iterate through the
--   values in <tt>s</tt> and produce side-effects in IO.
unfoldM_ :: Monad m => (s -> m (Maybe s)) -> s -> m ()

-- | A monadic unfold.
unfoldMapM :: (Monad m, Monoid a) => (s -> m (Maybe (a, s))) -> s -> m a
fold1M :: Monad m => (a -> a -> m a) -> [a] -> m a

-- | Assuming the function passed in is associative, divide up the work
--   binary tree-wise.
assocFoldl1 :: (a -> a -> a) -> [a] -> a

-- | Assuming the function passed in is associative, divide up the work
--   binary tree-wise.
assocFoldl1M :: Monad m => (a -> a -> m a) -> [a] -> m a
