• Brick
• Haskeline
  • Hidden gem
  • Example of abstracting monads
• Example usage (aka: just show me how to use it)

I recently wrote an interpreter of a stack-based language in Haskell and wanted to give its REPL command-line editing and history.

The best way to do so without effort is to use the fantastic rlwrap: it handles the readline integration for you and lets you focus on your own problem domain.

I wanted to show the user the current stack in the interpreter and ended up with:

This was inspired by gdb -tui:

Here rlwrap falls short, it's not intended to wrap anything more complicated than a user interface that writes a prompt to stdout and reads a line from stdin.

I started to look for alternatives to rlwrap and settled on Brick for handling the terminal user interface and Haskeline for providing the command-line functionality.

However, Haskeline needed some coaxing to play nice with Brick. The code can be found in my fork of Haskeline.

Brick

Brick is a library for declaratively building terminal user interfaces.

This means it lets you express your wishes about how the layout of the interface's widgets should be placed and decorated, without having to bother with control characters or ncurses.

To get up to speed on how to use it I followed mainly:

• the User guide,
• its Hackage documentation
• and the Introduction to Brick post implementing a snake game. This was also the post that brought Brick to my attention, thank you samtay for that!

Haskeline

Haskeline is a pure Haskell implementation providing similar functionality as readline: command-line editing, history and completion. You've probably already seen it in action since it's used in GHCi.

It already featured multiple backends for different kinds of terminals (e.g. Windows or POSIX), so adding another felt natural. Since both Brick and Haskeline are event driven, combining them amounts to two channels in opposite directions, not exactly brain surgery. Also, Haskeline is implemented in the style of monad transformer stacks, so it provides an example on how to structure a code base using them.

Hidden gem

While implementing the Brick backend in Haskeline, I encountered this curious looking type:

data EvalTerm m =
    forall n . (Term n, CommandMonad n)
            => EvalTerm (forall a . n a -> m a) (forall a . m a -> n a)

This type is used when specifying how to run a terminal backend, where in the TermOps the following field is required:

evalTerm :: forall m . CommandMonad m => EvalTerm m

To unravel the meaning of the EvalTerm type, note that it's an existential type. Another clue is to simplify it a bit using the ~> type operator:

type f ~> g = forall x. f x -> g x

Using this type synonym, EvalTerm contains both a transformation n ~> m and another in the reverse direction m ~> n. Did someone say natural isomorphism?

Note also that in evalTerm both m and n have CommandMonad instances, while n also has a Term instance. Having the picture of monad stacks in your mind suggests that n might be constructed as one or more monad transformers on top of m.

Since these backends have different requirements, i.e. implemented with different monad stacks, there's a need for abstraction. Can you see the sparkle in the eye of the OO-programmer thinking about interfaces and inheritance? Indeed, the dynamic dispatch mechanism of OOP can be emulated using existential types, but here we'll abstract monads not the data itself, but the idea and underlying mechanism are very much the same.

Example of abstracting monads

To check my hypothesis of the interpretation of the EvalTerm type above, i.e. as a way to talk explicitly about abstractions and providing witnessing values representing concrete implementations, I wrote down the following example.

Assume we have a type class that we would like to provide different implementations of:

class Interface m where
    suchFunction :: Int -> m Int

We also have a "baseline" monad class, representing the context in which we wish to use the abstracted interface:

class MonadIO m => BaseMonad m where
    baseOutput :: String -> m ()
    baseOutput = liftIO . putStrLn

Next, let's write down the type representing the dynamic dispatch of calls to the interface class into a particular concrete implementation:

newtype Dispatch = MkDispatch (forall m . BaseMonad m => Concretization m)

data Concretization m =
    forall n . (Interface n, Monad n) => MkConcretization (n ~> m) (m ~> n)

The separate Concretization data type is put at the top-level for no other reason than that I haven't found a way to bake it into the Dispatch type. Naively I tried to inline it:

data Dispatch2 where
    MkDispatch2 :: Monad m => (forall n . (Interface n, Monad n) => ((m ~> n), (n ~> m))) -> Dispatch2

but GHC told me:

    • Illegal polymorphic type: m ~> n
      GHC doesn't yet support impredicative polymorphism

Back to the example, I added three different Dispatch values. First one using a ReaderT Int:

newtype Concrete1 m a = MkConcrete1 { runConcrete1 :: ReaderT Int m a }
    deriving (Monad, Applicative, Functor, MonadReader Int)

instance Monad m => Interface (Concrete1 m) where
    suchFunction i = do
        x <- ask
        return $ x + i

dispatch1 :: Int -> Dispatch
dispatch1 i = MkDispatch $
    MkConcretization ((flip runReaderT) i . runConcrete1) (MkConcrete1 . lift)

Secondly, one using a StateT Int, mainly showing that you can easily have different monad stacks on top of a common base:

newtype Concrete2 m a = MkConcrete2 { runConcrete2 :: StateT Int m a }
    deriving (Monad, Applicative, Functor, MonadState Int)

instance Monad m => Interface (Concrete2 m) where
    suchFunction i = do
        x <- get
        put $ x * i
        return $ x * i

