Raxol Revived ExTermbox

View Source

Hex.pm Hexdocs.pm

Low-level termbox bindings for Elixir.

For high-level, declarative terminal UIs in Elixir, see raxol or it's predecessor Ratatouille. It builds on top of this library and the termbox API to provide an HTML-like DSL for defining views.

For the API Reference, see: https://hexdocs.pm/rrex_termbox.

Getting Started

Termbox bindings

ExTermbox implements the termbox API functions via NIFs:

Hello World

Let's go through the bundled hello world example. To follow along, clone this repo and edit the example.

This repository makes use of Git submodules, so make sure you include them in your clone. In recent versions of git, this can be accomplished by including the --recursive flag, e.g.

# Make sure to clone *this* repository recursively to include submodules
git clone --recursive <your-fork-url>

When the clone is complete, the c_src/termbox/ directory should have files in it.

You can also create an Elixir script in any Mix project with rrex_termbox in the dependencies list. Later, we'll run the example with mix run <file>.

In a real project, you'll probably want to use an OTP application with a proper supervision tree, but here we'll keep it as simple as possible.

First, some aliases for the modules we'll use.

alias ExTermbox.Bindings, as: Termbox
alias ExTermbox.{Cell, EventManager, Event, Position}

Next, we initialize the termbox application. This initialization should come before any other termbox functions are called. (Otherwise, your program will probably crash.)

:ok = Termbox.init()

In order to react to keyboard, click or resize events later, we need to start the event manager and subscribe the current process to any events. The event manager is an abstraction over poll_event/1 that constantly polls for events and notifies its subscribers whenever one is received.

{:ok, _pid} = EventManager.start_link()
:ok = EventManager.subscribe(self())

To render content to the screen, we use put_cell/1. We pass it %Cell{} structs that each have a position and a ch.

The position is a struct representing an (x, y) cartesian coordinate. The top-left-most cell of the screen represents the origin (0, 0).

The ch should be an integer representing the character (e.g., ?a or 97). In the example, we're using charlists for this reason.

for {ch, x} <- Enum.with_index('Hello, World!') do
  :ok = Termbox.put_cell(%Cell{position: %Position{x: x, y: 0}, ch: ch})
end

for {ch, x} <- Enum.with_index('(Press <q> to quit)') do
  :ok = Termbox.put_cell(%Cell{position: %Position{x: x, y: 2}, ch: ch})
end

Since Elixir is a functional language, it's good practice to avoid this sort of imperative style in real applications. Instead, you might build and transform a canvas defined as map or list of cells. Then, when your canvas is ready for rendering, it can be synced to termbox via put_cell/1 in one sweep. This is how the Ratatouille library works.

Until now, we've only updated termbox's internal buffer. To actually render the content to the screen, we need to call present/0:

Termbox.present()

When a key is pressed, it'll be sent to us by the event manager. Once we receive a 'q' key press, we'll shut down the application.

receive do
  {:event, %Event{ch: ?q}} ->
    :ok = Termbox.shutdown()
end

You can use this event-handling logic to respond to events any way you like---e.g., render different content, switch tabs, resize content, etc.

Finally, run the example like this:

mix run examples/hello_world.exs

You shuld see the text we rendered and be able to quit with 'q'.

Python Build Compatibility (Python 3.12+)

The version of the termbox C library bundled with :rrex_termbox v1.0.3 uses an older version of the waf build system. This version of waf contained code (import imp) that is incompatible with Python 3.12 and newer, causing the NIF compilation to fail if a modern Python version is your system default.

This fork includes a small patch directly within the bundled waf scripts (c_src/termbox/.waf3-2.0.14-e67604cd8962dbdaf7c93e0d7470ef5b/waflib/Context.py) to replace the incompatible code with its modern equivalent (importlib).

With this patch, :rrex_termbox should compile successfully using Python 3.12+ without requiring manual intervention or downgrading Python.

If you encounter build issues related to Python or waf, please ensure you are using a version of this library that includes this fix.

Installation

From Hex

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

def deps do
  [
    # {:rex_termbox, "~> 0.3"} # Original version
    {:rrex_termbox, "~> 1.0.3"} # @hydepwns updated fork
  ]
end

The Hex package bundles a compatible version of termbox. There are some compile hooks to automatically build and link a local copy of termbox for your application. This should happen the first time you build :rrex_termbox (e.g., via mix deps.compile).

So far the build has been tested on macOS and a few Linux distros. Please add an issue if you encounter any problems with the build.

From Source

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

# Make sure to clone *this* repository recursively to include submodules
git clone --recurse-submodules <your-fork-url>
cd rrex_termbox # Assuming the directory name matches the repo

The --recurse-submodules flag (--recursive before Git 2.13) is necessary in order to additionally clone the termbox source code, which is required to build this project.

Next, fetch the deps:

mix deps.get

Finally, try out the included event viewer application:

mix run examples/event_viewer.exs

If you see the application drawn and can trigger events, you're good to go. Use 'q' to quit the examples.

Distribution

Building a standalone executable for applications using :rrex_termbox requires some special consideration due to the included NIF (Native Implemented Function) for the termbox C library.

Standard Elixir tools like escript are not suitable because they do not correctly package the necessary shared object (.so) file located in the priv/ directory.

The recommended approach for creating distributable releases is to use Distillery or the built-in Elixir Releases. These tools are designed to handle NIFs correctly and will package your application along with the Erlang Runtime System (ERTS) and the compiled termbox NIF into a self-contained bundle.

Consult the documentation for Distillery or Elixir Releases for specific instructions on configuring your project for release builds.