TERMBOX2-NIF

About The Project

A modern, cross-platform BEAM (Erlang/Elixir/Gleam) wrapper for the termbox2 terminal UI library.

• Erlang NIF API: Low-level, direct access to termbox2 from Erlang.
• Elixir wrapper: Ergonomic, idiomatic Elixir API for TUI development.
• Gleam wrapper: Type-safe, functional API for Gleam projects.

Published on Hex.pm:https://hex.pm/packages/termbox2_nif

Note: The repository name was changed because the original "termbox2" name was already taken by the upstream C project. This package provides BEAM/Elixir/Erlang/Gleam bindings for termbox2, not the original C library itself.

Table of Contents

• About The Project
• Getting Started
• Usage
  • Erlang Quickstart
  • Elixir Quickstart
  • Gleam Quickstart
• Testing & NIF Loading
• Advanced/Wrapper-Specific Docs
• Roadmap
• License
• Wrappers Summary

Getting Started

Prerequisites

• Erlang/OTP 22+
• make
• C compiler (GCC/Clang)

Installation

Erlang

Add to your rebar.config:

{deps, [
  {termbox2_nif, {path, "termbox2_nif"}}
]}.

Fetch and compile:

rebar3 get-deps
rebar3 compile

Elixir

See wrappers/elixir/README.md for full instructions.

Gleam

See wrappers/gleam/README.md for full instructions.

Usage

Erlang Quickstart

%% Define default attributes (foreground/background)
-define(TB_DEFAULT, 0).

ok = termbox2_nif:tb_init(),
ok = termbox2_nif:tb_clear(),
Str = "Hello, termbox!",
X = 1, Y = 1,
Fg = ?TB_DEFAULT, Bg = ?TB_DEFAULT,
ok = termbox2_nif:tb_print(X, Y, Fg, Bg, Str),
ok = termbox2_nif:tb_present(),
{ok, _Type, _Mod, _KeyOrChar} = termbox2_nif:tb_poll_event(),
ok = termbox2_nif:tb_shutdown().

Elixir Quickstart

# In your mix.exs, add:
# {:termbox2, path: "wrappers/elixir"}, {:termbox2_nif, "~> 2.0.0"}

:ok = Termbox2.init()
:ok = Termbox2.set_cell(0, 0, ?A, :red, :default)
:ok = Termbox2.present()
:ok = Termbox2.shutdown()

Gleam Quickstart

import termbox2_gleam
import termbox2_gleam.{Red, Default, set_cell_friendly, print_friendly}

pub fn main() {
  case termbox2_gleam.init() {
    Ok(_) -> {
      set_cell_friendly(0, 0, 65, Red, Default)
      print_friendly(1, 1, Red, Default, "Hello, world!")
      termbox2_gleam.present()
      termbox2_gleam.shutdown()
    }
    Error(e) -> {
      io.println("Failed to initialize termbox2: " <> e)
    }
  }
}

Testing & NIF Loading

• Erlang:
  • Run tests: rebar3 ct
  • NIF is loaded automatically when built via Makefile or rebar3.
• Elixir:
  • Run tests: cd wrappers/elixir && mix test
  • NIF is loaded automatically; no manual copying needed.
• Gleam:
  • Run tests: make gleam-test (from project root)
  • This copies the BEAM and sets the code path for NIF loading.
• All wrappers:
  • Run all tests: make build-all
  • No manual copying or symlinking of BEAM/NIF files is required for any wrapper.

If you encounter NIF loading errors, ensure you have built the project from the root using the Makefile or wrapper-specific instructions.

Advanced/Wrapper-Specific Docs

• Erlang NIF API
• Elixir wrapper documentation
• Gleam wrapper documentation

Roadmap

• Erlang NIF created
• Gleam wrapper created
• Elixir wrapper created
• More advanced TUI helpers
• Windows support improvements
• More property-based tests

See open issues for a full list of proposed features and known issues.

License

Distributed under the MIT License. See LICENSE for more information.

Wrappers Summary

• Erlang NIF: Low-level API (termbox2_nif/)
• Elixir: Ergonomic TUI API (wrappers/elixir/)
• Gleam: Type-safe TUI API (wrappers/gleam/)

NIF binary: built to termbox2_nif/priv/. Wrappers symlink/copy from here as needed.

Build all: make build-all (see Makefile for details)