-- 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.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 Functor m => Functor (StateStackT s m)
instance (Monad m, Functor m) => Applicative (StateStackT s m)
instance Monad m => Monad (StateStackT s m)
instance MonadTrans (StateStackT s)
instance MonadIO m => MonadIO (StateStackT s m)
instance MonadCont m => MonadCont (StateStackT s m)
instance (Monoid w, MonadStateStack s m) => MonadStateStack s (WriterT w m)
instance (Monoid w, MonadStateStack s m) => MonadStateStack s (WriterT w m)
instance MonadStateStack s m => MonadStateStack s (StateT s m)
instance MonadStateStack s m => MonadStateStack s (StateT s m)
instance MonadStateStack s m => MonadStateStack s (ReaderT r m)
instance MonadStateStack s m => MonadStateStack s (MaybeT m)
instance MonadStateStack s m => MonadStateStack s (ListT m)
instance MonadStateStack s m => MonadStateStack s (IdentityT m)
instance (Error e, MonadStateStack s m) => MonadStateStack s (ErrorT e m)
instance MonadStateStack s m => MonadStateStack s (ContT r m)
instance Monad m => MonadStateStack s (StateStackT s m)
instance Monad m => MonadState s (StateStackT s m)
instance Newtype (StateStackT s m a) (StateT (s, [s]) m a)