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


-- | Simple monad transformer for imperative-style loops
--   
--   A library of looping constructs with <tt>continue</tt> and
--   <tt>exit</tt> control flow statements.
@package control-monad-loop
@version 0.1


module Control.Monad.Trans.Loop

-- | <a>LoopT</a> is a monad transformer for the loop body. It provides two
--   capabilities:
--   
--   <ul>
--   <li><a>continue</a> to the next iteration.</li>
--   <li><a>exit</a> the whole loop.</li>
--   </ul>
newtype LoopT c e m a
LoopT :: (forall r. (c -> m r) -> (e -> m r) -> (a -> m r) -> m r) -> LoopT c e m a
runLoopT :: LoopT c e m a -> forall r. (c -> m r) -> (e -> m r) -> (a -> m r) -> m r

-- | Call a loop body, passing it a continuation for the next iteration.
--   This can be used to construct custom looping constructs. For example,
--   here is the definition of <a>foreach</a>:
--   
--   <pre>
--   foreach list body = loop list
--     where loop []     = return ()
--           loop (x:xs) = stepLoopT (body x) (\_ -&gt; loop xs)
--   </pre>
stepLoopT :: Monad m => LoopT c e m c -> (c -> m e) -> m e

-- | Skip the rest of the loop body and go to the next iteration.
continue :: LoopT () e m a

-- | Break out of the loop entirely.
exit :: LoopT c () m a

-- | Like <a>continue</a>, but return a value from the loop body.
continueWith :: c -> LoopT c e m a

-- | Like <a>exit</a>, but return a value from the loop as a whole. See the
--   documentation of <a>iterateLoopT</a> for an example.
exitWith :: e -> LoopT c e m a

-- | Call the loop body with each item in the list.
--   
--   If you do not need to <a>continue</a> or <a>exit</a> the loop,
--   consider using <a>forM_</a> instead.
foreach :: Monad m => [a] -> (a -> LoopT c () m c) -> m ()

-- | Repeat the loop body while the predicate holds. Like a <tt>while</tt>
--   loop in C, the condition is tested first.
while :: Monad m => m Bool -> LoopT c () m c -> m ()

-- | Like a <tt>do while</tt> loop in C, where the condition is tested
--   after the loop body.
--   
--   <a>doWhile</a> returns the result of the last iteration. This is
--   possible because, unlike <a>foreach</a> and <a>while</a>, the loop
--   body is guaranteed to be executed at least once.
doWhile :: Monad m => LoopT a a m a -> m Bool -> m a

-- | Execute the loop body once. This is a convenient way to introduce
--   early exit support to a block of code.
--   
--   <a>continue</a> and <a>exit</a> do the same thing inside of
--   <a>once</a>.
once :: Monad m => LoopT a a m a -> m a

-- | Execute the loop body again and again. The only way to exit
--   <a>repeatLoopT</a> is to call <a>exit</a> or <a>exitWith</a>.
repeatLoopT :: Monad m => LoopT c e m a -> m e

-- | Call the loop body again and again, passing it the result of the
--   previous iteration each time around. The only way to exit
--   <a>iterateLoopT</a> is to call <a>exit</a> or <a>exitWith</a>.
--   
--   Example:
--   
--   <pre>
--   count :: Int -&gt; IO Int
--   count n = iterateLoopT 0 $ \i -&gt;
--       if i &lt; n
--           then do
--               lift $ print i
--               return $ i+1
--           else exitWith i
--   </pre>
iterateLoopT :: Monad m => c -> (c -> LoopT c e m c) -> m e

-- | Lift a function like <a>local</a> or <a>mask_</a>.
liftLocalLoopT :: Monad m => (forall a. m a -> m a) -> LoopT c e m b -> LoopT c e m b
instance MonadBase b m => MonadBase b (LoopT c e m)
instance MonadIO m => MonadIO (LoopT c e m)
instance MonadTrans (LoopT c e)
instance Monad (LoopT c e m)
instance Applicative (LoopT c e m)
instance Functor (LoopT c e m)