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


-- | MonadPrompt, implementation & examples
--   
--   "Prompting" monad that allows splitting the description of a
--   computation from the implementation of the effects used in that
--   computation.
--   <a>http://www.haskell.org/pipermail/haskell-cafe/2008-January/038301.html</a>
@package MonadPrompt
@version 1.0.0.5


-- | Implementation of monads that allow the computation to <a>prompt</a>
--   for further input.
--   
--   (c) 2008 Bertram Felgenhauer &amp; Ryan Ingram Released as open source
--   under a 3 clause BSD license. See the LICENSE file in the source code
--   distribution for further information.
--   
--   RecPromptT added by Cale Gibbard, contributed under the same license.
--   
--   MonadPrompt monads allow you to pass some object of the prompt type
--   in, and get a result of the prompt's answer type out.
module Control.Monad.Prompt

-- | You can construct a monad very simply with prompt, by putting all of
--   its effects as terms in a GADT, like the following example:
--   
--   <pre>
--   data PromptState s a where
--       Put :: s -&gt; PromptState s ()
--       Get :: PromptState s s
--   </pre>
--   
--   You then use <a>prompt</a> to access effects:
--   
--   <pre>
--   postIncrement :: MonadPrompt (PromptState Int) m =&gt; m Int
--   postIncrement =
--     do x &lt;- prompt Get
--        prompt (Put (x+1))
--        return x
--   </pre>
--   
--   The advantage of Prompt over implementing effects directly:
--   
--   <ol>
--   <li>Prompt is pure; it is only through the observation function
--   runPromptC that you can cause effects.</li>
--   <li>You don't have to worry about the monad laws; they are correct by
--   construction and you cannot break them.</li>
--   <li>You can implement several observation functions for the same type.
--   See, for example, <a>http://paste.lisp.org/display/53766</a> where a
--   guessing game is implemented with an IO observation function for the
--   user, and an AI observation function that plays the game
--   automatically.</li>
--   </ol>
--   
--   In these ways Prompt is similar to Unimo, but bind and return are
--   inlined into the computation, whereas in Unimo they are handled as a
--   term calculus. See
--   <a>http://sneezy.cs.nott.ac.uk/fplunch/weblog/?p=89</a>
class Monad m => MonadPrompt p m | m -> p
prompt :: MonadPrompt p m => p a -> m a
data Prompt p r

-- | <a>runPromptC</a> is the observation function for prompts. It takes
--   two functions as arguments:
--   
--   <ol>
--   <li><tt>ret</tt> will be called with the final result of the
--   computation, to convert it to the answer type.</li>
--   <li><tt>prm</tt> will be called if there are any effects; it is passed
--   a prompt and a continuation function. prm can apply the effect
--   requested by the prompt and call the continuation.</li>
--   </ol>
--   
--   In some cases prm can return the answer type directly; it may be
--   useful to abort the remainder of the computation, or save off the
--   continuation to be called later. There is a great example of using
--   this to implement a UI for peg solitaire in Bertram Felgenhauer's post
--   to Haskell-Cafe at
--   <a>http://www.haskell.org/pipermail/haskell-cafe/2008-January/038301.html</a>
runPromptC :: forall p r b. (r -> b) -> (forall a. p a -> (a -> b) -> b) -> Prompt p r -> b

-- | <a>runPrompt</a> takes a way of converting prompts to an element in a
--   pure fashion and calculates the result of the prompt
runPrompt :: (forall a. p a -> a) -> Prompt p r -> r

-- | <a>runPromptM</a> is similar to <a>runPrompt</a> but allows the
--   computation to happen in any monad.
runPromptM :: Monad m => (forall a. p a -> m a) -> Prompt p r -> m r

-- | <a>RecPrompt</a> is for prompts which are dependent on the prompt
--   monad.
--   
--   For example, a <tt>MonadPlus</tt> prompt:
--   
--   <pre>
--   data PromptPlus m a where
--     PromptZero :: PromptPlus m a
--     PromptPlus :: m a -&gt; m a -&gt; PromptPlus m a
--   
--   instance MonadPlus (RecPrompt PromptPlus) where
--     mzero = prompt PromptZero
--     mplus x y = prompt (PromptPlus x y)
--   </pre>
data RecPrompt p r
unRecPrompt :: RecPrompt p r -> Prompt (p (RecPrompt p)) r

