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

module Control.Monad.Operational

-- | The abstract data type Program instr a represents
--   programs, i.e. sequences of primitive instructions.
--   
--   
--   
- The primitive instructions are given by the type
--   constructor instr :: * -> *.
--   
- a is the return type of a program.
--   
--   
--   Program instr is always a monad and automatically
--   obeys the monad laws.
type Program (instr :: Type -> Type) = ProgramT instr Identity

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

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

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

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

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

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

-- | View function for inspecting the first instruction.
viewT :: forall m (instr :: Type -> Type) a. 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 m. This is the counterpart of the lift
--   function from MonadTrans.
--   
--   It can be defined as follows:
--   
--   
--   liftProgram = eval . view
--       where
--       eval :: ProgramView instr a -> ProgramT instr m a
--       eval (Return a) = return a
--       eval (i :>>= k) = singleton i >>= liftProgram . k
--   
liftProgram :: forall (m :: Type -> Type) (instr :: Type -> Type) a. Monad m => Program instr a -> ProgramT instr m a

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

-- | Utilitiy function for mapping a ProgramViewT back into a
--   ProgramT.
--   
--   Semantically, the function unviewT is an inverse of
--   viewT, e.g. we have
--   
--   
--   viewT (singleton i) >>= unviewT = return (singleton i)
--   
unviewT :: forall (m :: Type -> Type) (instr :: Type -> Type) a. 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 ProgramTs as monadic
--   actions.
--   
--   Ideally, you would not use another monad, but write a custom
--   interpreter directly with viewT. See the remark at
--   interpretWithMonad.
interpretWithMonadT :: Monad m => (forall x. () => instr x -> m x) -> ProgramT instr m a -> m a
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Applicative (Control.Monad.Operational.ProgramT instr m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Applicative (Control.Monad.Operational.ProgramViewT instr m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Functor (Control.Monad.Operational.ProgramT instr m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Functor (Control.Monad.Operational.ProgramViewT instr m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Operational.ProgramT instr m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Monad (Control.Monad.Operational.ProgramT instr m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Monad (Control.Monad.Operational.ProgramViewT instr m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (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.Trans.Class.MonadTrans (Control.Monad.Operational.ProgramT instr)
