ex_ncurses

Ncurses NIF for Elixir

What it does

ExNcurses is a NIF that let's you create text-based user interfaces and games. It connects Elixir to the ncurses library.

Differences from C ncurses

In general, this library provides a thin wrapper on most ncurses functions. That means that the documentation and examples for the C library should apply fairly directly. There are some differences:

• #defines are now atoms. For example, instead of KEY_UP for up arrow, you'll receive the atom :up.
• Keyboard input comes in as {ex_ncurses, :key, code} messages if you call listen/0. You can still call getch() like in C, but it doesn't have the semantics.
• Functions that take printf style arguments in C are available, but don't support arguments. It's expected that programs construct strings in Elixir like normal..

Installation

The package is available on hex.pm and can be installed by adding ex_ncurses to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_ncurses, "~> 0.3"}
  ]
end

Compiling

You will need to install the ncurses library and C header files first. Do this however is appropriate for your system.

Then the project can be compiled with

mix deps.get
mix compile

Examples

To run any of the example scripts, start them by invoking the run_example.sh:

./run_example.sh demo

More examples can be found at:

• Snake
• Spacelixir

FAQ

Why isn't anything being drawn to the screen

Try calling ExNcurses.refresh/0 or ExNcurses.wrefresh/1 if you're working in a window.

Hold up, x and y are swapped everywhere

That's the ncurses way. Everything is row and then column, so y comes first. The upper left is (0, 0).

What happened to the Elixir console

It's still there. It won't receive any input between calls to ExNcurses.initscr/1/ExNcurses.newterm/3 and ExNcurses.endwin/0. I'm still on the fence with what to do with the console. It could be redirected, output could be thrown away, etc. At the moment, you'll likely want to turn on the Elixir console logger so that it doesn't interfere with the display.

Something is crashing Erlang! What do I do

Try editing src/ex_ncurses.c and uncomment the #define DEBUG line. This logs timing and function entry/exit information to ex_ncurses.log. If something crashes, it should hopefully provide more information. Please post an issue if you find a crash with the log and details on how to reproduce. Or if you're up to it, please send a Pull Request with a fix. We appreciate any help you can provide to make this a better library.