-- | Runs a recursive prompt computation. This is similar to
--   <a>runPromptC</a>, but for recursive prompt types.
runRecPromptC :: forall p r b. (r -> b) -> (forall a. p (RecPrompt p) a -> (a -> b) -> b) -> RecPrompt p r -> b

-- | Run a recursive prompt computation in a pure fashion, similar to
--   <a>runPrompt</a>.
runRecPrompt :: (forall a. p (RecPrompt p) a -> a) -> RecPrompt p r -> r

-- | Run a recursive prompt computation in an arbitrary monad, similar to
--   <a>runPromptM</a>.
runRecPromptM :: Monad m => (forall a. p (RecPrompt p) a -> m a) -> RecPrompt p r -> m r

-- | Prompt can also be used to define monad transformers.
--   
--   You will notice the lack of a <tt>Monad m</tt> constraint; this is
--   allowed because Prompt doesn't use the underlying monad at all;
--   instead the observation function (generally implemented via
--   <a>runPromptT</a>) will have the constraint.
data PromptT p m a

-- | <a>runPromptT</a> runs a prompt monad transformer.
runPromptT :: forall p m r b. (r -> b) -> (forall a. p a -> (a -> b) -> b) -> (forall a. m a -> (a -> b) -> b) -> PromptT p m r -> b

-- | <a>runPromptTM</a> is a useful variant of runPromptT when interpreting
--   into another monad
runPromptTM :: forall p m r n. Monad n => (forall a. p a -> n a) -> (forall a. m a -> n a) -> PromptT p m r -> n r

-- | <a>runPromptTM'</a> specialises runPromptTM further for the case that
--   you're interpreting to the base monad by supplying the identity
--   function as the interpretation for lifted computations
runPromptTM' :: forall p m r. Monad m => (forall a. p a -> m a) -> PromptT p m r -> m r

-- | A higher-kinded Either, used in defining <a>PromptT</a>.
data Lift p m a
Effect :: p a -> Lift p m a
Lift :: m a -> Lift p m a
unPromptT :: PromptT p m a -> Prompt (Lift p m) a

-- | You can also lift any Prompt computation into a PromptT (or more
--   generally, any appropriate MonadPrompt instance). This is the kind of
--   place where the advantage of being able to use multiple observation
--   functions on Prompt really shows.
liftP :: MonadPrompt p m => Prompt p r -> m r

-- | A recursive variant of the prompt monad transformer.
data RecPromptT p m a
unRecPromptT :: RecPromptT p m a -> Prompt (Lift (p (RecPromptT p m)) m) a

-- | Run a recursive prompt monad transformer.
runRecPromptT :: forall p r b m. (r -> b) -> (forall a. p (RecPromptT p m) a -> (a -> b) -> b) -> (forall a. m a -> (a -> b) -> b) -> RecPromptT p m r -> b
instance GHC.Base.Monad (Control.Monad.Prompt.RecPromptT p m)
instance GHC.Base.Functor (Control.Monad.Prompt.RecPromptT p m)
instance GHC.Base.Applicative (Control.Monad.Prompt.RecPromptT p m)
instance Control.Monad.Prompt.MonadPrompt (p (Control.Monad.Prompt.RecPromptT p m)) (Control.Monad.Prompt.RecPromptT p m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Prompt.RecPromptT p)
instance GHC.Base.Monad (Control.Monad.Prompt.PromptT p m)
instance GHC.Base.Functor (Control.Monad.Prompt.PromptT p m)
instance GHC.Base.Applicative (Control.Monad.Prompt.PromptT p m)
instance Control.Monad.Prompt.MonadPrompt p (Control.Monad.Prompt.PromptT p m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Prompt.PromptT p)
instance GHC.Base.Monad (Control.Monad.Prompt.RecPrompt p)
instance GHC.Base.Functor (Control.Monad.Prompt.RecPrompt p)
instance GHC.Base.Applicative (Control.Monad.Prompt.RecPrompt p)
instance Control.Monad.Prompt.MonadPrompt (p (Control.Monad.Prompt.RecPrompt p)) (Control.Monad.Prompt.RecPrompt p)
instance GHC.Base.Monad (Control.Monad.Prompt.Prompt p)
instance GHC.Base.Functor (Control.Monad.Prompt.Prompt p)
instance GHC.Base.Applicative (Control.Monad.Prompt.Prompt p)
instance Control.Monad.Prompt.MonadPrompt p (Control.Monad.Prompt.Prompt p)
