libghc-monads-tf-doc 0.1.0.3-3build1 / usr / share / doc / libghc-monads-tf-doc / html / monads-tf.txt

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


-- | Monad classes, using type families
--   
--   Monad classes using type families, with instances for various 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 is almost a compatible replacement for the
--   <tt>mtl-tf</tt> package.
@package monads-tf
@version 0.1.0.3


-- | Classes for monad transformers.
--   
--   A monad transformer makes 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


-- | The MonadWriter class.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/pubs/springschool.html</a>) Advanced
--   School of Functional Programming, 1995.
module Control.Monad.Writer.Class
class (Monoid (WriterType m), Monad m) => MonadWriter m where type WriterType m where {
    type family WriterType m;
}
tell :: MonadWriter m => WriterType m -> m ()
listen :: MonadWriter m => m a -> m (a, WriterType m)
pass :: MonadWriter m => m (a, WriterType m -> WriterType m) -> m a
listens :: (MonadWriter m) => (WriterType m -> b) -> m a -> m (a, b)
censor :: (MonadWriter m) => (WriterType m -> WriterType m) -> m a -> m a
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Writer.Class.MonadWriter m) => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Writer.Class.MonadWriter m => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Writer.Class.MonadWriter m => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Writer.Class.MonadWriter m => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Writer.Class.MonadWriter m => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Writer.Class.MonadWriter m => Control.Monad.Writer.Class.MonadWriter (Control.Monad.Trans.State.Strict.StateT s m)


-- | Lazy writer monads.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/pubs/springschool.html</a>) Advanced
--   School of Functional Programming, 1995.
module Control.Monad.Writer.Lazy
class (Monoid (WriterType m), Monad m) => MonadWriter m where type WriterType m where {
    type family WriterType m;
}
tell :: MonadWriter m => WriterType m -> m ()
listen :: MonadWriter m => m a -> m (a, WriterType m)
pass :: MonadWriter m => m (a, WriterType m -> WriterType m) -> m a
listens :: (MonadWriter m) => (WriterType m -> b) -> m a -> m (a, b)
censor :: (MonadWriter m) => (WriterType m -> WriterType m) -> m a -> m a

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

-- | 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 a
[runWriterT] :: WriterT w 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


-- | The MonadWriter class.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/pubs/springschool.html</a>) Advanced
--   School of Functional Programming, 1995.
module Control.Monad.Writer


-- | Strict writer monads.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/pubs/springschool.html</a>) Advanced
--   School of Functional Programming, 1995.
module Control.Monad.Writer.Strict
class (Monoid (WriterType m), Monad m) => MonadWriter m where type WriterType m where {
    type family WriterType m;
}
tell :: MonadWriter m => WriterType m -> m ()
listen :: MonadWriter m => m a -> m (a, WriterType m)
pass :: MonadWriter m => m (a, WriterType m -> WriterType m) -> m a
listens :: (MonadWriter m) => (WriterType m -> b) -> m a -> m (a, b)
censor :: (MonadWriter m) => (WriterType m -> WriterType m) -> m a -> m a

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

-- | 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 a
[runWriterT] :: WriterT w 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


-- | MonadState class.
--   
--   This module is inspired by the paper /Functional Programming with
--   Overloading and Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.State.Class

-- | <i>get</i> returns the state from the internals of the monad.
--   
--   <i>put</i> replaces the state inside the monad.
class (Monad m) => MonadState m where type StateType m where {
    type family StateType m;
}
get :: MonadState m => m (StateType m)
put :: MonadState m => StateType m -> m ()

-- | Monadic state transformer.
--   
--   Maps an old state to a new state inside a state monad. The old state
--   is thrown away.
--   
--   <pre>
--   Main&gt; :t modify ((+1) :: Int -&gt; Int)
--   modify (...) :: (MonadState Int a) =&gt; a ()
--   </pre>
--   
--   This says that <tt>modify (+1)</tt> acts over any Monad that is a
--   member of the <tt>MonadState</tt> class, with an <tt>Int</tt> state.
modify :: (MonadState m) => (StateType m -> StateType m) -> m ()

