Documentation

Each of the following functors is a primitive action. A back-end provides interpreters for these actions using the Run class,

A short tutorial on writing backends.

Backends consist of two main components:

1. A monad, M, in which the primitive actions are interpreted. Run instances specify an interpreter for each supported action, e.g Run M Output will specify an interpreter for the Output primitive action in the monad M.
2. A newtype, e.g Backend a, which is a functor, usually implemented by wrapping a coproduct of all supported features. '(:<:)' instances, the Functor instance, and the Run instance are provided by generalized newtype deriving.

As an example, suppose I am writing a back-end to IO, like System.Console.Wizard.BasicIO. I want to support basic input and output, and arbitrary IO, so I declare instances for Run for the IO monad:

 instance Run IO Output      where runAlgebra (Output s w)        = putStr s   >> w
 instance Run IO OutputLn    where runAlgebra (OutputLn s w)      = putStrLn s >> w
 instance Run IO Line        where runAlgebra (Line s w)          = getLine    >>= w
 instance Run IO Character   where runAlgebra (Character s w)     = getChar    >>= w
 instance Run IO ArbitraryIO where runAlgebra (ArbitraryIO iov f) = iov        >>= f
 

And then I would define the newtype for the backend, which we can call MyIOBackend:

 newtype MyIOBackend a = MyIOBackend ((Output :+: OutputLn :+: Line :+: Character :+: ArbitraryIO) a)
                       deriving ( Functor, Run IO
                                , (:<:) Output
                                , (:<:) OutputLn
                                , (:<:) Line
                                , (:<:) Character
                                , (:<:) ArbitraryIO
                                )
 

A useful convenience is to provide a simple identity function to serve as a type coercion:

 myIOBackend :: Wizard MyIOBackend a -> Wizard MyIOBackend a
 myIOBackend = id
 

One additional primitive action that I might want to include is the ability to clear the screen at a certain point. So, we define a new data type for the action:

 data ClearScreen w = ClearScreen w deriving Functor -- via -XDeriveFunctor
 

And a "smart" constructor for use by the user:

 clearScreen :: (ClearScreen :<: b) => Wizard b ()
 clearScreen = Wizard $ lift $ inject (ClearScreen (Pure ())) 
 

(These smart constructors all follow a similar pattern. See the source of System.Console.Wizard for more examples)

And then we define an interpreter for it:

 instance Run IO ArbitraryIO where runAlgebra (ClearScreen f) = clearTheScreen >> f
 

Now, we can use this as-is simply by directly extending our back-end:

 foo :: Wizard (ClearScreen :+: MyIOBackend)
 foo = clearScreen >> output "Hello World!"
 

Or, we could modify MyIOBackend to include the extension directly.

For custom actions that return output, the definition looks slightly different. Here is the definition of Line:

 data Line w = Line (PromptString) (String -> w) deriving Functor -- via -XDeriveFunctor
 

And the smart constructor looks like this:

 line :: (Line :<: b) => PromptString -> Wizard b String
 line s = Wizard $ lift $ inject (Line s Pure)