libghc-transformers-doc 0.3.0.0-5 / usr / share / doc / libghc-transformers-doc / html / transformers.txt

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


-- | Concrete functor and monad transformers
--   
--   A portable library of functor and monad transformers, inspired by the
--   paper "Functional Programming with Overloading and Higher-Order
--   Polymorphism", by Mark P Jones, in <i>Advanced School of Functional
--   Programming</i>, 1995
--   (<a>http://web.cecs.pdx.edu/~mpj/pubs/springschool.html</a>).
--   
--   This package contains:
--   
--   <ul>
--   <li>the monad transformer class (in
--   <a>Control.Monad.Trans.Class</a>)</li>
--   <li>concrete functor and monad transformers, each with associated
--   operations and functions to lift operations associated with other
--   transformers.</li>
--   </ul>
--   
--   It can be used on its own in portable Haskell code, or with the monad
--   classes in the <tt>mtl</tt> or <tt>monads-tf</tt> packages, which
--   automatically lift operations introduced by monad transformers through
--   other transformers.
@package transformers
@version 0.3.0.0


-- | Products, lifted to functors.
module Data.Functor.Product

-- | Lifted product of functors.
data Product f g a
Pair :: (f a) -> (g a) -> Product f g a
instance (MonadFix f, MonadFix g) => MonadFix (Product f g)
instance (MonadPlus f, MonadPlus g) => MonadPlus (Product f g)
instance (Monad f, Monad g) => Monad (Product f g)
instance (Alternative f, Alternative g) => Alternative (Product f g)
instance (Applicative f, Applicative g) => Applicative (Product f g)
instance (Traversable f, Traversable g) => Traversable (Product f g)
instance (Foldable f, Foldable g) => Foldable (Product f g)
instance (Functor f, Functor g) => Functor (Product f g)


-- | Composition of functors.
module Data.Functor.Compose

-- | Right-to-left composition of functors. The composition of applicative
--   functors is always applicative, but the composition of monads is not
--   always a monad.
newtype Compose f g a
Compose :: f (g a) -> Compose f g a
getCompose :: Compose f g a -> f (g a)
instance (Alternative f, Applicative g) => Alternative (Compose f g)
instance (Applicative f, Applicative g) => Applicative (Compose f g)
instance (Traversable f, Traversable g) => Traversable (Compose f g)
instance (Foldable f, Foldable g) => Foldable (Compose f g)
instance (Functor f, Functor g) => Functor (Compose f g)


-- | The identity functor and monad.
--   
--   This trivial type constructor serves two purposes:
--   
--   <ul>
--   <li>It can be used with functions parameterized by functor or monad
--   classes.</li>
--   <li>It can be used as a base monad to which a series of monad
--   transformers may be applied to construct a composite monad. Most monad
--   transformer modules include the special case of applying the
--   transformer to <a>Identity</a>. For example, <tt>State s</tt> is an
--   abbreviation for <tt>StateT s <a>Identity</a></tt>.</li>
--   </ul>
module Data.Functor.Identity

-- | Identity functor and monad.
newtype Identity a
Identity :: a -> Identity a
runIdentity :: Identity a -> a
instance MonadFix Identity
instance Monad Identity
instance Applicative Identity
instance Traversable Identity
instance Foldable Identity
instance Functor Identity


-- | Classes for monad transformers.
--   
--   A monad transformer makes a new monad out of an existing monad, such
--   that computations of the old monad may be embedded in the new one. To
--   construct a monad with a desired set of features, one typically starts
--   with a base monad, such as <tt>Identity</tt>, <tt>[]</tt> or
--   <a>IO</a>, and applies a sequence of monad transformers.
--   
--   Most monad transformer modules include the special case of applying
--   the transformer to <tt>Identity</tt>. For example, <tt>State s</tt> is
--   an abbreviation for <tt>StateT s Identity</tt>.
--   
--   Each monad transformer also comes with an operation
--   <tt>run</tt><i>XXX</i> to unwrap the transformer, exposing a
--   computation of the inner monad.
module Control.Monad.Trans.Class

-- | The class of monad transformers. Instances should satisfy the
--   following laws, which state that <a>lift</a> is a transformer of
--   monads:
--   
--   <ul>
--   <li><pre><a>lift</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>lift</a> (m &gt;&gt;= f) = <a>lift</a> m &gt;&gt;=
--   (<a>lift</a> . f)</pre></li>
--   </ul>
class MonadTrans t
lift :: (MonadTrans t, Monad m) => m a -> t m a


-- | Class of monads based on <tt>IO</tt>.
module Control.Monad.IO.Class

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO m
liftIO :: MonadIO m => IO a -> m a
instance MonadIO IO


-- | Continuation monads.
module Control.Monad.Trans.Cont

-- | Continuation monad. <tt>Cont r a</tt> is a CPS computation that
--   produces an intermediate result of type <tt>a</tt> within a CPS
--   computation whose final result type is <tt>r</tt>.
--   
--   The <tt>return</tt> function simply creates a continuation which
--   passes the value on.
--   
--   The <tt>&gt;&gt;=</tt> operator adds the bound function into the
--   continuation chain.
type Cont r = ContT r Identity

-- | Construct a continuation-passing computation from a function. (The
--   inverse of <a>runCont</a>.)
cont :: ((a -> r) -> r) -> Cont r a

-- | Runs a CPS computation, returns its result after applying the final
--   continuation to it. (The inverse of <a>cont</a>.)
runCont :: Cont r a -> (a -> r) -> r

-- | Apply a function to transform the result of a continuation-passing
--   computation.
--   
--   <ul>
--   <li><pre><a>runCont</a> (<a>mapCont</a> f m) = f . <a>runCont</a>
--   m</pre></li>
--   </ul>
mapCont :: (r -> r) -> Cont r a -> Cont r a

-- | Apply a function to transform the continuation passed to a CPS
--   computation.
--   
--   <ul>
--   <li><pre><a>runCont</a> (<a>withCont</a> f m) = <a>runCont</a> m .
--   f</pre></li>
--   </ul>
withCont :: ((b -> r) -> (a -> r)) -> Cont r a -> Cont r b

-- | The continuation monad transformer. Can be used to add continuation
--   handling to other monads.
newtype ContT r m a
ContT :: ((a -> m r) -> m r) -> ContT r m a
runContT :: ContT r m a -> (a -> m r) -> m r

-- | Apply a function to transform the result of a continuation-passing
--   computation.
--   
--   <ul>
--   <li><pre><a>runContT</a> (<a>mapContT</a> f m) = f . <a>runContT</a>
--   m</pre></li>
--   </ul>
mapContT :: (m r -> m r) -> ContT r m a -> ContT r m a

-- | Apply a function to transform the continuation passed to a CPS
--   computation.
--   
--   <ul>
--   <li><pre><a>runContT</a> (<a>withContT</a> f m) = <a>runContT</a> m .
--   f</pre></li>
--   </ul>
withContT :: ((b -> m r) -> (a -> m r)) -> ContT r m a -> ContT r m b

-- | <tt>callCC</tt> (call-with-current-continuation) calls its argument
--   function, passing it the current continuation. It provides an escape
--   continuation mechanism for use with continuation monads. Escape
--   continuations one allow to abort the current computation and return a
--   value immediately. They achieve a similar effect to <a>throwError</a>
--   and <a>catchError</a> within an <a>ErrorT</a> monad. The advantage of
--   this function over calling <a>return</a> is that it makes the
--   continuation explicit, allowing more flexibility and better control.
--   
--   The standard idiom used with <tt>callCC</tt> is to provide a
--   lambda-expression to name the continuation. Then calling the named
--   continuation anywhere within its scope will escape from the
--   computation, even if it is many layers deep within nested
--   computations.
callCC :: ((a -> ContT r m b) -> ContT r m a) -> ContT r m a

-- | <tt><a>liftLocal</a> ask local</tt> yields a <tt>local</tt> function
--   for <tt><a>ContT</a> r m</tt>.
liftLocal :: Monad m => m r' -> ((r' -> r') -> m r -> m r) -> (r' -> r') -> ContT r m a -> ContT r m a
instance MonadIO m => MonadIO (ContT r m)
instance MonadTrans (ContT r)
instance Monad (ContT r m)
instance Applicative (ContT r m)
instance Functor (ContT r m)


-- | This monad transformer adds the ability to fail or throw exceptions to
--   a monad.
--   
--   A sequence of actions succeeds, producing a value, only if all the
--   actions in the sequence are successful. If one fails with an error,
--   the rest of the sequence is skipped and the composite action fails
--   with that error.
--   
--   If the value of the error is not required, the variant in
--   <a>Control.Monad.Trans.Maybe</a> may be used instead.
module Control.Monad.Trans.Error

-- | An exception to be thrown.
--   
--   Minimal complete definition: <a>noMsg</a> or <a>strMsg</a>.
class Error a where noMsg = strMsg "" strMsg _ = noMsg
noMsg :: Error a => a
strMsg :: Error a => String -> a

-- | Workaround so that we can have a Haskell 98 instance <tt><a>Error</a>
--   <a>String</a></tt>.
class ErrorList a
listMsg :: ErrorList a => String -> [a]

-- | The error monad transformer. It can be used to add error handling to
--   other monads.
--   
--   The <tt>ErrorT</tt> Monad structure is parameterized over two things:
--   
--   <ul>
--   <li>e - The error type.</li>
--   <li>m - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function yields a successful computation, while
--   <tt>&gt;&gt;=</tt> sequences two subcomputations, failing on the first
--   error.
newtype ErrorT e m a
ErrorT :: m (Either e a) -> ErrorT e m a
runErrorT :: ErrorT e m a -> m (Either e a)

-- | Map the unwrapped computation using the given function.
--   
--   <ul>
--   <li><pre><a>runErrorT</a> (<a>mapErrorT</a> f m) = f (<a>runErrorT</a>
--   m)</pre></li>
--   </ul>
mapErrorT :: (m (Either e a) -> n (Either e' b)) -> ErrorT e m a -> ErrorT e' n b

-- | Signal an error value <tt>e</tt>.
--   
--   <ul>
--   <li><pre><a>runErrorT</a> (<a>throwError</a> e) = <a>return</a>
--   (<a>Left</a> e)</pre></li>
--   <li><pre><a>throwError</a> e &gt;&gt;= m = <a>throwError</a>
--   e</pre></li>
--   </ul>
throwError :: (Monad m, Error e) => e -> ErrorT e m a

-- | Handle an error.
--   
--   <ul>
--   <li><pre><a>catchError</a> h (<a>lift</a> m) = <a>lift</a>
--   m</pre></li>
--   <li><pre><a>catchError</a> h (<a>throwError</a> e) = h e</pre></li>
--   </ul>
catchError :: (Monad m, Error e) => ErrorT e m a -> (e -> ErrorT e m a) -> ErrorT e m a

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: (((Either e a -> m (Either e b)) -> m (Either e a)) -> m (Either e a)) -> ((a -> ErrorT e m b) -> ErrorT e m a) -> ErrorT e m a

-- | Lift a <tt>listen</tt> operation to the new monad.
liftListen :: Monad m => (m (Either e a) -> m (Either e a, w)) -> ErrorT e m a -> ErrorT e m (a, w)

-- | Lift a <tt>pass</tt> operation to the new monad.
liftPass :: Monad m => (m (Either e a, w -> w) -> m (Either e a)) -> ErrorT e m (a, w -> w) -> ErrorT e m a
instance (Error e, MonadIO m) => MonadIO (ErrorT e m)
instance Error e => MonadTrans (ErrorT e)
instance (MonadFix m, Error e) => MonadFix (ErrorT e m)
instance (Monad m, Error e) => MonadPlus (ErrorT e m)
instance (Monad m, Error e) => Monad (ErrorT e m)
instance (Functor m, Monad m, Error e) => Alternative (ErrorT e m)
instance (Functor m, Monad m) => Applicative (ErrorT e m)
instance Traversable f => Traversable (ErrorT e f)
instance Foldable f => Foldable (ErrorT e f)
instance Functor m => Functor (ErrorT e m)
instance Error e => MonadPlus (Either e)
instance Error e => Alternative (Either e)
instance ErrorList Char
instance ErrorList a => Error [a]
instance Error IOException
instance MonadPlus IO


-- | The identity monad transformer.
--   
--   This is useful for functions parameterized by a monad transformer.
module Control.Monad.Trans.Identity

-- | The trivial monad transformer, which maps a monad to an equivalent
--   monad.
newtype IdentityT m a
IdentityT :: m a -> IdentityT m a
runIdentityT :: IdentityT m a -> m a

-- | Lift a unary operation to the new monad.
mapIdentityT :: (m a -> n b) -> IdentityT m a -> IdentityT n b

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m a -> (e -> m a) -> m a) -> IdentityT m a -> (e -> IdentityT m a) -> IdentityT m a

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: (((a -> m b) -> m a) -> m a) -> ((a -> IdentityT m b) -> IdentityT m a) -> IdentityT m a
instance MonadTrans IdentityT
instance MonadIO m => MonadIO (IdentityT m)
instance MonadFix m => MonadFix (IdentityT m)
instance MonadPlus m => MonadPlus (IdentityT m)
instance Monad m => Monad (IdentityT m)
instance Alternative m => Alternative (IdentityT m)
instance Applicative m => Applicative (IdentityT m)
instance Traversable f => Traversable (IdentityT f)
instance Foldable f => Foldable (IdentityT f)
instance Functor m => Functor (IdentityT m)


-- | The ListT monad transformer, adding backtracking to a given monad,
--   which must be commutative.
module Control.Monad.Trans.List

-- | Parameterizable list monad, with an inner monad.
--   
--   <i>Note:</i> this does not yield a monad unless the argument monad is
--   commutative.
newtype ListT m a
ListT :: m [a] -> ListT m a
runListT :: ListT m a -> m [a]

-- | Map between <a>ListT</a> computations.
--   
--   <ul>
--   <li><pre><a>runListT</a> (<a>mapListT</a> f m) = f (<a>runListT</a>
--   m)</pre></li>
--   </ul>
mapListT :: (m [a] -> n [b]) -> ListT m a -> ListT n b

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: ((([a] -> m [b]) -> m [a]) -> m [a]) -> ((a -> ListT m b) -> ListT m a) -> ListT m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m [a] -> (e -> m [a]) -> m [a]) -> ListT m a -> (e -> ListT m a) -> ListT m a
instance MonadIO m => MonadIO (ListT m)
instance MonadTrans ListT
instance Monad m => MonadPlus (ListT m)
instance Monad m => Monad (ListT m)
instance Applicative m => Alternative (ListT m)
instance Applicative m => Applicative (ListT m)
instance Traversable f => Traversable (ListT f)
instance Foldable f => Foldable (ListT f)
instance Functor m => Functor (ListT m)


-- | The <a>MaybeT</a> monad transformer adds the ability to fail to a
--   monad.
--   
--   A sequence of actions succeeds, producing a value, only if all the
--   actions in the sequence are successful. If one fails, the rest of the
--   sequence is skipped and the composite action fails.
--   
--   For a variant allowing a range of error values, see
--   <a>Control.Monad.Trans.Error</a>.
module Control.Monad.Trans.Maybe

-- | The parameterizable maybe monad, obtained by composing an arbitrary
--   monad with the <a>Maybe</a> monad.
--   
--   Computations are actions that may produce a value or fail.
--   
--   The <a>return</a> function yields a successful computation, while
--   <tt>&gt;&gt;=</tt> sequences two subcomputations, failing on the first
--   error.
newtype MaybeT m a
MaybeT :: m (Maybe a) -> MaybeT m a
runMaybeT :: MaybeT m a -> m (Maybe a)

-- | Transform the computation inside a <tt>MaybeT</tt>.
--   
--   <ul>
--   <li><pre><a>runMaybeT</a> (<a>mapMaybeT</a> f m) = f (<a>runMaybeT</a>
--   m)</pre></li>
--   </ul>
mapMaybeT :: (m (Maybe a) -> n (Maybe b)) -> MaybeT m a -> MaybeT n b

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: (((Maybe a -> m (Maybe b)) -> m (Maybe a)) -> m (Maybe a)) -> ((a -> MaybeT m b) -> MaybeT m a) -> MaybeT m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (Maybe a) -> (e -> m (Maybe a)) -> m (Maybe a)) -> MaybeT m a -> (e -> MaybeT m a) -> MaybeT m a