-- | Gets specific component of the state, using a projection function
--   supplied.
gets :: (MonadState m) => (StateType m -> a) -> m a
instance GHC.Base.Monad m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.State.Lazy.StateT s m)
instance GHC.Base.Monad m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Control.Monad.State.Class.MonadState (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monad m, GHC.Base.Monoid w) => Control.Monad.State.Class.MonadState (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.State.Class.MonadState m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Cont.ContT r m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.State.Class.MonadState m) => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.State.Class.MonadState m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.State.Class.MonadState m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.List.ListT m)
instance Control.Monad.State.Class.MonadState m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.State.Class.MonadState m => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monoid w, Control.Monad.State.Class.MonadState m) => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.State.Class.MonadState m) => Control.Monad.State.Class.MonadState (Control.Monad.Trans.Writer.Strict.WriterT w m)


-- | Lazy state monads.
--   
--   This module is inspired by the paper /Functional Programming with
--   Overloading and Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.State.Lazy

-- | <i>get</i> returns the state from the internals of the monad.
--   
--   <i>put</i> replaces the state inside the monad.
class (Monad m) => MonadState m where type StateType m where {
    type family StateType m;
}
get :: MonadState m => m (StateType m)
put :: MonadState m => StateType m -> m ()

-- | Monadic state transformer.
--   
--   Maps an old state to a new state inside a state monad. The old state
--   is thrown away.
--   
--   <pre>
--   Main&gt; :t modify ((+1) :: Int -&gt; Int)
--   modify (...) :: (MonadState Int a) =&gt; a ()
--   </pre>
--   
--   This says that <tt>modify (+1)</tt> acts over any Monad that is a
--   member of the <tt>MonadState</tt> class, with an <tt>Int</tt> state.
modify :: (MonadState m) => (StateType m -> StateType m) -> m ()

-- | Gets specific component of the state, using a projection function
--   supplied.
gets :: (MonadState m) => (StateType m -> a) -> m a

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

-- | 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 a
[runStateT] :: StateT s 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


-- | Strict state monads.
--   
--   This module is inspired by the paper /Functional Programming with
--   Overloading and Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.State.Strict

-- | <i>get</i> returns the state from the internals of the monad.
--   
--   <i>put</i> replaces the state inside the monad.
class (Monad m) => MonadState m where type StateType m where {
    type family StateType m;
}
get :: MonadState m => m (StateType m)
put :: MonadState m => StateType m -> m ()

-- | Monadic state transformer.
--   
--   Maps an old state to a new state inside a state monad. The old state
--   is thrown away.
--   
--   <pre>
--   Main&gt; :t modify ((+1) :: Int -&gt; Int)
--   modify (...) :: (MonadState Int a) =&gt; a ()
--   </pre>
--   
--   This says that <tt>modify (+1)</tt> acts over any Monad that is a
--   member of the <tt>MonadState</tt> class, with an <tt>Int</tt> state.
modify :: (MonadState m) => (StateType m -> StateType m) -> m ()

-- | Gets specific component of the state, using a projection function
--   supplied.
gets :: (MonadState m) => (StateType m -> a) -> m a

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

-- | 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 a
[runStateT] :: StateT s 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


-- | State monads.
--   
--   This module is inspired by the paper /Functional Programming with
--   Overloading and Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.State


-- | <ul>
--   <li><i>Computation type:</i> Computations which read values from a
--   shared environment.</li>
--   <li><i>Binding strategy:</i> Monad values are functions from the
--   environment to a value. The bound function is applied to the bound
--   value, and both have access to the shared environment.</li>
--   <li><i>Useful for:</i> Maintaining variable bindings, or other shared
--   environment.</li>
--   <li><i>Zero and plus:</i> None.</li>
--   <li><i>Example type:</i> <tt><tt>Reader</tt> [(String,Value)]
--   a</tt></li>
--   </ul>
--   
--   The <tt>Reader</tt> monad (also called the Environment monad).
--   Represents a computation, which can read values from a shared
--   environment, pass values from function to function, and execute
--   sub-computations in a modified environment. Using <tt>Reader</tt>
--   monad for such computations is often clearer and easier than using the
--   <a>State</a> monad.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.Reader.Class

