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


-- | Fast, easy to use CPS-based monad transformers
--   
--   This library implements fast and easy to use CPS-based monad
--   transformers. Most of the usual monad transformers are implemented,
--   including ChoiceT, ContT, EitherT, MaybeT and StateT. Because of the
--   design of this library, many other monad transformers are just special
--   cases of those, including e.g. ReaderT and WriterT. The
--   Control.ContStuff.Simple module also provides simplified monad
--   transformer wrappers, which hide the underlying CPS, so you get the
--   full performance, but with a simplified interface. Currently the
--   simplified monad transformers are implemented as type synonyms, so
--   their flexibility is slightly limited.
@package contstuff
@version 1.2.4


-- | This module implements the various effect classes supported by
--   contstuff.
module Control.ContStuff.Classes

-- | 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 support for forking threads.
class Monad m => Forkable m
forkIO :: Forkable m => m a -> m ThreadId
forkOS :: Forkable m => m a -> m ThreadId

-- | 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 <tt>E.bracket</tt>. 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 <tt>E.bracket_</tt>. 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), MonadTrans 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 returns <a>False</a>.
raiseUnless :: (HasExceptions m, Monad m) => Exception m -> m Bool -> m ()

-- | Throw given exception, if the given computation returns <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), MonadTrans t) => m Bool -> t m ()

-- | Type class for lifting functor computations.
class LiftFunctor t where { type family InnerFunctor t :: * -> *; }
liftF :: (LiftFunctor t, Monad m) => m (InnerFunctor t a) -> t m a

-- | Monads with environment (reader monads).
class Readable m where { type family StateOf m; }
get :: Readable m => m (StateOf m)

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

-- | Stateful monads, i.e. having a modifyable environment (stateful
--   monads).
--   
--   Minimal complete definition: <a>putLazy</a>.
class Stateful m
put :: Stateful m => StateOf m -> m ()
putLazy :: Stateful m => StateOf m -> m ()

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

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

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

