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


-- | Easy to use CPS-based monads
--   
--   This library implements easy to use CPS-based monads.
@package contstuff
@version 0.3.0


-- | This module implements a number of monad transformers using a CPS
--   approach internally.
module Control.ContStuff

-- | The identity monad transformer. This monad transformer represents
--   computations themselves without further side effects. Unlike most
--   other monad transformers in this module it is not implemented in terms
--   of continuation passing style.
newtype IdT m a
IdT :: m a -> IdT m a
getIdT :: IdT m a -> m a

-- | The continuation passing style monad transformer. This monad
--   transformer models the most basic form of CPS.
newtype ContT r m a
ContT :: ((a -> m r) -> m r) -> ContT r m a
getContT :: ContT r m a -> (a -> m r) -> m r

-- | Run a CPS-style computation given the supplied final continuation.
runContT :: (a -> m r) -> ContT r m a -> m r

-- | Evaluate a CPS-style computation to its final result.
evalContT :: (Applicative m) => ContT r m r -> m r

-- | Transform the final result along the way.
modifyContT :: (Functor m) => (r -> r) -> ContT r m ()

-- | The choice monad transformer, which models, as the most common
--   interpretation, nondeterminism. Internally a list of choices is
--   represented as a CPS-based left-fold function.
newtype ChoiceT r i m a
ChoiceT :: ((i -> a -> (i -> m r) -> m r) -> i -> (i -> m r) -> m r) -> ChoiceT r i m a
getChoiceT :: ChoiceT r i m a -> (i -> a -> (i -> m r) -> m r) -> i -> (i -> m r) -> m r

-- | Run a choice computation.
runChoiceT :: (i -> a -> (i -> m r) -> m r) -> i -> (i -> m r) -> ChoiceT r i m a -> m r

-- | Find the first solution.
findFirst :: (Alternative f, Applicative m) => ChoiceT (f a) (f a) m a -> m (f a)

-- | Find all solutions.
findAll :: (Alternative f, Applicative m) => ChoiceT (f a) (f a) m a -> m (f a)

-- | Get list of solutions (faster than <a>findAll</a>, but returns
--   solutions in reversed order).
listChoiceT :: (Applicative m) => ChoiceT [a] [a] m a -> m [a]

-- | Turn a list into a computation with alternatives.
listA :: (Alternative f) => [a] -> f a

-- | Monad transformer for CPS computations with an additional exception
--   continuation.
newtype EitherT r e m a
EitherT :: ((a -> m r) -> (e -> m r) -> m r) -> EitherT r e m a
getEitherT :: EitherT r e m a -> (a -> m r) -> (e -> m r) -> m r

-- | Run an <a>EitherT</a> transformer.
runEitherT :: (a -> m r) -> (e -> m r) -> EitherT r e m a -> m r

-- | Run an <a>EitherT</a> transformer returning an <a>Either</a> result.
evalEitherT :: (Applicative m) => EitherT (Either e a) e m a -> m (Either e a)

-- | Monad transformer for stateful computations.
newtype StateT r s m a
StateT :: (s -> (s -> a -> m r) -> m r) -> StateT r s m a
getStateT :: StateT r s m a -> s -> (s -> a -> m r) -> m r

-- | Run a state transformer.
runStateT :: s -> (s -> a -> m r) -> StateT r s m a -> m r

-- | Run a state transformer returning its result.
evalStateT :: (Applicative m) => s -> StateT r s m r -> m r

-- | Run a state transformer returning its final state.
execStateT :: (Applicative m) => s -> StateT s s m a -> m s

-- | The writer monad transformer. Supports logging effects.
type WriterT = ContT

-- | Run a writer transformer.
runWriterT :: (Alternative m) => WriterT r m a -> m r

-- | The traditional writer monad transformer.
type OldWriterT r w m a = ContT (r, w) m a

-- | Run a traditional writer transformer.
runOldWriterT :: (Applicative m, Monoid w) => OldWriterT r w m r -> m (r, w)

-- | Run a traditional writer transformer and return its result.
evalOldWriterT :: (Applicative m, Monoid w) => OldWriterT r w m r -> m r