-- | Lift a <tt>listen</tt> operation to the new monad.
liftListen :: Monad m => (m (Maybe a) -> m (Maybe a, w)) -> MaybeT m a -> MaybeT m (a, w)

-- | Lift a <tt>pass</tt> operation to the new monad.
liftPass :: Monad m => (m (Maybe a, w -> w) -> m (Maybe a)) -> MaybeT m (a, w -> w) -> MaybeT m a
instance MonadIO m => MonadIO (MaybeT m)
instance MonadTrans MaybeT
instance MonadFix m => MonadFix (MaybeT m)
instance Monad m => MonadPlus (MaybeT m)
instance Monad m => Monad (MaybeT m)
instance (Functor m, Monad m) => Alternative (MaybeT m)
instance (Functor m, Monad m) => Applicative (MaybeT m)
instance Traversable f => Traversable (MaybeT f)
instance Foldable f => Foldable (MaybeT f)
instance Functor m => Functor (MaybeT m)


-- | Declaration of the <a>ReaderT</a> monad transformer, which adds a
--   static environment to a given monad.
--   
--   If the computation is to modify the stored information, use
--   <a>Control.Monad.Trans.State</a> instead.
module Control.Monad.Trans.Reader

-- | The parameterizable reader monad.
--   
--   Computations are functions of a shared environment.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
type Reader r = ReaderT r Identity

