Keera Hails

Keera Hails is a toolkit to create Reactive Applications in Haskell.
It facilitates combining User Interfaces, external devices, network
connections, files and, optionally, FRP networks.

Keera Hails is modular and extensible. It is cross platform (Windows, Linux,
MacOSX, iOS, Android, GHCJS), UI-agnostic (Gtk+, WX, Qt, iOS native UIs,
Android Native toolkit, HTML DOM), FRP-agnostic and device-agnostic (Wiimote,
Webcams, etc).

Keera Hails has been used to create large applications and is used commercially
in production.

At a glance

<table> <tr> <td> Keera Studios' Gale Studio! <a href="http://keera.co.uk" target="_blank"> <img src="https://keera.co.uk/wp-content/uploads/2011/10/Screenshot.png" height="auto" alt="Gale Studio screenshot" style="max-height:175px;"></a> <img width="441" height="1"> </td> <td> Guerric Chupin's Arpeggigon <a href="https://gitlab.com/chupin/arpeggigon" target="_blank"> <img src="https://keera.co.uk/wp-content/uploads/2020/05/arpeggigon.png" height="auto" alt="Arpeggigon screenshot" style="max-height:175px;"></a> <img width="441" height="1"> </td> <td> SoOSim simulator <img src="https://keera.co.uk/wp-content/uploads/2011/10/Screenshot-from-2014-09-24-142046.png" height="auto" alt="CAES group's SoOSim" style="max-height: 175px;"> <img width="441" height="1"> </td> </tr> <tr> <td> iOS demo <a href="http://keera.co.uk" target="_blank"> <img src="https://keera.co.uk/wp-content/uploads/2022/04/keera-hails-ios-demo-capture.gif" height="auto" alt="Keera Hails iOS demo app screenshot" style="max-height:175px;"></a> <img width="441" height="1"> </td> <td> Android demo <a href="http://keera.co.uk" target="_blank"> <img src="https://keera.co.uk/wp-content/uploads/2022/04/keera-hails-android-demo-capture.gif" height="auto" alt="Keera Hails Android demo app screenshot" style="max-height:175px;"></a> <img width="441" height="1"> </td> <td> Web demo <a href="http://keera.co.uk" target="_blank"> <img src="https://keera.co.uk/wp-content/uploads/2022/04/hello-hails-web-calculator-css-final-orig-midres-short.gif" height="auto" alt="Keera Hails web demo app capture" style="max-height: 175px;"></a> <img width="441" height="1"> </td> </tr> <tr> <td colspan="3"> Image from Gale Studio and Keera Hails demos are Copyright © 2011 - 2022 Keera Studios Ltd. All Rights Reserved. Keera, Keera Studios, Keera Hails, Gale, Gale Studio are trademarks of Keera Studios Ltd. </td> </tr> </table>

Hands-on example

The two key ideas in Keera Hails are Reactive Values and Reactive Rules.
Reactive values are data holders or action endpoints that will contain, provide
and/or consume data. Reactive Rules just connect these values so that changes
propagate across.

A very simple example of an RV is the following construction, in which a passive
IORef is turned into active Reactive Value.

haskell
do

  -- Empower IORef with callback installation mechanism. This comes from the
  -- keera-callbacks library.
  --
  -- passiveCBRef :: CBRRef Integer
  passiveCBRef <- newCBRef 0

  -- Turn IO Ref into active reactive value (RV).
  --
  -- RVs are type classes. We use the type of Reactive Fields, which have a
  -- trivial RV implementation.
  let activeCBRefRV :: ReactiveFieldReadWrite IO Integer
      activeCBRefRV = ReactiveFieldReadWrite
                        (writeCBRef           passiveCBRef)
                        (readCBRef            passiveCBRef)
                        (installCallbackCBRef passiveCBRef)

We now define an RV that encloses a trivial monadic action:

haskell
  -- do continues

  -- Define a write-only RV that prints whatever you put in it.
  let printer :: Show a => ReactiveFieldWrite IO a
      printer = wrapMW print

You can connect them together in a monadic environment:

haskell
  -- Connect them using a reactive rule. In a GUI application, this code would
  -- in the controller, and would define connections between the model and
  -- the view.
  --
  -- For bi-directional connections, see (=:=).
  activeCBRefRV =:> printer

If you now loop and put data in the IORef, it will be passed along
the reactive connection and printed to the output:

haskell
  forever $ do
    threadDelay 1000000 -- 1 second
    reactiveValueModify activeCBRefRV (+1)

Using the same, simple ideas, you can define a RVs for, and connect, the fields
of GUI widgets, for files, for network sockets, etc.

Project Structure

The toolkit is divided in three parts:

