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


-- | Fast, easy to use CPS-based monads
--   
--   This library implements fast and easy to use CPS-based monad
--   transformers. Most of the usual monads are implemented.
@package contstuff
@version 0.6.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

-- | Turn a list into a <a>ChoiceT</a> computation efficiently.
choice :: [a] -> ChoiceT r i m a

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

-- | Find all solutions and ignore them.
findAll_ :: Applicative m => ChoiceT () i m a -> m ()

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

-- | Find the first solution and ignore it.
findFirst_ :: Applicative m => ChoiceT () i m a -> m ()

-- | Turn a list into a computation with alternatives.
listA :: Alternative f => [a] -> 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]

-- | Get one solution (faster than <a>findFirst</a>).
maybeChoiceT :: Applicative m => ChoiceT (Maybe a) (Maybe a) m a -> m (Maybe 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)

-- | Modify the result of an <a>EitherT</a> computation along the way.
modifyEitherT :: Functor m => (r -> r) -> EitherT r e m ()

-- | Monad transformer for CPS computations with an additional exception
--   continuation with no argument.
newtype MaybeT r m a
MaybeT :: ((a -> m r) -> m r -> m r) -> MaybeT r m a
getMaybeT :: MaybeT r m a -> (a -> m r) -> m r -> m r

-- | Run a <a>MaybeT</a> transformer.
runMaybeT :: (a -> m r) -> m r -> MaybeT r m a -> m r

-- | Run a <a>MaybeT</a> transformer returning a <a>Maybe</a> result.
evalMaybeT :: Applicative m => MaybeT (Maybe a) m a -> m (Maybe a)

-- | Modify the result of a <a>MaybeT</a> computation along the way.
modifyMaybeT :: Functor m => (r -> r) -> MaybeT r m ()

-- | 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

-- | The choice monad. Derived from <a>ChoiceT</a>.
type Choice r i a = ChoiceT r i Id a

-- | Get list of solutions.
listChoice :: Choice [a] [a] a -> [a]

-- | Get one solution.
maybeChoice :: Choice (Maybe a) (Maybe a) a -> Maybe 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)

-- | 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

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

-- | Fail (in the sense of the given transformer), if the given underlying
--   computation returns <a>True</a>.
forbid :: ((Exception (t m)) ~ (), HasExceptions (t m), Monad m, Monad (t m), Transformer t) => m Bool -> t m ()

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

-- | Throw given exception, if the given computation does not return
--   <a>True</a>.
raiseUnless :: (HasExceptions m, Monad m) => Exception m -> m Bool -> m ()

-- | Throw given exception, if the given computation does not return
--   <a>True</a>.
raiseWhen :: (HasExceptions m, Monad m) => Exception m -> m Bool -> m ()

-- | Fail (in the sense of the given transformer), if the given underlying
--   computation returns <a>False</a>.
require :: ((Exception (t m)) ~ (), HasExceptions (t m), Monad m, Monad (t m), Transformer t) => m Bool -> t m ()

-- | 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 where { type family Base m :: * -> *; }
base :: LiftBase m => Base m a -> m a

-- | Handy alias for lifting <a>IO</a> computations.
io :: (LiftBase m, (Base m) ~ IO) => 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.
--   
--   Minimal complete definition: <a>StateOf</a>, <a>get</a> and
--   <a>putLazy</a>.
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 (EitherT r e m)
instance (Monad m, Stateful m) => Stateful (ContT r m)
instance (LiftBase m, Monad m) => LiftBase (StateT r s m)
instance (LiftBase m, Monad m) => LiftBase (MaybeT r m)
instance (LiftBase m, Monad m) => LiftBase (EitherT r e m)
instance (LiftBase m, Monad m) => LiftBase (ContT r m)
instance (LiftBase m, Monad m) => LiftBase (ChoiceT r i m)
instance (LiftBase m, Monad m) => LiftBase (IdT m)
instance LiftBase ((->) r)
instance LiftBase []
instance LiftBase (ST s)
instance LiftBase Maybe
instance LiftBase Id
instance LiftBase IO
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 Alternative m => MonadPlus (StateT r s m)
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 (Functor m, Monoid w) => Writable (MaybeT (r, w) m) w
instance Alternative m => Writable (MaybeT r m) r
instance Transformer (MaybeT r)
instance Runnable (MaybeT r) r m a
instance Alternative m => MonadPlus (MaybeT r m)
instance Monad (MaybeT r m)
instance Functor (MaybeT r m)
instance HasExceptions (MaybeT r m)
instance CallCC (MaybeT r m)
instance Alternative (MaybeT r m)
instance Applicative (MaybeT r m)
instance Applicative m => Abortable (MaybeT r m)
instance Transformer IdT
instance Runnable IdT r m r
instance MonadFix m => MonadFix (IdT m)
instance (Alternative m, Monad m) => MonadPlus (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 Alternative m => MonadPlus (EitherT r e m)
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 Alternative m => MonadPlus (ContT r m)
instance Monad (ContT r m)
instance Functor (ContT r m)
instance CallCC (ContT r m)
instance Applicative (ContT r m)
instance Alternative m => Alternative (ContT r m)
instance Applicative m => Abortable (ContT r m)
instance Transformer (ChoiceT r i)
instance MonadPlus (ChoiceT r i m)
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 Applicative m => Abortable (ChoiceT r i m)
instance Show a => Show (Id a)
instance MonadFix Id
instance Monad Id
instance Applicative Id
instance Functor Id