README

term

term is a library that provides terminal handling for zig. It includes termios and terminfo capabilities on unix like platforms, plus a termbox like interface to the terminal.

The Term struct implements the termbox like interface, and it is planned to support windows, linux and other unix-like platforms in the future. But currently only linux is supported.

Installation

As this is a library to be used with zig, you can install it into your projects source code by using

git submodule add https://codeberg.org/gnarz/term term

Use

Either add term as a module to your build.zig and do

const term = @import("term");

or just do

const term = @import("term/term.zig");

then, term.ios contains the termios stuff, term.info contains the Terminfo struct that handles terminfo data, and term contains the Term struct that provides the simplified terminal interface.

Documentation

You can generate the documentation by calling

zig build docs

However, as zig’s documentation generator is experimental and seems to miss some of the functions, there is also the bit that follows here, and you may also have to refer to the source code.

term

Enums

Structs

Clipping

the Term struct maintains a clip rectangle. After creation and after calls to resetClip(), the clip rectangle contains the entire terminal screen, but you can change it using setClip(). Clipping works on all write* functions, and also on clear(). For the writeChar(), writeString() functions and the Writer returned by writer(), an overflow discipline can be set. If the written text is outside of the clip rectangle, this discipline will be honored. Horizontal disciplines are clip (just cut the text) or wrap (wrap around to the next line). Vertical disciplines are clip and scroll (scroll the clip rectangle up until the new text is visible). The writeCharAt() and writeStringAt() functions always clip the output data.

The cursor position is not bound by the clip rectangle.

Example

...
const allocator = ...; // some allocator
var term = Term.init(allocator);
defer term.deinit();

try term.setColor(7, 0);
try term.setAttribute(.Italic);
try term.setCell(10, 10, 'X');
try term.setCellUtf8(12, 10, "Ö");

while (true) {
  var evt = try term.pollEvent();

  if (needs_to_terminate) break;

  if (evt == .key) 
  // do something...

  term.update();
}

term.ios

check the man pages for the c functions for details. The constants needed for the functions are available from std.os.system.

Structs

Errors

Functions

These are the same as from C, so refer to man 3 termios.

term.info

This implements reading and querying of compiled terminfo files. Legacy and extended number formats are supported, as is the extended storage format. Terminfo data may be read from a file on disk or from a slice in memory.

Querying the predefined capabilities is done by their C name. The extended capabilities are referred to by their names, which are short and cryptic names. They have no long and friendly names. So the for example name for the shift-cursor-left key is Strings.key_sleft, as this is a predefined capability, but for shift-cursor-up it is Strings.kUP.

Enums

Structs

Errors

Example

...
const allocator = ...; // some allocator

var terminal = std.os.getenv("TERM");
if (terminal == null) return error.NOTTY;
var ti = try term.Terminfo.init(allocator, terminal.?);
defer ti.deinit();

// these are just functions that return values or pointers into the Terminfo
// struct's private memory
var has_meta_key: bool = ti.getBoolean(.has_meta_key);
var columns: i32 = ti.getNumber(.columns);
var clear_screen: []const u8 = ti.getString(.clear_screen);

// this returns a newly allocated string. There is a convenience function to
// deallocate this string using the same allocator that was used to allocate it.
var set_cursor: []const u8 = ti.getInterpolatedString(.cursor_address, .{y, x});
defer ti.freeInterpolatedString(set_cursor);
...

References