-- | Run a traditional writer transformer and return its log.
execOldWriterT :: (Applicative m, Monoid w) => OldWriterT r w m r -> m w

-- | The identity monad. This monad represents values themselves, i.e.
--   computations without effects.
newtype Id a
Id :: a -> Id a
getId :: Id a -> a

-- | Pure CPS monad derived from ContT.
type Cont r a = ContT r Id a

-- | Run a pure CPS computation.
runCont :: (a -> r) -> Cont r a -> r

-- | Evaluate a pure CPS computation to its final result.
evalCont :: Cont r r -> r

-- | Modify the result of a CPS computation along the way.
modifyCont :: (r -> r) -> Cont r ()

-- | Pure state monad derived from StateT.
type State r s a = StateT r s Id a

-- | Run a stateful computation.
runState :: s -> (s -> a -> r) -> State r s a -> r

-- | Run a stateful computation returning its result.
evalState :: s -> State r s r -> r

-- | Run a stateful computation returning its result.
execState :: s -> State s s a -> s

-- | The traditional writer monad.
type OldWriter r w a = ContT (r, w) Id a

-- | Run a traditional writer computation.
runOldWriter :: (Monoid w) => OldWriter r w r -> (r, w)

-- | Run a traditional writer computation and return its result.
evalOldWriter :: (Monoid w) => OldWriter r w r -> r

-- | Run a traditional writer computation and return its log.
execOldWriter :: (Monoid w) => OldWriter r w r -> w

-- | Monads supporting abortion.
class Abortable m where { type family Result m; }
abort :: (Abortable m) => Result m -> m a

-- | Monads supporting *call-with-current-continuation* (aka callCC).
class CallCC m
callCC :: (CallCC m) => ((a -> m b) -> m a) -> m a
data Label m a

-- | Capture the current continuation for later use.
labelCC :: (Applicative m, CallCC m) => a -> m (a, Label m a)

-- | Jump to a label.
goto :: Label m a -> a -> m ()

-- | Monads with exception support.
class HasExceptions m where { type family Exception m; }
raise :: (HasExceptions m) => Exception m -> m a
try :: (HasExceptions m) => m a -> m (Either (Exception m) a)

-- | Catch exceptions using an exception handler.
catch :: (HasExceptions m, Monad m) => m a -> (Exception m -> m a) -> m a

-- | Catch exceptions using an exception handler (flip <a>catch</a>).
handle :: (HasExceptions m, Monad m) => (Exception m -> m a) -> m a -> m a

-- | Run a final computation regardless of whether an exception was raised.
finally :: (HasExceptions m, Monad m) => m a -> m b -> m a

-- | Get a resource, run a computation, then release the resource, even if
--   an exception is raised:
--   
--   <pre>
--   bracket acquire release use
--   </pre>
--   
--   Please note that this function behaves slightly different from the
--   usual <a>bracket</a>. If both the user and the releaser throw an
--   exception, the user exception is significant.
bracket :: (HasExceptions m, Monad m) => m res -> (res -> m b) -> (res -> m a) -> m a

-- | Initialize, then run, then clean up safely, even if an exception is
--   raised:
--   
--   <pre>
--   bracket_ init cleanup run
--   </pre>
--   
--   Please note that this function behaves slightly different from the
--   usual <a>bracket_</a>. If both the user and the releaser throw an
--   exception, the user exception is significant.
bracket_ :: (HasExceptions m, Monad m) => m a -> m b -> m c -> m c

-- | The monad transformer class. Lifting computations one level down the
--   monad stack, or stated differently promoting a computation of the
--   underlying monad to the transformer.
class Transformer t
lift :: (Transformer t, Monad m) => m a -> t m a

-- | Monads, which support lifting base monad computations.
class LiftBase m a where { type family Base m a; }
base :: (LiftBase m a) => Base m a -> m a

-- | Handy alias for lifting IO computations.
io :: (LiftBase m a, (Base m a) ~ (IO a)) => Base m a -> m a

-- | Every monad transformer <tt>t</tt> that supports transforming <tt>t m
--   a</tt> to <tt>m a</tt> can be an instance of this class.
class Runnable t r m a where { type family Argument t r m a; }
runT :: (Runnable t r m a) => Argument t r m a -> t m a -> m r

