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


-- | Phantom State Transformer. Like State Monad, but without values.
--   
--   A monad transformer that mimics the State Monad Transformer from the
--   <a>transformers</a> package, but dropping the values. In those cases
--   that you want to use the State Monad but you only care about effects
--   and how the state changes, use this library to earn a plus of
--   efficiency.
@package phantom-state
@version 0.2.1.2


-- | Phantom State Transformer type and functions.
module Control.Applicative.PhantomState

-- | The Phantom State Transformer is like the State Monad Transformer, but
--   it does not hold any value. Therefore, it automatically discards the
--   result of any computation. Only changes in the state and effects will
--   remain. This transformer produces a new <a>Applicative</a> functor
--   from any <a>Monad</a>. The primitive operations in this functor are:
--   
--   <ul>
--   <li><a>useState</a>: Performs effects. State is unchanged.</li>
--   <li><a>changeState</a>: Changes state. No effect is performed.</li>
--   <li><a>useAndChangeState</a>: Changes state and performs effects.</li>
--   </ul>
--   
--   Although <a>useState</a> and <a>changeState</a> are defined in terms
--   of <a>useAndChangeState</a>:
--   
--   <pre>
--      useState f = useAndChangeState (\s -&gt; f s *&gt; pure s)
--   changeState f = useAndChangeState (pure . f)
--   </pre>
--   
--   So <a>useAndChangeState</a> is the only actual primitive.
--   
--   Use <a>runPhantomStateT</a> (or <a>runPhantomState</a>) to get the
--   result of a phantom state computation.
data PhantomStateT s m a

-- | Type synonym of <a>PhantomStateT</a> where the underlying <a>Monad</a>
--   is the <a>Identity</a> monad.
type PhantomState s = PhantomStateT s Identity

-- | Perform an applicative action using the current state, leaving the
--   state unchanged. The result will be discarded, so only the effect will
--   remain.
useState :: Applicative m => (s -> m a) -> PhantomStateT s m ()

-- | Modify the state using a pure function. No effect will be produced,
--   only the state will be modified.
changeState :: Applicative m => (s -> s) -> PhantomStateT s m ()

-- | Combination of <a>useState</a> and <a>changeState</a>. It allows you
--   to change the state while performing any effects. The new state will
--   be the result of applying the argument function to the old state. The
--   following equations hold:
--   
--   <pre>
--      useState f *&gt; changeState g }
--                                  } = useAndChangeState (\s -&gt; f s *&gt; g s)
--   changeState g *&gt;    useState f }
--   </pre>
useAndChangeState :: (s -> m s) -> PhantomStateT s m ()

-- | Perform a phantom state computation by setting an initial state and
--   running all the actions from there.
runPhantomStateT :: PhantomStateT s m a -> s -> m s

-- | Specialized version of <a>runPhantomStateT</a> where the underlying
--   <a>Monad</a> is the <a>Identity</a> monad.
runPhantomState :: PhantomState s a -> s -> s
instance GHC.Base.Functor (Control.Applicative.PhantomState.PhantomStateT s m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Applicative.PhantomState.PhantomStateT s m)
instance (GHC.Base.Monad m, GHC.Base.Alternative m) => GHC.Base.Alternative (Control.Applicative.PhantomState.PhantomStateT s m)