To write a monad, use the Program type.

To write a monad transformer, use the ProgramT type.

For easier interoperability, the Program type is actually a type synonym and defined in terms of ProgramT.

The basic idea for implementing monads with this libary is to think of monads as sequences of primitive instructions. For instance, imagine that you want to write a web application with a custom monad that features an instruction

askUserInput :: CustomMonad UserInput

which sends a form to the remote user and waits for the user to send back his input

To implement this monad, you decide that this instruction is a primitive, i.e. should not be implemented in terms of other, more basic instructions. Once you have chosen your primitives, collect them in a data type

data CustomMonadInstruction a where
    AskUserInput :: CustomMonadInstruction UserInput

Then, obtain your custom monad simply by applying the Program type constructor

type CustomMonad a = Program CustomMonadInstruction a

The library makes sure that it is an instance of the Monad class and fulfills all the required laws.

Essentially, the monad you now obtained is just a fancy list of primitive instructions. In particular, you can pattern match on the first element of this "list". This is how you implement an interpret or run function for your monad. Note that pattern matching is done using the view function

runCustomMonad :: CustomMonad a -> IO a
runCustomMonad m = case view m of
    Return a            -> return a -- done, return the result
    AskUserInput :>>= k -> do
        b <- waitForUserInput       -- wait for external user input
        runCustomMonad (k b)        -- proceed with next instruction

The point is that you can now proceed in any way you like: you can wait for the user to return input as shown, or you store the continuation k and retrieve it when your web application receives another HTTP request, or you can keep a log of all user inputs on the client side an replay them, and so on. Moreover, you can implement different run functions for one and the same custom monad, which is useful for testing. Also note that the result type of the run function does not need to be a monad at all.

In essence, your custom monad allows you to express your web application as a simple imperative program, while the underlying implementation can freely map this to an event-drived model or some other control flow architecture of your choice.

The possibilities are endless. More usage examples can be found here: https://github.com/HeinrichApfelmus/operational/tree/master/doc/examples#readme

Example usage

Stack machine from "The Operational Monad Tutorial".

   data StackInstruction a where
       Push :: Int -> StackInstruction ()
       Pop  :: StackInstruction Int

   type StackProgram a = Program StackInstruction a
   type Stack b        = [b]

   interpret :: StackProgram a -> (Stack Int -> a)
   interpret = eval . view
       where
       eval :: ProgramView StackInstruction a -> (Stack Int -> a)
       eval (Push a :>>= is) stack     = interpret (is ()) (a:stack)
       eval (Pop    :>>= is) (a:stack) = interpret (is a ) stack
       eval (Return a)       stack     = a

In this example, the type signature for the eval helper function is optional.

Example usage

List monad transformer.

   data PlusI m a where
       Zero :: PlusI m a
       Plus :: ListT m a -> ListT m a -> PlusI m a

   type ListT m a = ProgramT (PlusI m) m a

   runList :: Monad m => ListT m a -> m [a]
   runList = eval <=< viewT
       where
       eval :: Monad m => ProgramViewT (PlusI m) m a -> m [a]
       eval (Return x)        = return [x]
       eval (Zero     :>>= k) = return []
       eval (Plus m n :>>= k) =
           liftM2 (++) (runList (m >>= k)) (runList (n >>= k))

In this example, the type signature for the eval helper function is optional.