-- | See examples in <a>Control.Monad.Reader</a>. Note, the partially
--   applied function type <tt>(-&gt;) r</tt> is a simple reader monad. See
--   the <tt>instance</tt> declaration below.
class (Monad m) => MonadReader m where type EnvType m where {
    type family EnvType m;
}

-- | Retrieves the monad environment.
ask :: MonadReader m => m (EnvType m)

-- | Executes a computation in a modified environment.
local :: MonadReader m => (EnvType m -> EnvType m) -> m a -> m a

-- | Retrieves a function of the current environment.
asks :: (MonadReader m) => (EnvType m -> a) -> m a
instance Control.Monad.Reader.Class.MonadReader ((->) r)
instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Reader.Class.MonadReader m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Cont.ContT r m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Reader.Class.MonadReader m) => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Reader.Class.MonadReader m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Reader.Class.MonadReader m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Reader.Class.MonadReader m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Reader.Class.MonadReader m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Reader.Class.MonadReader m => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Reader.Class.MonadReader m) => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Reader.Class.MonadReader m) => Control.Monad.Reader.Class.MonadReader (Control.Monad.Trans.Writer.Strict.WriterT w m)


-- | <ul>
--   <li><i>Computation type:</i> Computations which read values from a
--   shared environment.</li>
--   <li><i>Binding strategy:</i> Monad values are functions from the
--   environment to a value. The bound function is applied to the bound
--   value, and both have access to the shared environment.</li>
--   <li><i>Useful for:</i> Maintaining variable bindings, or other shared
--   environment.</li>
--   <li><i>Zero and plus:</i> None.</li>
--   <li><i>Example type:</i> <tt><a>Reader</a> [(String,Value)]
--   a</tt></li>
--   </ul>
--   
--   The <a>Reader</a> monad (also called the Environment monad).
--   Represents a computation, which can read values from a shared
--   environment, pass values from function to function, and execute
--   sub-computations in a modified environment. Using <a>Reader</a> monad
--   for such computations is often clearer and easier than using the
--   <a>State</a> monad.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.Reader

-- | See examples in <a>Control.Monad.Reader</a>. Note, the partially
--   applied function type <tt>(-&gt;) r</tt> is a simple reader monad. See
--   the <tt>instance</tt> declaration below.
class (Monad m) => MonadReader m where type EnvType m where {
    type family EnvType m;
}

-- | Retrieves the monad environment.
ask :: MonadReader m => m (EnvType m)

-- | Executes a computation in a modified environment.
local :: MonadReader m => (EnvType m -> EnvType m) -> m a -> m a

-- | Retrieves a function of the current environment.
asks :: (MonadReader m) => (EnvType m -> a) -> m a

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

-- | 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 k r (m :: k -> *) (a :: k) :: forall k. * -> (k -> *) -> k -> *
ReaderT :: (r -> m a) -> ReaderT k r
[runReaderT] :: ReaderT k r -> 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 k1 r m a -> ReaderT k 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 k r m a -> ReaderT k r' m a


