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


-- | Implement monads by specifying operational semantics.
--   
--   Tiny library for implementing monads by specifying the primitive
--   instructions and their operational semantics. The monad laws will hold
--   automatically. Can also be used to define monad transformers, and the
--   lifting laws are, again, automatic.
--   
--   Accompanies the article: "The Operational Monad Tutorial", published
--   in Issue 15 of The Monad.Reader
--   <a>http://themonadreader.wordpress.com/2010/01/26/issue-15/</a>.
--   
--   Related packages: MonadPrompt
--   <a>http://hackage.haskell.org/package/MonadPrompt</a>.
@package operational
@version 0.2.0.3


-- | Implement monads by specifying primitive instructions and their
--   operational semantics.
--   
--   This package is based on the "The Operational Monad Tutorial",
--   published in Issue 15 of The Monad.Reader
--   <a>http://themonadreader.wordpress.com/</a>.
--   
--   You are reading the API reference. For more thorough documentation
--   including design and implementation notes as well as a correctness
--   proof, please consult the included documentation in
--   <tt>doc/Documentation.md</tt>, also available at
--   <a>http://heinrichapfelmus.github.com/operational/Documentation.html</a>
--   .
--   
--   This API reference includes only basic example code. More intricate
--   examples are available in the <tt>doc/examples</tt> directory, also
--   available at
--   <a>https://github.com/HeinrichApfelmus/operational/tree/master/doc/examples#readme</a>.
module Control.Monad.Operational

-- | The abstract data type 'Program instr a' represents programs.
--   
--   <ul>
--   <li>The type constructor <tt>instr :: * -&gt; *</tt> indexes the
--   primitive instructions.</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 a = ProgramT instr Identity a

-- | 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 a = ProgramViewT instr Identity a

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

-- | The abstract data type <tt><a>ProgramT</a> instr m a</tt> represents
--   programs.
--   
--   <ul>
--   <li>The type constructor <tt>instr :: * -&gt; *</tt> indexes the
--   primitive instructions.</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.
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)