-- | Apply a function to the current state. Lazy version.
modifyLazy :: (Monad m, Readable 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 Forkable IO


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

-- | The trivial monad transformer, which maps a monad to an equivalent
--   monad.
newtype IdentityT m :: (* -> *) a :: (* -> *) -> * -> *
IdentityT :: m a -> IdentityT a
runIdentityT :: IdentityT 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 r 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 r 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 ()

-- | Run the <a>EitherT</a> computation and return <a>True</a>, if it
--   results in a right value, <a>False</a> otherwise.
testEitherT :: Applicative m => EitherT Bool e m a -> m Bool

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

-- | Run the <a>MaybeT</a> computation and return <a>True</a>, if it
--   results in a Just value, <a>False</a> otherwise.
testMaybeT :: Applicative m => MaybeT Bool m a -> m Bool

-- | Monad transformer for computations with readable environment. Unlike
--   the other monad transformers this one allows no CPS effects and also
--   hides its constructors, which makes it commutative.
--   
--   If you need CPS effects, consider using <a>StateT</a>.
data ReaderT e m a

-- | Run a computation with environment.
runReaderT :: Applicative m => e -> ReaderT e m a -> m a

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

-- | Run a state transformer.
runStateT :: s -> (a -> s -> 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
instance (Functor m, Monoid w) => Writable (StateT (r, w) s m) w
instance Alternative m => Writable (StateT r s m) r
instance MonadTrans (StateT r s)
instance Stateful (StateT r s m)
instance Readable (StateT r s m)
instance Alternative m => MonadPlus (StateT r s m)
instance MonadIO m => MonadIO (StateT r s m)
instance Monad (StateT r s m)
instance Functor (StateT r s m)
instance Forkable m => Forkable (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 MonadTrans (ReaderT e)
instance Readable (ReaderT e m)
instance MonadIO m => MonadIO (ReaderT e m)
instance Monad (ReaderT e m)
instance Functor (ReaderT e m)
instance Forkable m => Forkable (ReaderT e m)
instance Applicative (ReaderT e m)
instance (Functor m, Monoid w) => Writable (MaybeT (r, w) m) w
instance Alternative m => Writable (MaybeT r m) r
instance MonadTrans (MaybeT r)
instance Alternative m => MonadPlus (MaybeT r m)
instance MonadIO m => MonadIO (MaybeT r m)
instance Monad (MaybeT r m)
instance LiftFunctor (MaybeT r)
instance Functor (MaybeT r m)
instance HasExceptions (MaybeT r m)
instance Forkable m => Forkable (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 (Functor m, Monoid w) => Writable (EitherT (r, w) e m) w
instance Alternative m => Writable (EitherT r e m) r
instance MonadTrans (EitherT r e)
instance Alternative m => MonadPlus (EitherT r e m)
instance MonadIO m => MonadIO (EitherT r e m)
instance Monad (EitherT r e m)
instance LiftFunctor (EitherT r e)
instance HasExceptions (EitherT r e m)
instance Functor (EitherT r e m)
instance Forkable m => Forkable (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 MonadTrans (ContT r)
instance MonadIO m => MonadIO (ContT r m)
instance Alternative m => MonadPlus (ContT r m)
instance Monad (ContT r m)
instance Functor (ContT r m)
instance Forkable m => Forkable (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 MonadTrans (ChoiceT r i)
instance MonadPlus (ChoiceT r i m)
instance MonadIO m => MonadIO (ChoiceT r i m)
instance Monad (ChoiceT r i m)
instance LiftFunctor (ChoiceT r i)
instance Functor (ChoiceT r i m)
instance Forkable m => Forkable (ChoiceT r i m)
instance Applicative (ChoiceT r i m)
instance Alternative (ChoiceT r i m)
instance Applicative m => Abortable (ChoiceT r i m)


-- | This module implements the non-transformer variants of the monad
--   transformers found in <a>Control.ContStuff.Trans</a>.
module Control.ContStuff.Monads

-- | The choice monad. Derived from <a>ChoiceT</a>.
type Choice r i a = ChoiceT r i Identity 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 Identity 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 computation with environment.
type Reader e a = ReaderT e Identity a

-- | Run a pure computation with environment.
runReader :: e -> Reader e a -> a

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

-- | Run a stateful computation.
runState :: s -> (a -> s -> 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) Identity 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


-- | This module implements some miscellaneous type class instances.
module Control.ContStuff.Instances
instance (Monad m, Stateful m) => Stateful (MaybeT r m)
instance (Monad m, Stateful m) => Stateful (IdentityT m)
instance (Monad m, Stateful m) => Stateful (EitherT r e m)
instance (Monad m, Stateful m) => Stateful (ContT r m)
instance (Monad m, Stateful m) => Stateful (ChoiceT r i m)
instance (Monad m, Readable m) => Readable (MaybeT r m)
instance (Monad m, Readable m) => Readable (IdentityT m)
instance (Monad m, Readable m) => Readable (EitherT r e m)
instance (Monad m, Readable m) => Readable (ContT r m)
instance (Monad m, Readable m) => Readable (ChoiceT r i m)
instance HasExceptions IO
instance HasExceptions Maybe
instance HasExceptions (Either e)


-- | This module provides all the transformers from
--   <a>Control.ContStuff.Trans</a>, but with a simplified interface,
--   hiding the underlying CPS machinery.
module Control.ContStuff.Simple
type ChoiceT m a = forall r i. ChoiceT r i m a
choice :: [a] -> ChoiceT m a
findAll :: (Alternative f, Applicative m) => ChoiceT m a -> m (f a)
findAll_ :: Applicative m => ChoiceT m a -> m ()
findFirst :: (Alternative f, Applicative m) => ChoiceT m a -> m (f a)
findFirst_ :: Applicative m => ChoiceT m a -> m ()

-- | Turn a list into a computation with alternatives.
listA :: Alternative f => [a] -> f a
listChoiceT :: Applicative m => ChoiceT m a -> m [a]
maybeChoiceT :: Applicative m => ChoiceT m a -> m (Maybe a)
type EitherT e m a = forall r. EitherT r e m a
evalEitherT :: Applicative m => EitherT e m a -> m (Either e a)
testEitherT :: Applicative m => EitherT e m a -> m Bool
type MaybeT m a = forall r. MaybeT r m a
evalMaybeT :: Applicative m => MaybeT m a -> m (Maybe a)
testMaybeT :: Applicative m => MaybeT m a -> m Bool

-- | Monad transformer for computations with readable environment. Unlike
--   the other monad transformers this one allows no CPS effects and also
--   hides its constructors, which makes it commutative.
--   
--   If you need CPS effects, consider using <a>StateT</a>.
data ReaderT e m a

-- | Run a computation with environment.
runReaderT :: Applicative m => e -> ReaderT e m a -> m a
type StateT s m a = forall r. StateT r s m a
evalStateT :: Applicative m => s -> StateT s m a -> m a
execStateT :: Applicative m => s -> StateT s m a -> m s
type WriterT w m a = forall r. OldWriterT r w m a
runWriterT :: (Applicative m, Monoid w) => WriterT w m a -> m (a, w)
evalWriterT :: (Applicative m, Monoid w) => WriterT w m a -> m a
execWriterT :: (Applicative m, Monoid w) => WriterT w m a -> m w


-- | Convenience module.
module Control.ContStuff