# Ratatouille


Ratatouille is a declarative terminal UI kit for Elixir for building rich
text-based terminal applications similar to how you write HTML.

It builds on top of the [termbox][termbox] API (using the Elixir bindings from

For the API Reference, see: [](

*[Toby](, a terminal-based Erlang observer built with Ratatouille*


**Table of Contents**

* [Ratatouille](#ratatouille)
  * [Getting Started](#getting-started)
    * [Building an Application](#building-an-application)
      * [init/1](#init1)
      * [update/2](#update2)
      * [render/1](#render1)
      * [Running it](#running-it)
  * [Views](#views)
  * [Examples](#examples)
  * [Under the Hood](#under-the-hood)
  * [Packaging and Distributing](#packaging-and-distributing)
    * [Defining an OTP Application](#defining-an-otp-application)
    * [Executable Releases with Distillery](#executable-releases-with-distillery)
  * [Installation](#installation)
    * [From Hex](#from-hex)
    * [From Source](#from-source)
  * [Roadmap](#roadmap)
  * [Contributing](#contributing)
    * [Running the Tests](#running-the-tests)

## Getting Started

Ratatouille implements the Elm Architecture as a way to structure application
logic. This fits quite naturally in Elixir and is part of what makes Ratatouille
declarative. If you've already used it on the web, it should feel very familiar.

As with a GenServer definition, Ratatouille apps only implement a behaviour by
defining callbacks and don't know how to start or run themselves. It's the
application runtime that handles all of those (sometimes tricky) details.

### Building an Application

Let's build a simple application that displays an integer counter which can be
incremented when the user presses "+" and decremented when the user presses "-".

First a quick clarification, since we're using the word "application" a lot. For
our purposes, an application is a terminal application, and not necessarily an
OTP application, but your terminal application could also be an OTP
application. We'll cover that in [Packaging and Distributing
Applications](#packaging-and-distributing) below.

Back to the counter app. First we'll look at the entire example, then we'll go
through it line by line to see what each line does. You can also find this
example [in the repo][counter_example] and run it with `mix run`.


# examples/counter.exs

defmodule Counter do
  @behaviour Ratatouille.App

  import Ratatouille.View

  def init(_context), do: 0

  def update(model, msg) do
    case msg do
      {:event, %{ch: ?+}} -> model + 1
      {:event, %{ch: ?-}} -> model - 1
      _ -> model

  def render(model) do
    view do
      label(content: "Counter is #{model} (+/-)")

At the top, we define a new module (`Counter`) for the app and we inform Elixir
that it will implement the `Ratatouille.App` behaviour. This just ensures we're
warned if we forget to implement a callback and serves as documentation that
this is a Ratatouille app.

defmodule Counter do
  @behaviour Ratatouille.App


Next, we import the View DSL from

import Ratatouille.View

The View DSL provides element builder functions like `view`, `row`, `table`,
`label` that you can use to define views. Think of them like HTML tags.

#### `init/1`

The `init/1` callback defines the initial model. "Model" is the Elm
architecture's term for what we often call "state" in Elixir/Erlang. As with a
GenServer, the state (our model) will later be passed to callbacks when things
happen in order to allow the app to update it.

The model can be any Erlang term. For larger apps, it's helpful to use maps or
structs to organize different pieces of the state. Here, we just have an integer
counter, so we return `0`:

defmodule Counter do

  def init(_context), do: 0


#### `update/2`

The `update/2` callback defines how to transform the model when a particular
message is received. Ratatouille's runtime will automatically call `update/2`
when terminal events occur (pressing a key, resizing the window, clicking the
mouse, etc.). We can also send ourselves messages via subscriptions and commands.

Here, we'd like to increment the counter when we get a `?+` key press and
decrement it when get a `?-`. Event messages are based on the underlying termbox
events and characters are given as code points (e.g., `?a` is `97`).

defmodule Counter do

  def update(model, msg) do
    case msg do
      {:event, %{ch: ?+}} -> model + 1
      {:event, %{ch: ?-}} -> model - 1
      _ -> model


It's a good idea to provide a fallback clause in case we don't know how to
handle a message. This way the app won't crash if the user presses a key that
the app doesn't handle. But if things stop working as you expect, try removing
the fallback to see if important messages are going unmatched.

#### `render/1`

The `render/1` callback defines a view to display the model. The runtime will
call it as needed when it needs to update the terminal window.

Similar to HTML, a view is defined as a tree of elements (nodes). Elements have
attributes (e.g., `text: bold`) and children (nested content). While helper
functions can return arbitrary element trees, the `render/1` callback must
return a view tree starting with a root `view` element---it's sort of like the
`<body>` tag in HTML.

defmodule Counter do

  def render(model) do
    view do
      label(content: "Counter is #{model} (+/-)")


#### Running it

There's a final and very important line at the bottom:


This starts the application runtime with our app definition. Options can be
passed as a second argument. This is an easy way to run simple apps. For more
complicated ones, it's recommended to define an OTP application.

That's it---now you can run the program with `mix run <file>`. To run the
bundled example:

$ mix run examples/counter.exs

You should see the counter we defined, be able to make changes to it with '+'
and '-', and be able to quit using 'q'.

## Views

| Element | Description       |
| ------- | ----------------- |
| [`bar`]( | Block-level element for creating title, status or menu bars |
| [`chart`]( | Element for plotting a series as a multi-line chart |
| [`column`]( | Container occupying a vertical segment of the grid |
| [`label`]( | Block-level element for displaying text |
| [`overlay`]( | Container overlaid on top of the view |
| [`panel`]( | Container with a border and title used to demarcate content |
| [`row`]( | Container used to define grid layouts with one or more columns |
| [`sparkline`]( | Element for plotting a series in a single line |
| [`table`]( | Container for displaying data in rows and columns |
| [`table_cell`]( | Element representing a table cell |
| [`table_row`]( | Container representing a row of the table |
| [`text`]( | Inline element for displaying uniformly-styled text |
| [`tree`]( | Container for displaying data as a tree of nodes |
| [`tree_node`]( | Container representing a tree node |
| [`view`]( | Top-level container |

## Examples

| Name | Description |
| ---- | ----------- |
| [`rendering.exs`]( | A rendering demo of all the supported elements |
| [`counter.exs`]( | How to create a simple app with state and updates |
| [`editor.exs`]( | How to use receive and display user input |
| [`multiple_views.exs`]( | How to render different views/tabs based on a selection |
| [`subscriptions.exs`]( | How to subscribe to multiple intervals |
| [`commands.exs`]( | How to run commands asynchronously and receive the results |

## Under the Hood

The application runtime abstracts away a lot of the details concerning how the
terminal window is updated and how events are received. If you're interested in
how these things actually work, or if the runtime doesn't support your use case,
see this guide:


## Packaging and Distributing

*Warning: This part is still rough around the edges.*

While it's easy to run apps with `mix run`, packaging them for others to easily
run is a bit more complicated. Depending on the type of app you're building, it
might not be reasonable to assume that users have any Elixir or Erlang tools
installed. Terminal apps are usually distributed as binary executables so that
they can just be run as such without additional dependencies. Fortunately, this
is possible using OTP releases that bundle ERTS.

### Defining an OTP Application

In order to create an OTP release, we first need to define an OTP application
that runs the terminal application. `Ratatouille.Runtime.Supervisor` takes care
of starting all the necessary runtime components, so we start this supervisor
under the OTP application supervisor and pass it a Ratatouille app definition
(along with any other runtime configuration).

For example, the OTP application for toby looks like this:

defmodule Toby do
  use Application

  def start(_type, _args) do
    children = [
      {Ratatouille.Runtime.Supervisor, runtime: [app: Toby.App]},
      # other workers...

      strategy: :one_for_one,
      name: Toby.Supervisor

### Executable Releases with Distillery

We'll use Distillery to create the OTP release, as it can even create
distributable, self-contained executables. Releases built on a given
architecture can generally be run on machines of the same architecture.

Follow the Distillery guide to generate a release configuration:


In order to make a "batteries-included" release, it's important that you have
`include_erts` set to `true`:

``` elixir
environment :prod do
  set(include_erts: true)

Now it's possible to generate the release:

MIX_ENV=prod mix release --executable --transient

This creates a Distillery release that bundles the Erlang runtime and the
application. Start it in the foreground, e.g.:

_build/prod/rel/toby/bin/ foreground

You can also move this executable somewhere else (e.g., to a directory in your
$PATH). A current caveat is that it must be able to unpack itself, as Distillery
executables are self-extracting archives.

## Installation

### From Hex

Add Ratatouille as a dependency in your project's `mix.exs`:

def deps do
    {:ratatouille, "~> 0.4.0"}

### From Source

To try out the master branch, first clone the repo:

git clone
cd ratatouille

Next, fetch the deps:

mix deps.get

Finally, try out one of the included [`examples/`][examples]:

mix run examples/rendering.exs

If you see lots of things drawn on your terminal screen, you're good to go. Use
"q" to quit in the examples (unless otherwise specified).


## Roadmap

* Apps
  * [x] Application Runtime
  * [x] Subscriptions
  * [x] Commands
* Views / Rendering
  * [x] Rendering engine with basic elements
  * [ ] More configurable charts (axis label, color, multiple lines, etc.)
  * [ ] Uniform support for text styling (incl. inheritance)
  * [ ] Automatic translation to termbox styling constants
    * For example, `color: :red` instead of `color: Constants.color(:red)`.
  * [ ] Rendering optimizations (view diffing, more efficient updates, etc.)
* Events
  * [ ] Translate termbox events to a cleaner format
    * Dealing with the integer constants is incovenient. These could be
      converted to atoms by the event manager.
* Terminal Backend
  * [x] ex_termbox NIFs
  * [ ] Alternative port-based termbox backend
* Customization
  * [ ] Registering custom element renderers
    * This would support using custom elements (e.g. `my_table()`) that are
      defined outside of the core library.

## Contributing

Contributions are much appreciated. They don't necessarily have to come in the
form of code, I'm also very thankful for bug reports, documentation
improvements, questions, and suggestions.

### Running the Tests

Run the unit tests as usual:

mix test

Ratatouille also includes integration tests of the bundled examples. These
aren't included in the default suite because they actually run the example apps.
The integration suite can be run like so:

mix test --only integration