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


-- | Implementation of difficult monads made easy
with operational semantics.
--   
--   This library makes it easy to implement monads with tricky control
--   flow.
--   
--   This is useful for: writing web applications in a sequential style,
--   programming games with a uniform interface for human and AI players
--   and easy replay capababilities, implementing fast parser monads,
--   designing monadic DSLs, etc.
--   
--   See the project homepage
--   <a>http://haskell.org/haskellwiki/Operational</a> for a more detailed
--   introduction and features.
--   
--   Related packages: MonadPrompt
--   <a>http://hackage.haskell.org/package/MonadPrompt</a>.
@package operational
@version 0.2.2.1

module Control.Monad.Operational

-- | The abstract data type <tt><a>Program</a> instr a</tt> represents
--   programs, i.e. sequences of primitive instructions.
--   
--   <ul>
--   <li>The <i>primitive instructions</i> are given by the type
--   constructor <tt>instr :: * -&gt; *</tt>.</li>
--   <li><tt>a</tt> is the return type of a program.</li>
--   </ul>
--   
--   <tt><a>Program</a> instr</tt> is always a monad and automatically
--   obeys the monad laws.
type Program instr = ProgramT instr Identity

-- | Program made from a single primitive instruction.
singleton :: instr a -> ProgramT instr m a

-- | View type for inspecting the first instruction. It has two
--   constructors <a>Return</a> and <tt>:&gt;&gt;=</tt>. (For technical
--   reasons, they are documented at <a>ProgramViewT</a>.)
type ProgramView instr = ProgramViewT instr Identity

-- | View function for inspecting the first instruction.
view :: Program instr a -> ProgramView instr a

-- | Utility function that extends a given interpretation of instructions
--   as monadic actions to an interpration of <a>Program</a>s as monadic
--   actions.
--   
--   This function can be useful if you are mainly interested in mapping a
--   <a>Program</a> to different standard monads, like the state monad. For
--   implementing a truly custom monad, you should write your interpreter
--   directly with <a>view</a> instead.
interpretWithMonad :: Monad m => (forall a. instr a -> m a) -> (Program instr b -> m b)

-- | The abstract data type <tt><a>ProgramT</a> instr m a</tt> represents
--   programs over a base monad <tt>m</tt>, i.e. sequences of primitive
--   instructions and actions from the base monad.
--   
--   <ul>
--   <li>The <i>primitive instructions</i> are given by the type
--   constructor <tt>instr :: * -&gt; *</tt>.</li>
--   <li><tt>m</tt> is the base monad, embedded with <a>lift</a>.</li>
--   <li><tt>a</tt> is the return type of a program.</li>
--   </ul>
--   
--   <tt><a>ProgramT</a> instr m</tt> is a monad transformer and
--   automatically obeys both the monad and the lifting laws.
data ProgramT instr m a

-- | View type for inspecting the first instruction. This is very similar
--   to pattern matching on lists.
--   
--   <ul>
--   <li>The case <tt>(Return a)</tt> means that the program contains no
--   instructions and just returns the result <tt>a</tt>.</li>
--   <li>The case <tt>(someInstruction :&gt;&gt;= k)</tt> means that the
--   first instruction is <tt>someInstruction</tt> and the remaining
--   program is given by the function <tt>k</tt>.</li>
--   </ul>
data ProgramViewT instr m a
Return :: a -> ProgramViewT instr m a
(:>>=) :: instr b -> (b -> ProgramT instr m a) -> ProgramViewT instr m a

-- | View function for inspecting the first instruction.
viewT :: Monad m => ProgramT instr m a -> m (ProgramViewT instr m a)

-- | Lift a plain sequence of instructions to a sequence of instructions
--   over a monad <tt>m</tt>. This is the counterpart of the <a>lift</a>
--   function from <a>MonadTrans</a>.
--   
--   It can be defined as follows:
--   
--   <pre>
--   liftProgram = eval . view
--       where
--       eval :: ProgramView instr a -&gt; ProgramT instr m a
--       eval (Return a) = return a
--       eval (i :&gt;&gt;= k) = singleton i &gt;&gt;= liftProgram . k
--   </pre>
liftProgram :: Monad m => Program instr a -> ProgramT instr m a
instance MonadIO m => MonadIO (ProgramT instr m)
instance MonadState s m => MonadState s (ProgramT instr m)
instance Monad m => Applicative (ProgramT instr m)
instance Monad m => Functor (ProgramT instr m)
instance MonadTrans (ProgramT instr)
instance Monad m => Monad (ProgramT instr m)