-- | Stateful monads.
class Stateful m where { type family StateOf m; { put x = x `seq` putLazy x } }
get :: (Stateful m) => m (StateOf m)
put :: (Stateful m) => StateOf m -> m ()
putLazy :: (Stateful m) => StateOf m -> m ()

-- | Get a certain field.
getField :: (Functor m, Stateful m) => (StateOf m -> a) -> m a

-- | Apply a function to the current state.
modify :: (Monad m, Stateful m) => (StateOf m -> StateOf m) -> m ()

-- | Get a field and modify the state.
modifyField :: (Monad m, Stateful m) => (StateOf m -> a) -> (a -> StateOf m) -> m ()

-- | Get a field and modify the state. Lazy version.
modifyFieldLazy :: (Monad m, Stateful m) => (StateOf m -> a) -> (a -> StateOf m) -> m ()

-- | Apply a function to the current state. Lazy version.
modifyLazy :: (Monad m, Stateful m) => (StateOf m -> StateOf m) -> m ()

-- | Monads with support for logging. Traditionally these are called
--   *writer monads*.
class Writable m w
tell :: (Writable m w) => w -> m ()
instance (Monad m, Stateful m) => Stateful (ContT r m)
instance (LiftBase m a, Monad m) => LiftBase (StateT r s m) a
instance (LiftBase m a, Monad m) => LiftBase (ContT r m) a
instance (LiftBase m a, Monad m) => LiftBase (ChoiceT r i m) a
instance (LiftBase m a, Monad m) => LiftBase (IdT m) a
instance LiftBase ((->) r) a
instance LiftBase [] a
instance LiftBase (ST s) a
instance LiftBase Maybe a
instance LiftBase Id a
instance LiftBase IO a
instance HasExceptions IO
instance HasExceptions Maybe
instance HasExceptions (Either e)
instance (Functor m, Monoid w) => Writable (StateT (r, w) s m) w
instance (Alternative m) => Writable (StateT r s m) r
instance Transformer (StateT r s)
instance Stateful (StateT r s m)
instance Runnable (StateT r s) r m a
instance Monad (StateT r s m)
instance Functor (StateT r s m)
instance CallCC (StateT r s m)
instance Applicative (StateT r s m)
instance (Alternative m) => Alternative (StateT r s m)
instance (Applicative m) => Abortable (StateT r s m)
instance Transformer IdT
instance Runnable IdT r m r
instance (MonadFix m) => MonadFix (IdT m)
instance (Monad m) => Monad (IdT m)
instance (Functor m) => Functor (IdT m)
instance (Applicative m) => Applicative (IdT m)
instance (Alternative m) => Alternative (IdT m)
instance (Functor m, Monoid w) => Writable (EitherT (r, w) e m) w
instance (Alternative m) => Writable (EitherT r e m) r
instance Transformer (EitherT r e)
instance Runnable (EitherT r e) r m a
instance Monad (EitherT r e m)
instance Functor (EitherT r e m)
instance HasExceptions (EitherT r e m)
instance CallCC (EitherT r e m)
instance (Alternative m) => Alternative (EitherT r e m)
instance Applicative (EitherT r e m)
instance (Applicative m) => Abortable (EitherT r e m)
instance (Functor m, Monoid w) => Writable (ContT (r, w) m) w
instance (Alternative m) => Writable (ContT r m) r
instance Transformer (ContT r)
instance Runnable (ContT r) r m a
instance Monad (ContT r m)
instance Functor (ContT r m)
instance CallCC (ContT r m)
instance Applicative (ContT r m)
instance (Alternative m, Monad m) => Alternative (ContT r m)
instance (Applicative m) => Abortable (ContT r m)
instance Transformer (ChoiceT r i)
instance Monad (ChoiceT r i m)
instance Functor (ChoiceT r i m)
instance Applicative (ChoiceT r i m)
instance Alternative (ChoiceT r i m)
instance MonadFix Id
instance Monad Id
instance Applicative Id
instance Functor Id