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

-- | A state monad which allows the state to be saved and restored on a
--   stack.
--   
--   
--   
- Computation type: 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.
--   
- Binding strategy: Same as for the usual state monad; the
--   state and accompanying stack of saved states are threaded through
--   computations.
--   
- Useful for: Remembering state while emitting commands for
--   some system which itself has saveable/restorable state, such as OpenGL
--   or Cairo.
--   
--   
--   Simple example:
--   
--   
--   ghci> let p = get >>= liftIO . print
--   ghci> evalStateStackT (put 2 >> p >> save >> put 3 >> p >> restore >> p) 0
--   2
--   3
--   2
--   
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 :: Type -> Type)
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 :: Type -> Type) a
StateStackT :: StateT (s, [s]) m a -> StateStackT s (m :: Type -> Type) a
[unStateStackT] :: StateStackT s (m :: Type -> Type) a -> StateT (s, [s]) m a
type StateStack s a = StateStackT s Identity a

-- | Run a StateStackT 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 runStateStackT, but discard the final state.
evalStateStackT :: Monad m => StateStackT s m a -> s -> m a

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

-- | Run a StateStack 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 runStateStack, but discard the final state.
evalStateStack :: StateStack s a -> s -> a

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

-- | StateT computations can always be lifted to
--   StateStackT computations which do not manipulate the state
--   stack.
liftState :: forall (m :: Type -> Type) s a. Monad m => StateT s m a -> StateStackT s m a
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Applicative (Control.Monad.StateStack.StateStackT s m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Functor (Control.Monad.StateStack.StateStackT s m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.StateStack.StateStackT s m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.StateStack.StateStackT s m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Monad (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 GHC.Internal.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.State.Strict.StateT s m)
instance Control.Monad.StateStack.MonadStateStack s m => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.StateStack.MonadStateStack s m) => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.StateStack.MonadStateStack s m) => Control.Monad.StateStack.MonadStateStack s (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance GHC.Internal.Base.Monad m => Control.Monad.State.Class.MonadState s (Control.Monad.StateStack.StateStackT s m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.StateStack.StateStackT s)
