Use the Model - View - Controller pattern to separate impure inputs and outputs from pure application logic so that you can:

• Equationally reason about your model
• Exercise your model with property-based testing (like QuickCheck)
• Reproducibly replay your model

The mvc library uses the type system to statically enforce the separation of impure Views and Controllers from the pure Model.

Here's a small example program written using the mvc library to illustrate the core types and concepts:

import MVC
import qualified MVC.Prelude as MVC
import qualified Pipes.Prelude as Pipes

external :: Managed (View String, Controller String)
external = do
    c1 <- MVC.stdinLines
    c2 <- MVC.tick 1
    return (MVC.stdoutLines, c1 <> fmap show c2)

model :: Model () String String
model = asPipe (Pipes.takeWhile (/= "quit"))
    
main :: IO ()
main = runMVC () model external

This program has three components:

• A Controller that interleaves lines from standard input with periodic ticks
• A View that writes lines to standard output
• A pure Model, which forwards lines until the user inputs "quit"

runMVC connects them into a complete program, which outputs a () every second and also echoes standard input to standard output until the user enters "quit":

>>> main
()
Test<Enter>
Test
()
()
42<Enter>
42
()
quit<enter>
>>> 

The following sections give extended guidance for how to structure mvc programs. Additionally, there is an MVC.Prelude module, which provides several utilities and provides a more elaborate code example using the sdl library.

Controllers represent concurrent inputs to your system. Use the Functor and Monoid instances for Controller and Managed to unify multiple Managed Controllers together into a single Managed Controller:

controllerA :: Managed (Controller A)
controllerB :: Managed (Controller B)
controllerC :: Managed (Controller C)

data TotalInput = InA A | InB B | InC C

controllerTotal :: Managed (Controller TotalInput)
controllerTotal =
        fmap (fmap InA) controllerA
    <>  fmap (fmap InB) controllerB
    <>  fmap (fmap InC) controllerC

Combining Controllers interleaves their values.

Views represent outputs of your system. Use handles and the Monoid instance of View to unify multiple Views together into a single View:

viewD :: Managed (View D)
viewE :: Managed (View E)
viewF :: Managed (View F)

data TotalOutput = OutD D | OutE E | OutF F

makePrisms ''TotalOutput  -- Generates _OutD, _OutE, and _OutF prisms

viewTotal :: Managed (View TotalOutput)
viewTotal =
        fmap (handles _OutD) viewD
    <>  fmap (handles _OutE) viewE
    <>  fmap (handles _OutF) viewF

Combining Views sequences their outputs.

If a lens dependency is too heavy-weight, then you can manually generate Traversals, which handles will also accept. Here is an example of how you can generate Traversals by hand with no dependencies:

-- _OutD :: Traversal' TotalOutput D
_OutD :: Applicative f => (D -> f D) -> (TotalOutput -> f TotalOutput)
_OutD k (OutD d) = fmap OutD (k d)
_OutD k  t       = pure t

-- _OutE :: Traversal' TotalOutput E
_OutE :: Applicative f => (E -> f E) -> (TotalOutput -> f TotalOutput)
_OutE k (OutE d) = fmap OutE (k d)
_OutE k  t       = pure t

-- _OutF :: Traversal' TotalOutput F
_OutF :: Applicative f => (F -> f F) -> (TotalOutput -> f TotalOutput)
_OutF k (OutF d) = fmap OutF (k d)
_OutF k  t       = pure t

Models are stateful streams and they sit in between Controllers and Views.

Use State to internally communicate within the Model.

Read the "ListT" section which describes why you should prefer ListT over Pipe when possible.

Also, try to defer converting your Pipe to a Model until you call runMVC, because the conversion is not reversible and Pipe is strictly more featureful than Model.

Connect a Model, View, and Controller and an initial state together using runMVC to complete your application.

runMVC is the only way to consume Views and Controllers. The types forbid you from mixing View and Controller logic with your Model logic.

Note that runMVC only accepts one View and one Controller. This enforces a single entry point and exit point for your Model so that you can cleanly separate your Model logic from your View logic and Controller logic. The way you add more Views and Controllers to your program is by unifying them into a single View or Controller by using their Monoid instances. See the "Controllers" and "Views" sections for more details on how to do this.

Use managed to create primitive Managed resources and use the Functor, Applicative, Monad, and Monoid instances for Managed to bundle multiple Managed resources into a single Managed resource.

See the source code for the "Utilities" section below for several examples of how to create Managed resources.

ListT computations can be combined in more ways than Pipes, so try to program in ListT as much as possible and defer converting it to a Pipe as late as possible using loop.

You can combine ListT computations even if their inputs and outputs are completely different:

-- Independent computations

modelAToD :: A -> ListT (State S) D
modelBToE :: B -> ListT (State S) E
modelCToF :: C -> ListT (State s) F

modelInToOut :: TotalInput -> ListT (State S) TotalOutput
modelInToOut totalInput = case totalInput of
    InA a -> fmap OutD (modelAToD a)
    InB b -> fmap OutE (modelBToE b)
    InC c -> fmap OutF (modelCToF c)

Sometimes you have multiple computations that handle different inputs but the same output, in which case you don't need to unify their outputs:

-- Overlapping outputs

modelAToOut :: A -> ListT (State S) Out
modelBToOut :: B -> ListT (State S) Out
modelCToOut :: C -> ListT (State S) Out

modelInToOut :: TotalInput -> ListT (State S) TotalOutput
modelInToOut totalInput = case totalInput of
    InA a -> modelAToOut a
    InB b -> modelBToOut b
    InC c -> modelCToOut c

Other times you have multiple computations that handle the same input but produce different outputs. You can unify their outputs using the Monoid and Functor instances for ListT:

-- Overlapping inputs

modelInToA :: TotalInput -> ListT (State S) A
modelInToB :: TotalInput -> ListT (State S) B
modelInToC :: TotalInput -> ListT (State S) C

modelInToOut :: TotalInput -> ListT (State S) TotalOutput
modelInToOut totalInput =
       fmap OutA (modelInToA totalInput)
    <> fmap OutB (modelInToB totalInput)
    <> fmap OutC (modelInToC totalInput)

You can also chain ListT computations, feeding the output of the first computation as the input to the next computation:

-- End-to-end

modelInToMiddle  :: TotalInput -> ListT (State S) MiddleStep
modelMiddleToOut :: MiddleStep -> ListT (State S) TotalOutput

modelInToOut :: TotalInput -> ListT (State S) TotalOutput
modelInToOut = modelInToMiddle >=> modelMiddleToOut

... or you can just use do notation if you prefer.

However, the Pipe type is more general than ListT and can represent things like termination. Therefore you should consider mixing Pipes with ListT when you need to take advantage of these extra features:

-- Mix ListT with Pipes

pipe :: Pipe TotalInput TotalOutput (State S) ()
pipe = Pipes.takeWhile (not . isC)) >-> loop modelInToOut
  where
    isC (InC _) = True
    isC  _      = False

So promote your ListT logic to a Pipe when you need to take advantage of these Pipe-specific features.

Data.Functor.Constant re-exports Constant

Data.Functor.Contravariant re-exports Contravariant

Data.Monoid re-exports Monoid, (<>), mconcat, and First (the type only)

Pipes re-exports everything

Pipes.Concurrent re-exports everything