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


-- | A monad for commanders
--   
--   A monad for commanders.
@package commandert
@version 0.1.0.1


module Control.Monad.Commander

-- | A <a>CommanderT</a> action is a metaphor for a military commander. At
--   each step, we have a new <a>Action</a> to take, or we could have
--   experienced <a>Defeat</a>, or we can see <a>Victory</a>. While a real
--   life commander worries about moving his troops around in order to
--   achieve a victory in battle, a <a>CommanderT</a> worries about
--   iteratively transforming a state to find some value.
--   
--   In more practical terms, a term of type <a>CommanderT</a> can be
--   thought of as a backtracking, stateful computation which can either
--   result in a result being produced, or nothing being produced. It is a
--   <a>Monad</a> for any base <a>Functor</a> you want to use as the effect
--   inside of the stateful computation, similarly to the free monad.
data CommanderT state f a
Action :: (state -> f (CommanderT state f a, state)) -> CommanderT state f a
Defeat :: CommanderT state f a
Victory :: a -> CommanderT state f a

-- | We can run a <a>CommanderT</a> on some state and see if it has a
--   successful campaign.
runCommanderT :: Monad m => CommanderT state m a -> state -> m (Maybe a)

-- | We can go from a non-<a>Functor</a> to a <a>Functor</a> inside of a
--   <a>CommanderT</a> action. This does the transformation "top to
--   bottom", as opposed to <a>hoistFromFunctor</a>, which does it "bottom
--   to top". If your natural transformation is lessening, i.e. it trims
--   branching structure, then you probably want to use this function.
hoistToFunctor :: Functor g => (forall a. f a -> g a) -> CommanderT state f a -> CommanderT state g a

-- | We can go from a <a>Functor</a> to a non-<a>Functor</a> inside of a
--   <a>CommanderT</a> action. This does the transformation "bottom to
--   top", as opposed to <a>hoistToFunctor</a>, which does it "top to
--   bottom". If your natural transformation is increasing, i.e. it adds
--   branching structure, then you probably want to use this function.
hoistFromFunctor :: Functor f => (forall a. f a -> g a) -> CommanderT state f a -> CommanderT state g a
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Monad.Commander.CommanderT state f)
instance GHC.Base.Functor f => GHC.Base.Applicative (Control.Monad.Commander.CommanderT state f)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Commander.CommanderT state)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Commander.CommanderT state m)
instance GHC.Base.Functor f => GHC.Base.Monad (Control.Monad.Commander.CommanderT state f)
instance GHC.Base.Functor f => GHC.Base.Alternative (Control.Monad.Commander.CommanderT state f)