Reactive Values: they are typed mutable values with event dispatching and
access properties. They can be modified by lifting functions and applying
lenses to them. They can also be connected so that they stay in sync during
program execution.
- keera-hails-reactivevalues: basic definitions and RV manipulation.
- keera-hails-reactivelenses: lens application.
Reactive bindings: Widget properties/attributes can be seen as
reactive values. So can network sockets, files, application models ('model'
as in MVC) and external resources (polling). Uni-directional, Functional
Reactive Programming signal functions can also be wrapped into a pair
of RVs (see Yampa). The idea is that, at the highest application level
(controller), each layer is wrapped in a reactive container and connected
to others.
- keera-hails-reactive-fs: Files as RVs
- keera-hails-reactive-network: Sockets as RVs
- keera-hails-reactive-gtk: Widget attributes and events as RVs
- keera-hails-reactive-wx: Widget attributes and events as RVs
- keera-hails-reactive-qt: Widget attributes and events as RVs
- keera-hails-reactive-htmldom (via GHCJS): HTML DOM element properties as RVs
- keera-hails-reactive-yampa: Yampa reactimation loops as a pair of RVs
- keera-hails-reactive-polling: Strategies to make RVs fire regularly
Backends for iOS and Android (using each platform's native UI toolkits) are
also available. Samples can be found
here and
here.
Please contact Keera Studios if you wish to use them.
MVC Architecture

MVC is easily applied using hails. There are two easy ways of wraping pure
models into RVs, depending on the level of change detection we need to detect
and optimise.
- keera-hails-mvc-model-lightmodel: Pure
  models as RVs
- keera-hails-mvc-model-protectedmodels:
  Pure models as RVs, with advance change detection. Template Haskell can be
  used to generate model access RVs based on record fields that stop
  unnecessary change propagation.
- keera-hails-mvc-view: Interface to the View of any
  program
- keera-hails-mvc-controller: Simple controller-handling definitions.
A pair Model-View, often needed by the controller, can be wrapped in an
environment. The following packages implement a Gtk View and a Gtk
environment.
- keera-hails-mvc-view-gtk: Structure to wrap Gtk views.
- keera-hails-mvc-environment-gtk: A MVC triplet based on a Gtk View.
The following package generate default project skeletons that do "the right
thing" (currently for Gtk+ only). The application takes the approach of
"convention over configuration": certain modules will be expected to have
predetermined names. If this is much of a problem, open a bug report.
- keera-hails: Program that generates a project skeleton.
We have a separate README that shows how to
build your first app using keera-hails.
Applications can be simplified further. The following packages implement
Gtk-based choreographies (M-V synchronizations and controller rule templates)
and address other common features needed in applications.
- keera-hails-mvc-solutions-gtk: Advanced choreographies for Gtk applications.
- keera-hails-mvc-solutions-config: Handling configuration files cleanly.
- keera-hails-i18n: Handling internationalization

Tutorials, papers and publications

Building a reactive calculator in Haskell
The Arpeggigon: Declarative Programming of A Full-Fledged Musical Application (PADL 2017)
Bridging the GUI gap with reactive values and relations (Haskell Symposium 2015)
Readme for Reactive Value library
Ivan Perez's 1st PhD report, pages 29 and 40
(page 40 is a paper of its own; page 29 is the thesis proposal outlining the
core ideas and problems that remain to be solved.)
TFP 2014 Pre-proceedings, pages 59-68
Reactive Programming using Reactive Values (blog post)

<table> <tr> <td> Building a reactive calculator in Haskell! <a href="https://keera.co.uk/2020/05/28/building-a-reactive-calculator-in-haskell-1-5/" target="_blank"> <img src="https://keera.co.uk/wp-content/uploads/2022/04/hello-hails-web-calculator-css-final-orig-midres-short.gif" height="auto" alt="Keera Hails web demo app capture" style="max-height:175px;"></a> <img width="441" height="1"> Copyright © 2020 - 2021 Keera Studios Ltd. All Rights Reserved. </td> </tr> </table>

For bibtex references to these articles, see Publications in http://www.cs.nott.ac.uk/~ixp/.

Applications and demos

Credits

I would like to thank the following people for fruitful discussions and collaborations.

Henrik Nilsson
Hamish Mackenzie (for helping me create the first GHCJS backend for Hails,
and for Gtk2hs).
Leuite Stegeman (for helping me create the first GHCJS backend for Hails).
Guerric Chupin (for continuing this work and writing Arpeggigon).
Arsen Kostenko
Emilio Gallego
Paolo Capriotti
Florent Ballestrieri
David McGillicuddy
Philip Holzenspies
Ian-Woo Kim
Atze van der Ploeg
Simon Peyton Jones
Michał Gajda
I thank the audiences of the following talks on Reactive programming and
Hails, for patientily listening to me complain about the state of the world
and commenting on my work.
- Haskell Symposium (2015), Vancouver, colocated with ICFP.
- London (2014), Haskell Meetup
- Nottingham (2014), FPLAD.
- TFP (2014)
- FPLab, Nottingham (2013)
- CAES Group, UTwente (2013)
- Babel Research Group, UPM (2010)

(Note: these people do not necessarily support anything I have to say.)