Documentation

You can construct a monad very simply with prompt, by putting all of its effects as terms in a GADT, like the following example:

data PromptState s a where
    Put :: s -> PromptState s ()
    Get :: PromptState s s

You then use prompt to access effects:

postIncrement :: MonadPrompt (PromptState Int) m => m Int
postIncrement =
  do x <- prompt Get
     prompt (Put (x+1))
     return x

The advantage of Prompt over implementing effects directly:

1. Prompt is pure; it is only through the observation function runPromptC that you can cause effects.
2. You don't have to worry about the monad laws; they are correct by construction and you cannot break them.
3. You can implement several observation functions for the same type. See, for example, http://paste.lisp.org/display/53766 where a guessing game is implemented with an IO observation function for the user, and an AI observation function that plays the game automatically.

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 http://sneezy.cs.nott.ac.uk/fplunch/weblog/?p=89

runPromptC is the observation function for prompts. It takes two functions as arguments:

1. ret will be called with the final result of the computation, to convert it to the answer type.
2. prm 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.

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 http://www.haskell.org/pipermail/haskell-cafe/2008-January/038301.html

runPrompt takes a way of converting prompts to an element in a pure fashion and calculates the result of the prompt

runPromptM is similar to runPrompt but allows the computation to happen in any monad.

RecPrompt is for prompts which are dependent on the prompt monad.

For example, a MonadPlus prompt:

data PromptPlus m a where
  PromptZero :: PromptPlus m a
  PromptPlus :: m a -> m a -> PromptPlus m a

instance MonadPlus (RecPrompt PromptPlus) where
  mzero = prompt PromptZero
  mplus x y = prompt (PromptPlus x y)

Runs a recursive prompt computation. This is similar to runPromptC, but for recursive prompt types.

Run a recursive prompt computation in a pure fashion, similar to runPrompt.

Run a recursive prompt computation in an arbitrary monad, similar to runPromptM.

Prompt can also be used to define monad transformers.

You will notice the lack of a Monad m constraint; this is allowed because Prompt doesn't use the underlying monad at all; instead the observation function (generally implemented via runPromptT) will have the constraint.

runPromptT runs a prompt monad transformer.

runPromptTM is a useful variant of runPromptT when interpreting into another monad

runPromptTM' 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

A higher-kinded Either, used in defining PromptT.

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.

A recursive variant of the prompt monad transformer.

Run a recursive prompt monad transformer.