-- | Declaration of the MonadRWS class.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.RWS.Class
class (Monoid (WriterType m), MonadReader m, MonadWriter m, MonadState m) => MonadRWS m
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.RWS.Class.MonadRWS (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Monad.RWS.Class.MonadRWS (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.RWS.Class.MonadRWS m) => Control.Monad.RWS.Class.MonadRWS (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.RWS.Class.MonadRWS m => Control.Monad.RWS.Class.MonadRWS (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.RWS.Class.MonadRWS m => Control.Monad.RWS.Class.MonadRWS (Control.Monad.Trans.Maybe.MaybeT m)


-- | Lazy RWS monad.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.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

-- | 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 a
[runRWST] :: RWST r w s 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


-- | Strict RWS monad.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.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

-- | 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 a
[runRWST] :: RWST r w s 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


-- | Declaration of the MonadRWS class.
--   
--   Inspired by the paper /Functional Programming with Overloading and
--   Higher-Order Polymorphism/, Mark P Jones
--   (<a>http://web.cecs.pdx.edu/~mpj/</a>) Advanced School of Functional
--   Programming, 1995.
module Control.Monad.RWS


-- | The List monad.
module Control.Monad.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 a
[runListT] :: ListT 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


-- | <ul>
--   <li><i>Computation type:</i> Simple function application.</li>
--   <li><i>Binding strategy:</i> The bound function is applied to the
--   input value. <tt><a>Identity</a> x &gt;&gt;= f == <a>Identity</a> (f
--   x)</tt></li>
--   <li><i>Useful for:</i> Monads can be derived from monad transformers
--   applied to the <a>Identity</a> monad.</li>
--   <li><i>Zero and plus:</i> None.</li>
--   <li><i>Example type:</i> <tt><a>Identity</a> a</tt></li>
--   </ul>
--   
--   The <tt>Identity</tt> monad is a monad that does not embody any
--   computational strategy. It simply applies the bound function to its
--   input without any modification. Computationally, there is no reason to
--   use the <tt>Identity</tt> monad instead of the much simpler act of
--   simply applying functions to their arguments. The purpose of the
--   <tt>Identity</tt> monad is its fundamental role in the theory of monad
--   transformers. Any monad transformer applied to the <tt>Identity</tt>
--   monad yields a non-transformer version of that monad.
module Control.Monad.Identity


-- | <ul>
--   <li><i>Computation type:</i> Computations which may fail or throw
--   exceptions.</li>
--   <li><i>Binding strategy:</i> Failure records information about the
--   cause/location of the failure. Failure values bypass the bound
--   function, other values are used as inputs to the bound function.</li>
--   <li><i>Useful for:</i> Building computations from sequences of
--   functions that may fail or using exception handling to structure error
--   handling.</li>
--   <li><i>Zero and plus:</i> Zero is represented by an empty error and
--   the plus operation executes its second argument if the first
--   fails.</li>
--   <li><i>Example type:</i> <tt><a>Either</a> <a>String</a> a</tt></li>
--   </ul>
--   
--   The Error monad (also called the Exception monad).
module Control.Monad.Error.Class

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

-- | Creates an exception without a message. The default implementation is
--   <tt><a>strMsg</a> ""</tt>.
noMsg :: Error a => a

-- | Creates an exception with a message. The default implementation of
--   <tt><a>strMsg</a> s</tt> is <a>noMsg</a>.
strMsg :: Error a => String -> a

-- | The strategy of combining computations that can throw exceptions by
--   bypassing bound functions from the point an exception is thrown to the
--   point that it is handled.
--   
--   Is parameterized over the type of error information and the monad type
--   constructor. It is common to use <tt><a>Either</a> String</tt> as the
--   monad type constructor for an error monad in which error descriptions
--   take the form of strings. In that case and many other common cases the
--   resulting monad is already defined as an instance of the
--   <a>MonadError</a> class. You can also define your own error type
--   and/or use a monad type constructor other than <tt><a>Either</a>
--   String</tt> or <tt><a>Either</a> IOError</tt>. In these cases you will
--   have to explicitly define instances of the <a>Error</a> and/or
--   <a>MonadError</a> classes.
class (Monad m) => MonadError m where type ErrorType m where {
    type family ErrorType m;
}

-- | Is used within a monadic computation to begin exception processing.
throwError :: MonadError m => ErrorType m -> m a

-- | A handler function to handle previous errors and return to normal
--   execution. A common idiom is:
--   
--   <pre>
--   do { action1; action2; action3 } `catchError` handler
--   </pre>
--   
--   where the <tt>action</tt> functions can call <a>throwError</a>. Note
--   that <tt>handler</tt> and the do-block must have the same return type.
catchError :: MonadError m => m a -> (ErrorType m -> m a) -> m a
instance Control.Monad.Error.Class.MonadError GHC.Types.IO
instance Control.Monad.Trans.Error.Error e => Control.Monad.Error.Class.MonadError (Data.Either.Either e)
instance (GHC.Base.Monad m, Control.Monad.Trans.Error.Error e) => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Error.Class.MonadError m => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Error.Class.MonadError m => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Error.Class.MonadError m => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Error.Class.MonadError m => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monoid w, Control.Monad.Error.Class.MonadError m) => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Error.Class.MonadError m) => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Error.Class.MonadError m => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Error.Class.MonadError m => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Error.Class.MonadError m) => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Error.Class.MonadError m) => Control.Monad.Error.Class.MonadError (Control.Monad.Trans.Writer.Strict.WriterT w m)