dispatch2 :: Int -> Dispatch
dispatch2 i = MkDispatch $
    MkConcretization ((flip evalStateT) i . runConcrete2) (MkConcrete2 . lift)

Lastly, an example using a free monad with the intent of showing that the concrete monad does not necessarily need to be a monad transformer on top of the base monad. However, the example below suggests something similar to a FreeT. The actual FreeT is different.

It's possible to implement mtl-style instances, lifting through the underlying BaseMonad. Here is the corresponding example using that style. In that setting the second field of MkConcretization is unnecessary: the lifting m ~> n transform is used implicitly by the MonadIO and BaseMonad instances of the concrete implementations. As always there's a trade-off and matter of taste.

Anyway, here's the code for the third concretization:

data Concrete3F m v where
    SomeFunctionF :: Int -> (Int -> v) -> Concrete3F m v
    LiftF :: forall a m v . (m a) -> (a -> v) -> Concrete3F m v

instance Functor (Concrete3F m) where
    fmap f (SomeFunctionF i k) = SomeFunctionF i (f . k)
    fmap f (LiftF ma k) = LiftF ma (f . k)

newtype Concrete3 m a = MkConcrete3 { runConcrete3 :: Free (Concrete3F m) a }
    deriving (Monad, Applicative, Functor)

instance Interface (Concrete3 m) where
    suchFunction i = MkConcrete3 . liftF $ SomeFunctionF i id

dispatch3 :: Dispatch
dispatch3 = MkDispatch $ MkConcretization
    (iterM go . runConcrete3)
    (MkConcrete3 . liftF . \ma -> LiftF ma id)

go :: BaseMonad m => Concrete3F m (m v) -> m v
go (SomeFunctionF i k) = k (i * i)
go (LiftF ma k) = ma >>= k

To show how the usage of Dispatch would work, here are some example programs:

program1 :: (Interface n, Monad n, BaseMonad m) => (m ~> n) -> n Int
program1 liftB = do
    i <- suchFunction 1
    liftB $ baseOutput $ "Interface: program1 " ++ show i
    return i

program2 :: BaseMonad m => Int -> m ()
program2 i = do
    baseOutput $ "BaseMonad: program2 " ++ show i

program3 :: BaseMonad m => Dispatch -> m ()
program3 (MkDispatch (MkConcretization evalI liftB)) = do
    l <- evalI $ do
        i <- suchFunction 2
        j <- program1 liftB
        let k = i + j
        liftB $ program2 k
        return $ k
    baseOutput $ "BaseMonad again l=" ++ show l

Note that:

• program1 does not make any assumption on the relation between n and m, so uses of BaseMonad functions requires a lift
• program2 only uses m (the BaseMonad) and so requires to be lifted into m in program3
• program3 shows an inner do-expression than runs in the n monad, and so needs to be evaluated back down into the m monad

Example usage (aka: just show me how to use it)

This example will set up a simple two widget Brick app, with a simple text string on top and a Haskeline input loop on the bottom:

The code of this example is included in the fork and can be executed using the accompanying Makefile-script.

data Event = FromHBWidget HB.ToBrick | HaskelineDied (Either SomeException ())

data Name = TheApp | HaskelineWidget
    deriving (Ord, Eq, Show)

data MyState = MyState { haskelineWidget :: HB.Widget Name }

app :: HB.Config Event -> App MyState Event Name
app c = App { appDraw = drawUI
            , appChooseCursor = const $ showCursorNamed HaskelineWidget
            , appHandleEvent = handleEvent c
            , appStartEvent = return
            , appAttrMap = const $ attrMap V.defAttr []
            }

handleEvent :: HB.Config Event
            -> MyState -> BrickEvent Name Event -> EventM Name (Next MyState)
handleEvent c s@MyState{haskelineWidget = hw} e = do
    hw' <- HB.handleEvent c hw e
    handleAppEvent (s { haskelineWidget = hw' }) e

handleAppEvent :: MyState -> BrickEvent Name Event -> EventM Name (Next MyState)
handleAppEvent s (AppEvent (HaskelineDied e)) = halt s
handleAppEvent s (VtyEvent (V.EvKey V.KEsc [])) = halt s
handleAppEvent s _ = continue s

drawUI :: MyState -> [Widget Name]
drawUI s = [ top <=> bottom ]
    where
        top = C.center $ str "yo"
        bottom = B.border $ HB.render (haskelineWidget s)

runHaskeline :: HB.Config Event -> IO ()
runHaskeline c = runInputTBehavior (HB.useBrick c) defaultSettings loop
   where
       loop :: InputT IO ()
       loop = do
           minput <- getInputLine "% "
           case minput of
             Nothing -> return ()
             Just input -> do
                 outputStr input
                 loop

main :: IO ()
main = do
    chan <- newBChan 10
    config <- HB.configure
            chan
            FromHBWidget
            (\case { FromHBWidget x -> Just x; _ -> Nothing })
    _ <- forkFinally
            (runHaskeline config)
            (writeBChan chan . HaskelineDied)
    void $ customMain
        (V.mkVty V.defaultConfig)
        (Just chan)
        (app config)
        MyState { haskelineWidget = HB.initialWidget HaskelineWidget }