-- | Constructor for computations in the reader monad (equivalent to
--   <a>asks</a>).
reader :: Monad m => (r -> a) -> ReaderT r m a

-- | Runs a <tt>Reader</tt> and extracts the final value from it. (The
--   inverse of <a>reader</a>.)
runReader :: Reader r a -> r -> a

-- | Transform the value returned by a <tt>Reader</tt>.
--   
--   <ul>
--   <li><pre><a>runReader</a> (<a>mapReader</a> f m) = f .
--   <a>runReader</a> m</pre></li>
--   </ul>
mapReader :: (a -> b) -> Reader r a -> Reader r b

-- | Execute a computation in a modified environment (a specialization of
--   <a>withReaderT</a>).
--   
--   <ul>
--   <li><pre><a>runReader</a> (<a>withReader</a> f m) = <a>runReader</a> m
--   . f</pre></li>
--   </ul>
withReader :: (r' -> r) -> Reader r a -> Reader r' a

-- | The reader monad transformer, which adds a read-only environment to
--   the given monad.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
newtype ReaderT r m a
ReaderT :: (r -> m a) -> ReaderT r m a

-- | The underlying computation, as a function of the environment.
runReaderT :: ReaderT r m a -> r -> m a

-- | Transform the computation inside a <tt>ReaderT</tt>.
--   
--   <ul>
--   <li><pre><a>runReaderT</a> (<a>mapReaderT</a> f m) = f .
--   <a>runReaderT</a> m</pre></li>
--   </ul>
mapReaderT :: (m a -> n b) -> ReaderT r m a -> ReaderT r n b

-- | Execute a computation in a modified environment (a more general
--   version of <a>local</a>).
--   
--   <ul>
--   <li><pre><a>runReaderT</a> (<a>withReaderT</a> f m) =
--   <a>runReaderT</a> m . f</pre></li>
--   </ul>
withReaderT :: (r' -> r) -> ReaderT r m a -> ReaderT r' m a

-- | Fetch the value of the environment.
ask :: Monad m => ReaderT r m r

-- | Execute a computation in a modified environment (a specialization of
--   <a>withReaderT</a>).
--   
--   <ul>
--   <li><pre><a>runReaderT</a> (<a>local</a> f m) = <a>runReaderT</a> m .
--   f</pre></li>
--   </ul>
local :: Monad m => (r -> r) -> ReaderT r m a -> ReaderT r m a

-- | Retrieve a function of the current environment.
--   
--   <ul>
--   <li><pre><a>asks</a> f = <a>liftM</a> f <a>ask</a></pre></li>
--   </ul>
asks :: Monad m => (r -> a) -> ReaderT r m a

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: (((a -> m b) -> m a) -> m a) -> ((a -> ReaderT r m b) -> ReaderT r m a) -> ReaderT r m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m a -> (e -> m a) -> m a) -> ReaderT r m a -> (e -> ReaderT r m a) -> ReaderT r m a
instance MonadIO m => MonadIO (ReaderT r m)
instance MonadTrans (ReaderT r)
instance MonadFix m => MonadFix (ReaderT r m)
instance MonadPlus m => MonadPlus (ReaderT r m)
instance Monad m => Monad (ReaderT r m)
instance Alternative m => Alternative (ReaderT r m)
instance Applicative m => Applicative (ReaderT r m)
instance Functor m => Functor (ReaderT r m)


-- | A monad transformer that combines <tt>ReaderT</tt>, <tt>WriterT</tt>
--   and <tt>StateT</tt>. This version is lazy; for a strict version, see
--   <a>Control.Monad.Trans.RWS.Strict</a>, which has the same interface.
module Control.Monad.Trans.RWS.Lazy

-- | A monad containing an environment of type <tt>r</tt>, output of type
--   <tt>w</tt> and an updatable state of type <tt>s</tt>.
type RWS r w s = RWST r w s Identity

-- | Construct an RWS computation from a function. (The inverse of
--   <a>runRWS</a>.)
rws :: (r -> s -> (a, s, w)) -> RWS r w s a

-- | Unwrap an RWS computation as a function. (The inverse of <a>rws</a>.)
runRWS :: RWS r w s a -> r -> s -> (a, s, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final value and output, discarding the final state.
evalRWS :: RWS r w s a -> r -> s -> (a, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final state and output, discarding the final value.
execRWS :: RWS r w s a -> r -> s -> (s, w)

-- | Map the return value, final state and output of a computation using
--   the given function.
--   
--   <ul>
--   <li><pre><a>runRWS</a> (<a>mapRWS</a> f m) r s = f (<a>runRWS</a> m r
--   s)</pre></li>
--   </ul>
mapRWS :: ((a, s, w) -> (b, s, w')) -> RWS r w s a -> RWS r w' s b

-- | <tt><a>withRWS</a> f m</tt> executes action <tt>m</tt> with an initial
--   environment and state modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>runRWS</a> (<a>withRWS</a> f m) r s = <a>uncurry</a>
--   (<a>runRWS</a> m) (f r s)</pre></li>
--   </ul>
withRWS :: (r' -> s -> (r, s)) -> RWS r w s a -> RWS r' w s a

-- | A monad transformer adding reading an environment of type <tt>r</tt>,
--   collecting an output of type <tt>w</tt> and updating a state of type
--   <tt>s</tt> to an inner monad <tt>m</tt>.
newtype RWST r w s m a
RWST :: (r -> s -> m (a, s, w)) -> RWST r w s m a
runRWST :: RWST r w s m a -> r -> s -> m (a, s, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final value and output, discarding the final state.
evalRWST :: Monad m => RWST r w s m a -> r -> s -> m (a, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final state and output, discarding the final value.
execRWST :: Monad m => RWST r w s m a -> r -> s -> m (s, w)

-- | Map the inner computation using the given function.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>mapRWST</a> f m) r s = f (<a>runRWST</a> m
--   r s)</pre></li>
--   </ul>
mapRWST :: (m (a, s, w) -> n (b, s, w')) -> RWST r w s m a -> RWST r w' s n b

-- | <tt><a>withRWST</a> f m</tt> executes action <tt>m</tt> with an
--   initial environment and state modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>withRWST</a> f m) r s = <a>uncurry</a>
--   (<a>runRWST</a> m) (f r s)</pre></li>
--   </ul>
withRWST :: (r' -> s -> (r, s)) -> RWST r w s m a -> RWST r' w s m a

-- | Constructor for computations in the reader monad (equivalent to
--   <a>asks</a>).
reader :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

-- | Fetch the value of the environment.
ask :: (Monoid w, Monad m) => RWST r w s m r

-- | Execute a computation in a modified environment
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>local</a> f m) r s = <a>runRWST</a> m (f
--   r) s</pre></li>
--   </ul>
local :: (Monoid w, Monad m) => (r -> r) -> RWST r w s m a -> RWST r w s m a

-- | Retrieve a function of the current environment.
--   
--   <ul>
--   <li><pre><a>asks</a> f = <a>liftM</a> f <a>ask</a></pre></li>
--   </ul>
asks :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

-- | Construct a writer computation from a (result, output) pair.
writer :: Monad m => (a, w) -> RWST r w s m a

-- | <tt><a>tell</a> w</tt> is an action that produces the output
--   <tt>w</tt>.
tell :: (Monoid w, Monad m) => w -> RWST r w s m ()

-- | <tt><a>listen</a> m</tt> is an action that executes the action
--   <tt>m</tt> and adds its output to the value of the computation.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>listen</a> m) r s = <a>liftM</a> (\(a, w)
--   -&gt; ((a, w), w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
listen :: (Monoid w, Monad m) => RWST r w s m a -> RWST r w s m (a, w)

-- | <tt><a>listens</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and adds the result of applying <tt>f</tt> to the output to
--   the value of the computation.
--   
--   <ul>
--   <li><pre><a>listens</a> f m = <a>liftM</a> (id *** f) (<a>listen</a>
--   m)</pre></li>
--   <li><pre><a>runRWST</a> (<a>listens</a> f m) r s = <a>liftM</a> (\(a,
--   w) -&gt; ((a, f w), w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
listens :: (Monoid w, Monad m) => (w -> b) -> RWST r w s m a -> RWST r w s m (a, b)

-- | <tt><a>pass</a> m</tt> is an action that executes the action
--   <tt>m</tt>, which returns a value and a function, and returns the
--   value, applying the function to the output.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>pass</a> m) r s = <a>liftM</a> (\((a, f),
--   w) -&gt; (a, f w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
pass :: (Monoid w, Monad m) => RWST r w s m (a, w -> w) -> RWST r w s m a

-- | <tt><a>censor</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   <ul>
--   <li><pre><a>censor</a> f m = <a>pass</a> (<a>liftM</a> (\x -&gt;
--   (x,f)) m)</pre></li>
--   <li><pre><a>runRWST</a> (<a>censor</a> f m) r s = <a>liftM</a> (\(a,
--   w) -&gt; (a, f w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
censor :: (Monoid w, Monad m) => (w -> w) -> RWST r w s m a -> RWST r w s m a

-- | Construct a state monad computation from a state transformer function.
state :: (Monoid w, Monad m) => (s -> (a, s)) -> RWST r w s m a

-- | Fetch the current value of the state within the monad.
get :: (Monoid w, Monad m) => RWST r w s m s

-- | <tt><a>put</a> s</tt> sets the state within the monad to <tt>s</tt>.
put :: (Monoid w, Monad m) => s -> RWST r w s m ()

-- | <tt><a>modify</a> f</tt> is an action that updates the state to the
--   result of applying <tt>f</tt> to the current state.
--   
--   <ul>
--   <li><pre><a>modify</a> f = <a>get</a> &gt;&gt;= (<a>put</a> .
--   f)</pre></li>
--   </ul>
modify :: (Monoid w, Monad m) => (s -> s) -> RWST r w s m ()

-- | Get a specific component of the state, using a projection function
--   supplied.
--   
--   <ul>
--   <li><pre><a>gets</a> f = <a>liftM</a> f <a>get</a></pre></li>
--   </ul>
gets :: (Monoid w, Monad m) => (s -> a) -> RWST r w s m a

-- | Uniform lifting of a <tt>callCC</tt> operation to the new monad. This
--   version rolls back to the original state on entering the continuation.
liftCallCC :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a

-- | In-situ lifting of a <tt>callCC</tt> operation to the new monad. This
--   version uses the current state on entering the continuation.
liftCallCC' :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (a, s, w) -> (e -> m (a, s, w)) -> m (a, s, w)) -> RWST l w s m a -> (e -> RWST l w s m a) -> RWST l w s m a
instance (Monoid w, MonadIO m) => MonadIO (RWST r w s m)
instance Monoid w => MonadTrans (RWST r w s)
instance (Monoid w, MonadFix m) => MonadFix (RWST r w s m)
instance (Monoid w, MonadPlus m) => MonadPlus (RWST r w s m)
instance (Monoid w, Monad m) => Monad (RWST r w s m)
instance (Monoid w, Functor m, MonadPlus m) => Alternative (RWST r w s m)
instance (Monoid w, Functor m, Monad m) => Applicative (RWST r w s m)
instance Functor m => Functor (RWST r w s m)


-- | A monad transformer that combines <tt>ReaderT</tt>, <tt>WriterT</tt>
--   and <tt>StateT</tt>. This version is lazy; for a strict version, see
--   <a>Control.Monad.Trans.RWS.Strict</a>, which has the same interface.
module Control.Monad.Trans.RWS


-- | A monad transformer that combines <tt>ReaderT</tt>, <tt>WriterT</tt>
--   and <tt>StateT</tt>. This version is strict; for a lazy version, see
--   <a>Control.Monad.Trans.RWS.Lazy</a>, which has the same interface.
module Control.Monad.Trans.RWS.Strict

-- | A monad containing an environment of type <tt>r</tt>, output of type
--   <tt>w</tt> and an updatable state of type <tt>s</tt>.
type RWS r w s = RWST r w s Identity

-- | Construct an RWS computation from a function. (The inverse of
--   <a>runRWS</a>.)
rws :: (r -> s -> (a, s, w)) -> RWS r w s a

-- | Unwrap an RWS computation as a function. (The inverse of <a>rws</a>.)
runRWS :: RWS r w s a -> r -> s -> (a, s, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final value and output, discarding the final state.
evalRWS :: RWS r w s a -> r -> s -> (a, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final state and output, discarding the final value.
execRWS :: RWS r w s a -> r -> s -> (s, w)

-- | Map the return value, final state and output of a computation using
--   the given function.
--   
--   <ul>
--   <li><pre><a>runRWS</a> (<a>mapRWS</a> f m) r s = f (<a>runRWS</a> m r
--   s)</pre></li>
--   </ul>
mapRWS :: ((a, s, w) -> (b, s, w')) -> RWS r w s a -> RWS r w' s b

-- | <tt><a>withRWS</a> f m</tt> executes action <tt>m</tt> with an initial
--   environment and state modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>runRWS</a> (<a>withRWS</a> f m) r s = <a>uncurry</a>
--   (<a>runRWS</a> m) (f r s)</pre></li>
--   </ul>
withRWS :: (r' -> s -> (r, s)) -> RWS r w s a -> RWS r' w s a

-- | A monad transformer adding reading an environment of type <tt>r</tt>,
--   collecting an output of type <tt>w</tt> and updating a state of type
--   <tt>s</tt> to an inner monad <tt>m</tt>.
newtype RWST r w s m a
RWST :: (r -> s -> m (a, s, w)) -> RWST r w s m a
runRWST :: RWST r w s m a -> r -> s -> m (a, s, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final value and output, discarding the final state.
evalRWST :: Monad m => RWST r w s m a -> r -> s -> m (a, w)

-- | Evaluate a computation with the given initial state and environment,
--   returning the final state and output, discarding the final value.
execRWST :: Monad m => RWST r w s m a -> r -> s -> m (s, w)

-- | Map the inner computation using the given function.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>mapRWST</a> f m) r s = f (<a>runRWST</a> m
--   r s)</pre></li>
--   </ul>
mapRWST :: (m (a, s, w) -> n (b, s, w')) -> RWST r w s m a -> RWST r w' s n b

-- | <tt><a>withRWST</a> f m</tt> executes action <tt>m</tt> with an
--   initial environment and state modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>withRWST</a> f m) r s = <a>uncurry</a>
--   (<a>runRWST</a> m) (f r s)</pre></li>
--   </ul>
withRWST :: (r' -> s -> (r, s)) -> RWST r w s m a -> RWST r' w s m a

-- | Constructor for computations in the reader monad (equivalent to
--   <a>asks</a>).
reader :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

-- | Fetch the value of the environment.
ask :: (Monoid w, Monad m) => RWST r w s m r

-- | Execute a computation in a modified environment
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>local</a> f m) r s = <a>runRWST</a> m (f
--   r) s</pre></li>
--   </ul>
local :: (Monoid w, Monad m) => (r -> r) -> RWST r w s m a -> RWST r w s m a

-- | Retrieve a function of the current environment.
--   
--   <ul>
--   <li><pre><a>asks</a> f = <a>liftM</a> f <a>ask</a></pre></li>
--   </ul>
asks :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

-- | Construct a writer computation from a (result, output) pair.
writer :: Monad m => (a, w) -> RWST r w s m a

-- | <tt><a>tell</a> w</tt> is an action that produces the output
--   <tt>w</tt>.
tell :: (Monoid w, Monad m) => w -> RWST r w s m ()

-- | <tt><a>listen</a> m</tt> is an action that executes the action
--   <tt>m</tt> and adds its output to the value of the computation.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>listen</a> m) r s = <a>liftM</a> (\(a, w)
--   -&gt; ((a, w), w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
listen :: (Monoid w, Monad m) => RWST r w s m a -> RWST r w s m (a, w)

-- | <tt><a>listens</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and adds the result of applying <tt>f</tt> to the output to
--   the value of the computation.
--   
--   <ul>
--   <li><pre><a>listens</a> f m = <a>liftM</a> (id *** f) (<a>listen</a>
--   m)</pre></li>
--   <li><pre><a>runRWST</a> (<a>listens</a> f m) r s = <a>liftM</a> (\(a,
--   w) -&gt; ((a, f w), w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
listens :: (Monoid w, Monad m) => (w -> b) -> RWST r w s m a -> RWST r w s m (a, b)

-- | <tt><a>pass</a> m</tt> is an action that executes the action
--   <tt>m</tt>, which returns a value and a function, and returns the
--   value, applying the function to the output.
--   
--   <ul>
--   <li><pre><a>runRWST</a> (<a>pass</a> m) r s = <a>liftM</a> (\((a, f),
--   w) -&gt; (a, f w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
pass :: (Monoid w, Monad m) => RWST r w s m (a, w -> w) -> RWST r w s m a

-- | <tt><a>censor</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   <ul>
--   <li><pre><a>censor</a> f m = <a>pass</a> (<a>liftM</a> (\x -&gt;
--   (x,f)) m)</pre></li>
--   <li><pre><a>runRWST</a> (<a>censor</a> f m) r s = <a>liftM</a> (\(a,
--   w) -&gt; (a, f w)) (<a>runRWST</a> m r s)</pre></li>
--   </ul>
censor :: (Monoid w, Monad m) => (w -> w) -> RWST r w s m a -> RWST r w s m a

-- | Construct a state monad computation from a state transformer function.
state :: (Monoid w, Monad m) => (s -> (a, s)) -> RWST r w s m a

-- | Fetch the current value of the state within the monad.
get :: (Monoid w, Monad m) => RWST r w s m s

-- | <tt><a>put</a> s</tt> sets the state within the monad to <tt>s</tt>.
put :: (Monoid w, Monad m) => s -> RWST r w s m ()

-- | <tt><a>modify</a> f</tt> is an action that updates the state to the
--   result of applying <tt>f</tt> to the current state.
--   
--   <ul>
--   <li><pre><a>modify</a> f = <a>get</a> &gt;&gt;= (<a>put</a> .
--   f)</pre></li>
--   </ul>
modify :: (Monoid w, Monad m) => (s -> s) -> RWST r w s m ()

-- | Get a specific component of the state, using a projection function
--   supplied.
--   
--   <ul>
--   <li><pre><a>gets</a> f = <a>liftM</a> f <a>get</a></pre></li>
--   </ul>
gets :: (Monoid w, Monad m) => (s -> a) -> RWST r w s m a

-- | Uniform lifting of a <tt>callCC</tt> operation to the new monad. This
--   version rolls back to the original state on entering the continuation.
liftCallCC :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a

-- | In-situ lifting of a <tt>callCC</tt> operation to the new monad. This
--   version uses the current state on entering the continuation.
liftCallCC' :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (a, s, w) -> (e -> m (a, s, w)) -> m (a, s, w)) -> RWST l w s m a -> (e -> RWST l w s m a) -> RWST l w s m a
instance (Monoid w, MonadIO m) => MonadIO (RWST r w s m)
instance Monoid w => MonadTrans (RWST r w s)
instance (Monoid w, MonadFix m) => MonadFix (RWST r w s m)
instance (Monoid w, MonadPlus m) => MonadPlus (RWST r w s m)
instance (Monoid w, Monad m) => Monad (RWST r w s m)
instance (Monoid w, Functor m, MonadPlus m) => Alternative (RWST r w s m)
instance (Monoid w, Functor m, Monad m) => Applicative (RWST r w s m)
instance Functor m => Functor (RWST r w s m)


-- | Lazy state monads, passing an updatable state through a computation.
--   See below for examples.
--   
--   In this version, sequencing of computations is lazy. For a strict
--   version, see <a>Control.Monad.Trans.State.Strict</a>, which has the
--   same interface.
--   
--   Some computations may not require the full power of state
--   transformers:
--   
--   <ul>
--   <li>For a read-only state, see <a>Control.Monad.Trans.Reader</a>.</li>
--   <li>To accumulate a value without using it on the way, see
--   <a>Control.Monad.Trans.Writer</a>.</li>
--   </ul>
module Control.Monad.Trans.State.Lazy

-- | A state monad parameterized by the type <tt>s</tt> of the state to
--   carry.
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
type State s = StateT s Identity

-- | Construct a state monad computation from a function. (The inverse of
--   <a>runState</a>.)
state :: Monad m => (s -> (a, s)) -> StateT s m a

-- | Unwrap a state monad computation as a function. (The inverse of
--   <a>state</a>.)
runState :: State s a -> s -> (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalState</a> m s = <a>fst</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
evalState :: State s a -> s -> a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execState</a> m s = <a>snd</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
execState :: State s a -> s -> s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runState</a> (<a>mapState</a> f m) = f . <a>runState</a>
--   m</pre></li>
--   </ul>
mapState :: ((a, s) -> (b, s)) -> State s a -> State s b

-- | <tt><a>withState</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withState</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withState :: (s -> s) -> State s a -> State s a

-- | A state transformer monad parameterized by:
--   
--   <ul>
--   <li><tt>s</tt> - The state.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
newtype StateT s m a
StateT :: (s -> m (a, s)) -> StateT s m a
runStateT :: StateT s m a -> s -> m (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalStateT</a> m s = <a>liftM</a> <a>fst</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
evalStateT :: Monad m => StateT s m a -> s -> m a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execStateT</a> m s = <a>liftM</a> <a>snd</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
execStateT :: Monad m => StateT s m a -> s -> m s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runStateT</a> (<a>mapStateT</a> f m) = f .
--   <a>runStateT</a> m</pre></li>
--   </ul>
mapStateT :: (m (a, s) -> n (b, s)) -> StateT s m a -> StateT s n b

-- | <tt><a>withStateT</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withStateT</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withStateT :: (s -> s) -> StateT s m a -> StateT s m a

-- | Fetch the current value of the state within the monad.
get :: Monad m => StateT s m s

-- | <tt><a>put</a> s</tt> sets the state within the monad to <tt>s</tt>.
put :: Monad m => s -> StateT s m ()

-- | <tt><a>modify</a> f</tt> is an action that updates the state to the
--   result of applying <tt>f</tt> to the current state.
--   
--   <ul>
--   <li><pre><a>modify</a> f = <a>get</a> &gt;&gt;= (<a>put</a> .
--   f)</pre></li>
--   </ul>
modify :: Monad m => (s -> s) -> StateT s m ()

-- | Get a specific component of the state, using a projection function
--   supplied.
--   
--   <ul>
--   <li><pre><a>gets</a> f = <a>liftM</a> f <a>get</a></pre></li>
--   </ul>
gets :: Monad m => (s -> a) -> StateT s m a

-- | Uniform lifting of a <tt>callCC</tt> operation to the new monad. This
--   version rolls back to the original state on entering the continuation.
liftCallCC :: ((((a, s) -> m (b, s)) -> m (a, s)) -> m (a, s)) -> ((a -> StateT s m b) -> StateT s m a) -> StateT s m a

-- | In-situ lifting of a <tt>callCC</tt> operation to the new monad. This
--   version uses the current state on entering the continuation. It does
--   not satisfy the laws of a monad transformer.
liftCallCC' :: ((((a, s) -> m (b, s)) -> m (a, s)) -> m (a, s)) -> ((a -> StateT s m b) -> StateT s m a) -> StateT s m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (a, s) -> (e -> m (a, s)) -> m (a, s)) -> StateT s m a -> (e -> StateT s m a) -> StateT s m a

-- | Lift a <tt>listen</tt> operation to the new monad.
liftListen :: Monad m => (m (a, s) -> m ((a, s), w)) -> StateT s m a -> StateT s m (a, w)

-- | Lift a <tt>pass</tt> operation to the new monad.
liftPass :: Monad m => (m ((a, s), b) -> m (a, s)) -> StateT s m (a, b) -> StateT s m a
instance MonadIO m => MonadIO (StateT s m)
instance MonadTrans (StateT s)
instance MonadFix m => MonadFix (StateT s m)
instance MonadPlus m => MonadPlus (StateT s m)
instance Monad m => Monad (StateT s m)
instance (Functor m, MonadPlus m) => Alternative (StateT s m)
instance (Functor m, Monad m) => Applicative (StateT s m)
instance Functor m => Functor (StateT s m)


-- | State monads, passing an updatable state through a computation.
--   
--   Some computations may not require the full power of state
--   transformers:
--   
--   <ul>
--   <li>For a read-only state, see <a>Control.Monad.Trans.Reader</a>.</li>
--   <li>To accumulate a value without using it on the way, see
--   <a>Control.Monad.Trans.Writer</a>.</li>
--   </ul>
--   
--   This version is lazy; for a strict version, see
--   <a>Control.Monad.Trans.State.Strict</a>, which has the same interface.
module Control.Monad.Trans.State


-- | Strict state monads, passing an updatable state through a computation.
--   See below for examples.
--   
--   In this version, sequencing of computations is strict. For a lazy
--   version, see <a>Control.Monad.Trans.State.Lazy</a>, which has the same
--   interface.
--   
--   Some computations may not require the full power of state
--   transformers:
--   
--   <ul>
--   <li>For a read-only state, see <a>Control.Monad.Trans.Reader</a>.</li>
--   <li>To accumulate a value without using it on the way, see
--   <a>Control.Monad.Trans.Writer</a>.</li>
--   </ul>
module Control.Monad.Trans.State.Strict

-- | A state monad parameterized by the type <tt>s</tt> of the state to
--   carry.
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
type State s = StateT s Identity

-- | Construct a state monad computation from a function. (The inverse of
--   <a>runState</a>.)
state :: Monad m => (s -> (a, s)) -> StateT s m a

-- | Unwrap a state monad computation as a function. (The inverse of
--   <a>state</a>.)
runState :: State s a -> s -> (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalState</a> m s = <a>fst</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
evalState :: State s a -> s -> a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execState</a> m s = <a>snd</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
execState :: State s a -> s -> s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runState</a> (<a>mapState</a> f m) = f . <a>runState</a>
--   m</pre></li>
--   </ul>
mapState :: ((a, s) -> (b, s)) -> State s a -> State s b

-- | <tt><a>withState</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withState</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withState :: (s -> s) -> State s a -> State s a

-- | A state transformer monad parameterized by:
--   
--   <ul>
--   <li><tt>s</tt> - The state.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
newtype StateT s m a
StateT :: (s -> m (a, s)) -> StateT s m a
runStateT :: StateT s m a -> s -> m (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalStateT</a> m s = <a>liftM</a> <a>fst</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
evalStateT :: Monad m => StateT s m a -> s -> m a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execStateT</a> m s = <a>liftM</a> <a>snd</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
execStateT :: Monad m => StateT s m a -> s -> m s

-- | Map both the return value and final state of a computation using the
--   given function.
--   
--   <ul>
--   <li><pre><a>runStateT</a> (<a>mapStateT</a> f m) = f .
--   <a>runStateT</a> m</pre></li>
--   </ul>
mapStateT :: (m (a, s) -> n (b, s)) -> StateT s m a -> StateT s n b

-- | <tt><a>withStateT</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withStateT</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withStateT :: (s -> s) -> StateT s m a -> StateT s m a

-- | Fetch the current value of the state within the monad.
get :: Monad m => StateT s m s

-- | <tt><a>put</a> s</tt> sets the state within the monad to <tt>s</tt>.
put :: Monad m => s -> StateT s m ()

-- | <tt><a>modify</a> f</tt> is an action that updates the state to the
--   result of applying <tt>f</tt> to the current state.
--   
--   <ul>
--   <li><pre><a>modify</a> f = <a>get</a> &gt;&gt;= (<a>put</a> .
--   f)</pre></li>
--   </ul>
modify :: Monad m => (s -> s) -> StateT s m ()

-- | Get a specific component of the state, using a projection function
--   supplied.
--   
--   <ul>
--   <li><pre><a>gets</a> f = <a>liftM</a> f <a>get</a></pre></li>
--   </ul>
gets :: Monad m => (s -> a) -> StateT s m a

-- | Uniform lifting of a <tt>callCC</tt> operation to the new monad. This
--   version rolls back to the original state on entering the continuation.
liftCallCC :: ((((a, s) -> m (b, s)) -> m (a, s)) -> m (a, s)) -> ((a -> StateT s m b) -> StateT s m a) -> StateT s m a

-- | In-situ lifting of a <tt>callCC</tt> operation to the new monad. This
--   version uses the current state on entering the continuation. It does
--   not satisfy the laws of a monad transformer.
liftCallCC' :: ((((a, s) -> m (b, s)) -> m (a, s)) -> m (a, s)) -> ((a -> StateT s m b) -> StateT s m a) -> StateT s m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (a, s) -> (e -> m (a, s)) -> m (a, s)) -> StateT s m a -> (e -> StateT s m a) -> StateT s m a

-- | Lift a <tt>listen</tt> operation to the new monad.
liftListen :: Monad m => (m (a, s) -> m ((a, s), w)) -> StateT s m a -> StateT s m (a, w)

-- | Lift a <tt>pass</tt> operation to the new monad.
liftPass :: Monad m => (m ((a, s), b) -> m (a, s)) -> StateT s m (a, b) -> StateT s m a
instance MonadIO m => MonadIO (StateT s m)
instance MonadTrans (StateT s)
instance MonadFix m => MonadFix (StateT s m)
instance MonadPlus m => MonadPlus (StateT s m)
instance Monad m => Monad (StateT s m)
instance (Functor m, MonadPlus m) => Alternative (StateT s m)
instance (Functor m, Monad m) => Applicative (StateT s m)
instance Functor m => Functor (StateT s m)


-- | The lazy <a>WriterT</a> monad transformer, which adds collection of
--   outputs (such as a count or string output) to a given monad.
--   
--   This version builds its output lazily; for a strict version, see
--   <a>Control.Monad.Trans.Writer.Strict</a>, which has the same
--   interface.
--   
--   This monad transformer provides only limited access to the output
--   during the computation. For more general access, use
--   <a>Control.Monad.Trans.State</a> instead.
module Control.Monad.Trans.Writer.Lazy

-- | A writer monad parameterized by the type <tt>w</tt> of output to
--   accumulate.
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
type Writer w = WriterT w Identity

-- | Construct a writer computation from a (result, output) pair. (The
--   inverse of <a>runWriter</a>.)
writer :: Monad m => (a, w) -> WriterT w m a

-- | Unwrap a writer computation as a (result, output) pair. (The inverse
--   of <a>writer</a>.)
runWriter :: Writer w a -> (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriter</a> m = <a>snd</a> (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
execWriter :: Writer w a -> w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriter</a> (<a>mapWriter</a> f m) = f (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
mapWriter :: ((a, w) -> (b, w')) -> Writer w a -> Writer w' b

-- | A writer monad parameterized by:
--   
--   <ul>
--   <li><tt>w</tt> - the output to accumulate.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
newtype WriterT w m a
WriterT :: m (a, w) -> WriterT w m a
runWriterT :: WriterT w m a -> m (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriterT</a> m = <a>liftM</a> <a>snd</a>
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
execWriterT :: Monad m => WriterT w m a -> m w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>mapWriterT</a> f m) = f
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
mapWriterT :: (m (a, w) -> n (b, w')) -> WriterT w m a -> WriterT w' n b

-- | <tt><a>tell</a> w</tt> is an action that produces the output
--   <tt>w</tt>.
tell :: (Monoid w, Monad m) => w -> WriterT w m ()

-- | <tt><a>listen</a> m</tt> is an action that executes the action
--   <tt>m</tt> and adds its output to the value of the computation.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>listen</a> m) = <a>liftM</a> (\(a, w)
--   -&gt; ((a, w), w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
listen :: (Monoid w, Monad m) => WriterT w m a -> WriterT w m (a, w)

-- | <tt><a>listens</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and adds the result of applying <tt>f</tt> to the output to
--   the value of the computation.
--   
--   <ul>
--   <li><pre><a>listens</a> f m = <a>liftM</a> (id *** f) (<a>listen</a>
--   m)</pre></li>
--   <li><pre><a>runWriterT</a> (<a>listens</a> f m) = <a>liftM</a> (\(a,
--   w) -&gt; ((a, f w), w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
listens :: (Monoid w, Monad m) => (w -> b) -> WriterT w m a -> WriterT w m (a, b)

-- | <tt><a>pass</a> m</tt> is an action that executes the action
--   <tt>m</tt>, which returns a value and a function, and returns the
--   value, applying the function to the output.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>pass</a> m) = <a>liftM</a> (\((a, f),
--   w) -&gt; (a, f w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
pass :: (Monoid w, Monad m) => WriterT w m (a, w -> w) -> WriterT w m a

-- | <tt><a>censor</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   <ul>
--   <li><pre><a>censor</a> f m = <a>pass</a> (<a>liftM</a> (\x -&gt;
--   (x,f)) m)</pre></li>
--   <li><pre><a>runWriterT</a> (<a>censor</a> f m) = <a>liftM</a> (\(a, w)
--   -&gt; (a, f w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
censor :: (Monoid w, Monad m) => (w -> w) -> WriterT w m a -> WriterT w m a

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: Monoid w => ((((a, w) -> m (b, w)) -> m (a, w)) -> m (a, w)) -> ((a -> WriterT w m b) -> WriterT w m a) -> WriterT w m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (a, w) -> (e -> m (a, w)) -> m (a, w)) -> WriterT w m a -> (e -> WriterT w m a) -> WriterT w m a
instance Traversable f => Traversable (WriterT w f)
instance Foldable f => Foldable (WriterT w f)
instance (Monoid w, MonadIO m) => MonadIO (WriterT w m)
instance Monoid w => MonadTrans (WriterT w)
instance (Monoid w, MonadFix m) => MonadFix (WriterT w m)
instance (Monoid w, MonadPlus m) => MonadPlus (WriterT w m)
instance (Monoid w, Monad m) => Monad (WriterT w m)
instance (Monoid w, Alternative m) => Alternative (WriterT w m)
instance (Monoid w, Applicative m) => Applicative (WriterT w m)
instance Functor m => Functor (WriterT w m)


-- | The WriterT monad transformer. This version is lazy; for a strict
--   version, see <a>Control.Monad.Trans.Writer.Strict</a>, which has the
--   same interface.
module Control.Monad.Trans.Writer


-- | The strict <a>WriterT</a> monad transformer, which adds collection of
--   outputs (such as a count or string output) to a given monad.
--   
--   This version builds its output strictly; for a lazy version, see
--   <a>Control.Monad.Trans.Writer.Lazy</a>, which has the same interface.
--   
--   This monad transformer provides only limited access to the output
--   during the computation. For more general access, use
--   <a>Control.Monad.Trans.State</a> instead.
module Control.Monad.Trans.Writer.Strict

-- | A writer monad parameterized by the type <tt>w</tt> of output to
--   accumulate.
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
type Writer w = WriterT w Identity

-- | Construct a writer computation from a (result, output) pair. (The
--   inverse of <a>runWriter</a>.)
writer :: Monad m => (a, w) -> WriterT w m a

-- | Unwrap a writer computation as a (result, output) pair. (The inverse
--   of <a>writer</a>.)
runWriter :: Writer w a -> (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriter</a> m = <a>snd</a> (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
execWriter :: Writer w a -> w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriter</a> (<a>mapWriter</a> f m) = f (<a>runWriter</a>
--   m)</pre></li>
--   </ul>
mapWriter :: ((a, w) -> (b, w')) -> Writer w a -> Writer w' b

-- | A writer monad parameterized by:
--   
--   <ul>
--   <li><tt>w</tt> - the output to accumulate.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function produces the output <a>mempty</a>, while
--   <tt>&gt;&gt;=</tt> combines the outputs of the subcomputations using
--   <a>mappend</a>.
newtype WriterT w m a
WriterT :: m (a, w) -> WriterT w m a
runWriterT :: WriterT w m a -> m (a, w)

-- | Extract the output from a writer computation.
--   
--   <ul>
--   <li><pre><a>execWriterT</a> m = <a>liftM</a> <a>snd</a>
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
execWriterT :: Monad m => WriterT w m a -> m w

-- | Map both the return value and output of a computation using the given
--   function.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>mapWriterT</a> f m) = f
--   (<a>runWriterT</a> m)</pre></li>
--   </ul>
mapWriterT :: (m (a, w) -> n (b, w')) -> WriterT w m a -> WriterT w' n b

-- | <tt><a>tell</a> w</tt> is an action that produces the output
--   <tt>w</tt>.
tell :: (Monoid w, Monad m) => w -> WriterT w m ()

-- | <tt><a>listen</a> m</tt> is an action that executes the action
--   <tt>m</tt> and adds its output to the value of the computation.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>listen</a> m) = <a>liftM</a> (\(a, w)
--   -&gt; ((a, w), w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
listen :: (Monoid w, Monad m) => WriterT w m a -> WriterT w m (a, w)

-- | <tt><a>listens</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and adds the result of applying <tt>f</tt> to the output to
--   the value of the computation.
--   
--   <ul>
--   <li><pre><a>listens</a> f m = <a>liftM</a> (id *** f) (<a>listen</a>
--   m)</pre></li>
--   <li><pre><a>runWriterT</a> (<a>listens</a> f m) = <a>liftM</a> (\(a,
--   w) -&gt; ((a, f w), w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
listens :: (Monoid w, Monad m) => (w -> b) -> WriterT w m a -> WriterT w m (a, b)

-- | <tt><a>pass</a> m</tt> is an action that executes the action
--   <tt>m</tt>, which returns a value and a function, and returns the
--   value, applying the function to the output.
--   
--   <ul>
--   <li><pre><a>runWriterT</a> (<a>pass</a> m) = <a>liftM</a> (\((a, f),
--   w) -&gt; (a, f w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
pass :: (Monoid w, Monad m) => WriterT w m (a, w -> w) -> WriterT w m a

-- | <tt><a>censor</a> f m</tt> is an action that executes the action
--   <tt>m</tt> and applies the function <tt>f</tt> to its output, leaving
--   the return value unchanged.
--   
--   <ul>
--   <li><pre><a>censor</a> f m = <a>pass</a> (<a>liftM</a> (\x -&gt;
--   (x,f)) m)</pre></li>
--   <li><pre><a>runWriterT</a> (<a>censor</a> f m) = <a>liftM</a> (\(a, w)
--   -&gt; (a, f w)) (<a>runWriterT</a> m)</pre></li>
--   </ul>
censor :: (Monoid w, Monad m) => (w -> w) -> WriterT w m a -> WriterT w m a

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: Monoid w => ((((a, w) -> m (b, w)) -> m (a, w)) -> m (a, w)) -> ((a -> WriterT w m b) -> WriterT w m a) -> WriterT w m a

-- | Lift a <tt>catchError</tt> operation to the new monad.
liftCatch :: (m (a, w) -> (e -> m (a, w)) -> m (a, w)) -> WriterT w m a -> (e -> WriterT w m a) -> WriterT w m a
instance (Monoid w, MonadIO m) => MonadIO (WriterT w m)
instance Monoid w => MonadTrans (WriterT w)
instance (Monoid w, MonadFix m) => MonadFix (WriterT w m)
instance (Monoid w, MonadPlus m) => MonadPlus (WriterT w m)
instance (Monoid w, Monad m) => Monad (WriterT w m)
instance (Monoid w, Alternative m) => Alternative (WriterT w m)
instance (Monoid w, Applicative m) => Applicative (WriterT w m)
instance Traversable f => Traversable (WriterT w f)
instance Foldable f => Foldable (WriterT w f)
instance Functor m => Functor (WriterT w m)


-- | The constant functor.
module Data.Functor.Constant

-- | Constant functor.
newtype Constant a b
Constant :: a -> Constant a b
getConstant :: Constant a b -> a
instance Monoid a => Applicative (Constant a)
instance Traversable (Constant a)
instance Foldable (Constant a)
instance Functor (Constant a)


-- | Adding a new kind of pure computation to an applicative functor.
module Control.Applicative.Lift

-- | Applicative functor formed by adding pure computations to a given
--   applicative functor.
data Lift f a
Pure :: a -> Lift f a
Other :: (f a) -> Lift f a

-- | Projection to the other functor.
unLift :: Applicative f => Lift f a -> f a

-- | An applicative functor that collects a monoid (e.g. lists) of errors.
--   A sequence of computations fails if any of its components do, but
--   unlike monads made with <tt>ErrorT</tt> from
--   <a>Control.Monad.Trans.Error</a>, these computations continue after an
--   error, collecting all the errors.
type Errors e = Lift (Constant e)

-- | Report an error.
failure :: Monoid e => e -> Errors e a
instance Alternative f => Alternative (Lift f)
instance Applicative f => Applicative (Lift f)
instance Traversable f => Traversable (Lift f)
instance Foldable f => Foldable (Lift f)
instance Functor f => Functor (Lift f)


-- | Making functors with an <a>Applicative</a> instance that performs
--   actions in the reverse order.
module Control.Applicative.Backwards

-- | The same functor, but with an <a>Applicative</a> instance that
--   performs actions in the reverse order.
newtype Backwards f a
Backwards :: f a -> Backwards f a
forwards :: Backwards f a -> f a
instance Traversable f => Traversable (Backwards f)
instance Foldable f => Foldable (Backwards f)
instance Alternative f => Alternative (Backwards f)
instance Applicative f => Applicative (Backwards f)
instance Functor f => Functor (Backwards f)


-- | Making functors whose elements are notionally in the reverse order
--   from the original functor.
module Data.Functor.Reverse

-- | The same functor, but with <a>Foldable</a> and <a>Traversable</a>
--   instances that process the elements in the reverse order.
newtype Reverse f a
Reverse :: f a -> Reverse f a
getReverse :: Reverse f a -> f a
instance Traversable f => Traversable (Reverse f)
instance Foldable f => Foldable (Reverse f)
instance Alternative f => Alternative (Reverse f)
instance Applicative f => Applicative (Reverse f)
instance Functor f => Functor (Reverse f)