-- | <ul>
--   <li><i>Computation type:</i> Computations which may fail or throw
--   exceptions.</li>
--   <li><i>Binding strategy:</i> Failure records information about the
--   cause/location of the failure. Failure values bypass the bound
--   function, other values are used as inputs to the bound function.</li>
--   <li><i>Useful for:</i> Building computations from sequences of
--   functions that may fail or using exception handling to structure error
--   handling.</li>
--   <li><i>Zero and plus:</i> Zero is represented by an empty error and
--   the plus operation executes its second argument if the first
--   fails.</li>
--   <li><i>Example type:</i> <tt><a>Either</a> String a</tt></li>
--   </ul>
--   
--   The Error monad (also called the Exception monad).
module Control.Monad.Error

-- | The strategy of combining computations that can throw exceptions by
--   bypassing bound functions from the point an exception is thrown to the
--   point that it is handled.
--   
--   Is parameterized over the type of error information and the monad type
--   constructor. It is common to use <tt><a>Either</a> String</tt> as the
--   monad type constructor for an error monad in which error descriptions
--   take the form of strings. In that case and many other common cases the
--   resulting monad is already defined as an instance of the
--   <a>MonadError</a> class. You can also define your own error type
--   and/or use a monad type constructor other than <tt><a>Either</a>
--   String</tt> or <tt><a>Either</a> IOError</tt>. In these cases you will
--   have to explicitly define instances of the <a>Error</a> and/or
--   <a>MonadError</a> classes.
class (Monad m) => MonadError m where type ErrorType m where {
    type family ErrorType m;
}

-- | Is used within a monadic computation to begin exception processing.
throwError :: MonadError m => ErrorType m -> m a

-- | A handler function to handle previous errors and return to normal
--   execution. A common idiom is:
--   
--   <pre>
--   do { action1; action2; action3 } `catchError` handler
--   </pre>
--   
--   where the <tt>action</tt> functions can call <a>throwError</a>. Note
--   that <tt>handler</tt> and the do-block must have the same return type.
catchError :: MonadError m => m a -> (ErrorType m -> m a) -> m a

-- | An exception to be thrown.
--   
--   Minimal complete definition: <a>noMsg</a> or <a>strMsg</a>.
class Error 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 a
[runErrorT] :: ErrorT e 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


-- | <ul>
--   <li><i>Computation type:</i> Computations which can be interrupted and
--   resumed.</li>
--   <li><i>Binding strategy:</i> Binding a function to a monadic value
--   creates a new continuation which uses the function as the continuation
--   of the monadic computation.</li>
--   <li><i>Useful for:</i> Complex control structures, error handling, and
--   creating co-routines.</li>
--   <li><i>Zero and plus:</i> None.</li>
--   <li><i>Example type:</i> <tt><tt>Cont</tt> r a</tt></li>
--   </ul>
--   
--   The Continuation monad represents computations in continuation-passing
--   style (CPS). In continuation-passing style function result is not
--   returned, but instead is passed to another function, received as a
--   parameter (continuation). Computations are built up from sequences of
--   nested continuations, terminated by a final continuation (often
--   <tt>id</tt>) which produces the final result. Since continuations are
--   functions which represent the future of a computation, manipulation of
--   the continuation functions can achieve complex manipulations of the
--   future of the computation, such as interrupting a computation in the
--   middle, aborting a portion of a computation, restarting a computation,
--   and interleaving execution of computations. The Continuation monad
--   adapts CPS to the structure of a monad.
--   
--   Before using the Continuation monad, be sure that you have a firm
--   understanding of continuation-passing style and that continuations
--   represent the best solution to your particular design problem. Many
--   algorithms which require continuations in other languages do not
--   require them in Haskell, due to Haskell's lazy semantics. Abuse of the
--   Continuation monad can produce code that is impossible to understand
--   and maintain.
module Control.Monad.Cont.Class
class (Monad m) => MonadCont m

