-- 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://wiki.haskell.org/Operational</a>
--   for a more detailed introduction and features.
--   
--   Related packages:
--   
--   <ul>
--   <li>MonadPrompt —
--   <a>http://hackage.haskell.org/package/MonadPrompt</a></li>
--   <li>free — <a>http://hackage.haskell.org/package/free</a></li>
--   <li>free-operational —
--   <a>http://hackage.haskell.org/package/free-operational</a></li>
--   </ul>
@package operational
@version 0.2.4.2

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 :: forall instr m b. 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

-- | Extend a mapping of instructions to a mapping of <a>ProgramT</a>.
mapInstr :: forall instr1 instr2 m a. Monad m => (forall x. instr1 x -> instr2 x) -> ProgramT instr1 m a -> ProgramT instr2 m a

-- | Utilitiy function for mapping a <a>ProgramViewT</a> back into a
--   <a>ProgramT</a>.
--   
--   Semantically, the function <a>unviewT</a> is an inverse of
--   <a>viewT</a>, e.g. we have
--   
--   <pre>
--   viewT (singleton i) &gt;&gt;= unviewT = return (singleton i)
--   </pre>
unviewT :: Monad m => ProgramViewT instr m a -> ProgramT instr m a

-- | Utility function that extends a given interpretation of instructions
--   as monadic actions to an interpration of <a>ProgramT</a>s as monadic
--   actions.
--   
--   Ideally, you would not use another monad, but write a custom
--   interpreter directly with <a>viewT</a>. See the remark at
--   <a>interpretWithMonad</a>.
interpretWithMonadT :: Monad m => (forall x. instr x -> m x) -> ProgramT instr m a -> m a
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Monad.Operational.ProgramViewT instr m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Operational.ProgramViewT instr m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Operational.ProgramViewT instr m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Operational.ProgramT instr m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Operational.ProgramT instr)
instance GHC.Base.Monad m => GHC.Base.Functor (Control.Monad.Operational.ProgramT instr m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Operational.ProgramT instr m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Operational.ProgramT instr m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Operational.ProgramT instr m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Operational.ProgramT instr m)