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


-- | Simple State-like monad transformer with saveable and restorable state
--   
--   Simple State-like monad transformer where states can be saved to and
--   restored from an internal stack.
@package statestack
@version 0.3.1


-- | A state monad which allows the state to be saved and restored on a
--   stack.
--   
--   <ul>
--   <li><i>Computation type:</i> Computations with implicit access to a
--   read/write state, with additional operations for pushing the current
--   state on a stack and later restoring the state from the top of the
--   stack.</li>
--   <li><i>Binding strategy:</i> Same as for the usual state monad; the
--   state and accompanying stack of saved states are threaded through
--   computations.</li>
--   <li><i>Useful for:</i> Remembering state while emitting commands for
--   some system which itself has saveable/restorable state, such as OpenGL
--   or Cairo.</li>
--   </ul>
--   
--   Simple example:
--   
--   <pre>
--   ghci&gt; let p = get &gt;&gt;= liftIO . print
--   ghci&gt; evalStateStackT (put 2 &gt;&gt; p &gt;&gt; save &gt;&gt; put 3 &gt;&gt; p &gt;&gt; restore &gt;&gt; p) 0
--   2
--   3
--   2
--   </pre>
module Control.Monad.StateStack

-- | Class of monads which support a state along with a stack for saving
--   and restoring states.
class MonadState s m => MonadStateStack s m
save :: MonadStateStack s m => m ()
restore :: MonadStateStack s m => m ()

-- | A monad transformer which adds a save/restorable state to an existing
--   monad.
newtype StateStackT s m a
StateStackT :: StateT (s, [s]) m a -> StateStackT s m a
[unStateStackT] :: StateStackT s m a -> StateT (s, [s]) m a
type StateStack s a = StateStackT s Identity a

-- | Run a <tt>StateStackT</tt> computation from an initial state,
--   resulting in a computation of the underlying monad which yields the
--   return value and final state.
runStateStackT :: Monad m => StateStackT s m a -> s -> m (a, s)

-- | Like <a>runStateStackT</a>, but discard the final state.
evalStateStackT :: Monad m => StateStackT s m a -> s -> m a

-- | Like <a>runStateStackT</a>, but discard the return value and yield
--   only the final state.
execStateStackT :: Monad m => StateStackT s m a -> s -> m s

-- | Run a <tt>StateStack</tt> computation from an initial state, resulting
--   in a pair of the final return value and final state.
runStateStack :: StateStack s a -> s -> (a, s)

-- | Like <a>runStateStack</a>, but discard the final state.
evalStateStack :: StateStack s a -> s -> a

-- | Like <a>runStateStack</a>, but discard the return value and yield only
--   the final state.
execStateStack :: StateStack s a -> s -> s

-- | <tt>StateT</tt> computations can always be lifted to
--   <tt>StateStackT</tt> computations which do not manipulate the state
--   stack.
liftState :: Monad m => StateT s m a -> StateStackT s m a
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.StateStack.StateStackT s m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.StateStack.StateStackT s)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.StateStack.StateStackT s m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.StateStack.StateStackT s m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.StateStack.StateStackT s m)
instance GHC.Base.Monad m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.StateStack.StateStackT s m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Cont.ContT r m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.StateStack.MonadStateStack s m) => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.StateStack.MonadStateStack s m) => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance GHC.Base.Monad m => Control.Monad.State.Class.MonadState s (Control.Monad.StateStack.StateStackT s m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.StateStack.StateStackT s m)