Termbox.Banana

This module provides a reactive-banana FRP interface to termbox, a simple C library for writing text-based user interfaces: https://github.com/termbox/termbox

See also:

• termbox-tea, an Elm Architecture interface.

This module is intended to be imported qualified.

👉 Quick start example

This termbox program displays the number of keys pressed.

{-# LANGUAGE DuplicateRecordFields #-}
{-# LANGUAGE ImportQualifiedPost #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedRecordDot #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE NoFieldSelectors #-}

import Data.Foldable (fold)
import Reactive.Banana ((<@>))
import Reactive.Banana qualified as Banana
import Termbox.Banana qualified as Termbox

main :: IO ()
main =
  Termbox.run network >>= \case
    Left err -> putStrLn ("Termbox program failed to initialize: " ++ show err)
    Right n -> putStrLn ("Pressed " ++ show n ++ " keys.")

network :: Banana.MonadMoment m => Termbox.Inputs -> m (Termbox.Outputs Int)
network inputs = do
  keysPressed <- Banana.accumB 0 ((+ 1) <$ inputs.keys)
  pure
    Termbox.Outputs
      { scene = render <$> keysPressed,
        done = Banana.filterJust (isDone <$> keysPressed <@> inputs.keys)
      }
  where
    isDone :: Int -> Termbox.Key -> Maybe Int
    isDone n = \case
      Termbox.KeyEsc -> Just n
      _ -> Nothing

render :: Int -> Termbox.Scene
render keysPressed =
  fold
    [ string
        Termbox.Pos {row = 2, col = 4}
        ("Number of keys pressed: " ++ map Termbox.char (show keysPressed)),
      string
        Termbox.Pos {row = 4, col = 4}
        ("Press " ++ map (Termbox.bold . Termbox.char) "Esc" ++ " to quit.")
    ]

string :: Termbox.Pos -> [Termbox.Cell] -> Termbox.Scene
string pos cells =
  foldMap (\(i, cell) -> Termbox.cell (Termbox.posRight i pos) cell) (zip [0 ..] cells)

Main

data Inputs

The inputs to a termbox FRP network.

Constructors

Inputs

Fields

• initialSize :: !Size

  The initial terminal size.

• keys :: !(Event Key)

  Key events.

• resizes :: !(Event Size)

  Resize events.

• mouses :: !(Event Mouse)

  Mouse events.

data Outputs a

The outputs from a termbox FRP network.

Constructors

Outputs

Fields

• scene :: !(Behavior Scene)

  The scene to render.

• done :: !(Event a)

  The events of arbitrary values, on the first of which is relevant, which causes run to return.

  Note: Wrapping this event in once is not necessary, as this library does so internally.

run

Arguments

:: (Inputs -> MomentIO (Outputs a))

The FRP network.

-> IO (Either InitError a)

The result of the FRP network.

Run a termbox FRP network.

run either:

• Returns immediately with an InitError.
• Returns the first value emitted by done.

data InitError

termbox initialization errors.

Constructors

FailedToOpenTTY

PipeTrapError

UnsupportedTerminal

Instances

Exception InitError

Defined in Termbox.Internal.Main

Methods

toException :: InitError -> SomeException

fromException :: SomeException -> Maybe InitError

displayException :: InitError -> String

Show InitError

Defined in Termbox.Internal.Main

Methods

showsPrec :: Int -> InitError -> ShowS

show :: InitError -> String

showList :: [InitError] -> ShowS

Terminal contents

Scene

data Scene

A scene.

• Set individual cells with cell.
• Set the background fill color with fill.
• Set the cursor position with cursor.
• Combine scenes together with <>.

Instances

Monoid Scene

Defined in Termbox.Internal.Scene

Methods

mempty :: Scene

mappend :: Scene -> Scene -> Scene

mconcat :: [Scene] -> Scene

Semigroup Scene

Defined in Termbox.Internal.Scene

Methods

(<>) :: Scene -> Scene -> Scene

sconcat :: NonEmpty Scene -> Scene

stimes :: Integral b => b -> Scene -> Scene

cell :: Pos -> Cell -> Scene

Set a single cell.

fill :: Color -> Scene

Set the background fill color.

cursor :: Pos -> Scene

Set the cursor position.

Cell

data Cell

A single cell.

• Create a cell with char, or with a string literal.
• Set a cell's color with fg, bg.
• Style a cell with bold, underline, blink.

Instances

IsString [Cell]

Defined in Termbox.Internal.Cell

Methods

fromString :: String -> [Cell]

char :: Char -> Cell

Create a cell from a character.

If the character is not 1 character wide, it will not be displayed.

fg :: Color -> Cell -> Cell

Set the foreground color of a cell.

bg :: Color -> Cell -> Cell

Set the background color of a cell.

bold :: Cell -> Cell

Make a cell bold.

underline :: Cell -> Cell

Make a cell underlined.

blink :: Cell -> Cell

Make a cell blink.

Colors

data Color

A color.

There are three classes of colors:

• Basic named colors and their bright variants, such as red and bright blue.
• Miscellaneous colors, such as color 33.
• Monochrome colors that range from black (gray 0) to white (gray 23).

Basic colors

defaultColor :: Color

red :: Color

green :: Color

yellow :: Color

blue :: Color

magenta :: Color

cyan :: Color

white :: Color

bright :: Color -> Color

Make a basic color brighter.

216 miscellaneous colors

color :: Int -> Color

A miscellaneous color.

Valid values are in the range [0, 215]; values outside of this range are clamped.

24 monochrome colors

gray :: Int -> Color

A monochrome color; black is 0 and white is 23.

Valid values are in the range [0, 23]; values outside of this range are clamped.

Event handling

data Key

A key event.

Some distinct key sequences map to the same key event. For example, to a termbox program, Enter is indistinguishable from Ctrl+M. Pattern synonyms below are provided for an alternate syntax in these cases, if desired.

Constructors

KeyChar Char

KeyArrowDown

KeyArrowLeft

KeyArrowRight

KeyArrowUp

KeyBackspace

KeyCtrlBackspace

Also KeyCtrlH

KeyCtrl6

KeyCtrl8

KeyCtrlA

KeyCtrlB

KeyCtrlBackslash

Also KeyCtrl4

KeyCtrlC

KeyCtrlD

KeyCtrlE

KeyCtrlF

KeyCtrlG

KeyCtrlJ

KeyCtrlK

KeyCtrlL

KeyCtrlN

KeyCtrlO

KeyCtrlP

KeyCtrlQ

KeyCtrlR

KeyCtrlRsqBracket

Also KeyCtrl5

KeyCtrlS

KeyCtrlSlash

Also KeyCtrl7, KeyCtrlUnderscore

KeyCtrlTilde

Also KeyCtrl2

KeyCtrlT

KeyCtrlU

KeyCtrlV

KeyCtrlW

KeyCtrlX

KeyCtrlY

KeyCtrlZ

KeyDelete

KeyEnd

KeyEnter

Also KeyCtrlM

KeyEsc

Also KeyCtrlLsqBracket, KeyCtrl3

KeyF1

KeyF10

KeyF11

KeyF12

KeyF2

KeyF3

KeyF4

KeyF5

KeyF6

KeyF7

KeyF8

KeyF9

KeyHome

KeyInsert

KeyPageDn

KeyPageUp

KeySpace

KeyTab

Also KeyCtrlI

Bundled Patterns

pattern KeyCtrlUnderscore :: Key

pattern KeyCtrlI :: Key

pattern KeyCtrlM :: Key

pattern KeyCtrl7 :: Key

pattern KeyCtrl5 :: Key

pattern KeyCtrl4 :: Key

pattern KeyCtrl3 :: Key

pattern KeyCtrl2 :: Key

pattern KeyCtrlLsqBracket :: Key

pattern KeyCtrlH :: Key

Instances

Show Key

Defined in Termbox.Internal.Key

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

Eq Key

Defined in Termbox.Internal.Key

Methods

(==) :: Key -> Key -> Bool

(/=) :: Key -> Key -> Bool

Ord Key

Defined in Termbox.Internal.Key

Methods

compare :: Key -> Key -> Ordering

(<) :: Key -> Key -> Bool

(<=) :: Key -> Key -> Bool

(>) :: Key -> Key -> Bool

(>=) :: Key -> Key -> Bool

max :: Key -> Key -> Key

min :: Key -> Key -> Key

data Mouse

A mouse event.

Constructors

Mouse

Fields

• button :: !MouseButton
• pos :: !Pos

Instances

Generic Mouse

Defined in Termbox.Internal.Mouse

Associated Types

type Rep Mouse :: Type -> Type

Methods

from :: Mouse -> Rep Mouse x

to :: Rep Mouse x -> Mouse

Show Mouse

Defined in Termbox.Internal.Mouse

Methods

showsPrec :: Int -> Mouse -> ShowS

show :: Mouse -> String

showList :: [Mouse] -> ShowS

Eq Mouse

Defined in Termbox.Internal.Mouse

Methods

(==) :: Mouse -> Mouse -> Bool

(/=) :: Mouse -> Mouse -> Bool

Ord Mouse

Defined in Termbox.Internal.Mouse

Methods

compare :: Mouse -> Mouse -> Ordering

(<) :: Mouse -> Mouse -> Bool

(<=) :: Mouse -> Mouse -> Bool

(>) :: Mouse -> Mouse -> Bool

(>=) :: Mouse -> Mouse -> Bool

max :: Mouse -> Mouse -> Mouse

min :: Mouse -> Mouse -> Mouse

type Rep Mouse

Defined in Termbox.Internal.Mouse

type Rep Mouse = D1 ('MetaData "Mouse" "Termbox.Internal.Mouse" "trmbx-1.1.0-f08fef24" 'False) (C1 ('MetaCons "Mouse" 'PrefixI 'True) (S1 ('MetaSel ('Just "button") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 MouseButton) :*: S1 ('MetaSel ('Just "pos") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Pos)))

data MouseButton where

A mouse button.

Bundled Patterns

pattern WheelUp :: MouseButton

pattern WheelDown :: MouseButton

pattern ReleaseClick :: MouseButton

pattern RightClick :: MouseButton

pattern MiddleClick :: MouseButton

pattern LeftClick :: MouseButton

Instances

Show MouseButton

Defined in Termbox.Internal.Mouse

Methods

showsPrec :: Int -> MouseButton -> ShowS

show :: MouseButton -> String

showList :: [MouseButton] -> ShowS

Eq MouseButton

Defined in Termbox.Internal.Mouse

Methods

(==) :: MouseButton -> MouseButton -> Bool

(/=) :: MouseButton -> MouseButton -> Bool

Ord MouseButton

Defined in Termbox.Internal.Mouse

Methods

compare :: MouseButton -> MouseButton -> Ordering

(<) :: MouseButton -> MouseButton -> Bool

(<=) :: MouseButton -> MouseButton -> Bool

(>) :: MouseButton -> MouseButton -> Bool

(>=) :: MouseButton -> MouseButton -> Bool

max :: MouseButton -> MouseButton -> MouseButton

min :: MouseButton -> MouseButton -> MouseButton

Miscellaneous types

data Pos

A terminal position.

Constructors

Pos

Fields

• row :: !Int
• col :: !Int

Instances

Generic Pos

Defined in Termbox.Internal.Pos

Associated Types

type Rep Pos :: Type -> Type

Methods

from :: Pos -> Rep Pos x

to :: Rep Pos x -> Pos

Show Pos

Defined in Termbox.Internal.Pos

Methods

showsPrec :: Int -> Pos -> ShowS

show :: Pos -> String

showList :: [Pos] -> ShowS

Eq Pos

Defined in Termbox.Internal.Pos

Methods

(==) :: Pos -> Pos -> Bool

(/=) :: Pos -> Pos -> Bool

Ord Pos

Defined in Termbox.Internal.Pos

Methods

compare :: Pos -> Pos -> Ordering

(<) :: Pos -> Pos -> Bool

(<=) :: Pos -> Pos -> Bool

(>) :: Pos -> Pos -> Bool

(>=) :: Pos -> Pos -> Bool

max :: Pos -> Pos -> Pos

min :: Pos -> Pos -> Pos

type Rep Pos

Defined in Termbox.Internal.Pos

type Rep Pos = D1 ('MetaData "Pos" "Termbox.Internal.Pos" "trmbx-1.1.0-f08fef24" 'False) (C1 ('MetaCons "Pos" 'PrefixI 'True) (S1 ('MetaSel ('Just "row") 'SourceUnpack 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel ('Just "col") 'SourceUnpack 'SourceStrict 'DecidedUnpack) (Rec0 Int)))

posUp :: Int -> Pos -> Pos

Move a position up.

posDown :: Int -> Pos -> Pos

Move a position down.

posLeft :: Int -> Pos -> Pos

Move a position left.

posRight :: Int -> Pos -> Pos

Move a position right.

data Size

A terminal size.

Constructors

Size

Fields

• width :: !Int
• height :: !Int

Instances

Generic Size

Defined in Termbox.Internal.Size

Associated Types

type Rep Size :: Type -> Type

Methods

from :: Size -> Rep Size x

to :: Rep Size x -> Size

Show Size

Defined in Termbox.Internal.Size

Methods

showsPrec :: Int -> Size -> ShowS

show :: Size -> String

showList :: [Size] -> ShowS

Eq Size

Defined in Termbox.Internal.Size

Methods

(==) :: Size -> Size -> Bool

(/=) :: Size -> Size -> Bool

Ord Size

Defined in Termbox.Internal.Size

Methods

compare :: Size -> Size -> Ordering

(<) :: Size -> Size -> Bool

(<=) :: Size -> Size -> Bool

(>) :: Size -> Size -> Bool

(>=) :: Size -> Size -> Bool

max :: Size -> Size -> Size

min :: Size -> Size -> Size

type Rep Size

Defined in Termbox.Internal.Size

type Rep Size = D1 ('MetaData "Size" "Termbox.Internal.Size" "trmbx-1.1.0-f08fef24" 'False) (C1 ('MetaCons "Size" 'PrefixI 'True) (S1 ('MetaSel ('Just "width") 'SourceUnpack 'SourceStrict 'DecidedUnpack) (Rec0 Int) :*: S1 ('MetaSel ('Just "height") 'SourceUnpack 'SourceStrict 'DecidedUnpack) (Rec0 Int)))