-- | <tt>callCC</tt> (call-with-current-continuation) calls a function with
--   the current continuation as its argument. Provides an escape
--   continuation mechanism for use with Continuation monads. Escape
--   continuations 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>Error</a> monad. Advantage of this
--   function over calling <tt>return</tt> is that it makes the
--   continuation explicit, allowing more flexibility and better control
--   (see examples in <a>Control.Monad.Cont</a>).
--   
--   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 :: MonadCont m => ((a -> m b) -> m a) -> m a
instance Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Cont.ContT r m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Cont.Class.MonadCont m) => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monoid w, Control.Monad.Cont.Class.MonadCont m) => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Cont.Class.MonadCont m) => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Cont.Class.MonadCont m) => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Cont.Class.MonadCont m) => Control.Monad.Cont.Class.MonadCont (Control.Monad.Trans.Writer.Strict.WriterT w m)


-- | <ul>
--   <li><i>Computation type:</i> Computations which can be interrupted and
--   resumed.</li>
--   <li><i>Binding strategy:</i> Binding a function to a monadic value
--   creates a new continuation which uses the function as the continuation
--   of the monadic computation.</li>
--   <li><i>Useful for:</i> Complex control structures, error handling, and
--   creating co-routines.</li>
--   <li><i>Zero and plus:</i> None.</li>
--   <li><i>Example type:</i> <tt><a>Cont</a> r a</tt></li>
--   </ul>
--   
--   The Continuation monad represents computations in continuation-passing
--   style (CPS). In continuation-passing style function result is not
--   returned, but instead is passed to another function, received as a
--   parameter (continuation). Computations are built up from sequences of
--   nested continuations, terminated by a final continuation (often
--   <tt>id</tt>) which produces the final result. Since continuations are
--   functions which represent the future of a computation, manipulation of
--   the continuation functions can achieve complex manipulations of the
--   future of the computation, such as interrupting a computation in the
--   middle, aborting a portion of a computation, restarting a computation,
--   and interleaving execution of computations. The Continuation monad
--   adapts CPS to the structure of a monad.
--   
--   Before using the Continuation monad, be sure that you have a firm
--   understanding of continuation-passing style and that continuations
--   represent the best solution to your particular design problem. Many
--   algorithms which require continuations in other languages do not
--   require them in Haskell, due to Haskell's lazy semantics. Abuse of the
--   Continuation monad can produce code that is impossible to understand
--   and maintain.
module Control.Monad.Cont
class (Monad m) => MonadCont m

-- | <tt>callCC</tt> (call-with-current-continuation) calls a function with
--   the current continuation as its argument. Provides an escape
--   continuation mechanism for use with Continuation monads. Escape
--   continuations 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>Error</a> monad. Advantage of this
--   function over calling <tt>return</tt> is that it makes the
--   continuation explicit, allowing more flexibility and better control
--   (see examples in <a>Control.Monad.Cont</a>).
--   
--   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 :: MonadCont m => ((a -> m b) -> m a) -> m a

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

-- | The result of running a CPS computation with a given final
--   continuation. (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 any type constructor: the <a>Monad</a> instance and most
--   of the operations do not require <tt>m</tt> to be a monad.
--   
--   <a>ContT</a> is not a functor on the category of monads, and many
--   operations cannot be lifted through it.
newtype ContT k (r :: k) (m :: k -> *) a :: forall k. k -> (k -> *) -> * -> *
ContT :: ((a -> m r) -> m r) -> ContT k a
[runContT] :: ContT k a -> (a -> m r) -> m r

-- | Apply a function to transform the result of a continuation-passing
--   computation. This has a more restricted type than the <tt>map</tt>
--   operations for other monad transformers, because <a>ContT</a> does not
--   define a functor in the category of monads.
--   
--   <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 k r m a -> ContT k 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 k r m a -> ContT k r m b