Harlock (harlock v0.2.0)

Harlock — a pure-Elixir TUI framework for Unix terminals.

The two entry points:

Harlock.run/2 — blocking. Starts the app, returns when it exits.
Harlock.start_link/2 — non-blocking. Returns a supervisor pid for embedding inside an existing OTP application.

v0.1 is under construction; the smoke functions are scaffold tooling.

Summary

Functions

Start an app and block until it exits. Returns {:ok, reason} on normal exit, {:error, reason} if the supervisor failed to start.

smoke()

Round-trip smoke test. Opens /dev/tty, writes a greeting in the alt-screen, reads up to 5 bytes from the user, echoes what was typed, and restores the terminal. Should leave the terminal in a usable state after returning.

smoke_crash()

Crash-path smoke test. Spawns a linked child that opens /dev/tty and then raises. with_raw's nested try/after blocks restore the terminal before the process dies. Returns {cleanup, reason} where cleanup is :ok if the restore ran.

start_link(app, init_arg \\ nil, opts \\ [])

Start an app under the caller's supervision tree without blocking.

Types

app()

@type app() :: module()

init_arg()

@type init_arg() :: any()

Functions

run(app, init_arg \\ nil, opts \\ [])

@spec run(app(), init_arg(), keyword()) :: {:ok, term()} | {:error, term()}

Start an app and block until it exits. Returns {:ok, reason} on normal exit, {:error, reason} if the supervisor failed to start.

The caller's process is linked to the app supervisor, so killing the caller tears down the supervisor cleanly — which in turn restores the terminal.

Options:

:theme — a Harlock.Theme.t() (or keyword list / map convertible via Harlock.Theme.build/1). Defaults to Harlock.Theme.default/0.

smoke()

@spec smoke() :: binary() | {:error, term()}

smoke_crash()

@spec smoke_crash() :: {:ok | :no_cleanup | term(), term()}

start_link(app, init_arg \\ nil, opts \\ [])

@spec start_link(app(), init_arg(), keyword()) :: Supervisor.on_start()

Start an app under the caller's supervision tree without blocking.

Returns {:ok, sup_pid}. The caller is responsible for handling the supervisor's lifecycle (linking, monitoring, stopping). Useful when embedding Harlock inside a larger OTP app — e.g. a Phoenix project with a dev-mode TUI dashboard.

Accepts the same options as run/3.