Terminfo

Terminfo is a terminfo parsing library for Crystal.

It supports:

1. Auto-detecting and searching for terminfo files
2. Parsing terminfo files using regular and extended format
3. Summarizing the content of terminfo files
4. Providing raw access to parsed terminfo data
5. Using internally stored terminfo data for most common terminals

It is implemented natively and does not depend on ncurses or other external library.

Installation

Add the dependency to shard.yml:

dependencies:
  terminfo:
    github: crystallabs/terminfo
    version: 0.8.1

Usage in a nutshell

Here is a basic example that parses a terminfo file, prints parsed headers, and accesses raw data.

require "terminfo"

# Using a module/mixin
class MyClass
  include Terminfo
end
my = MyClass.new # (No arguments provided will trigger term autodetection)

# Using a class
my = Terminfo::Data.new path: "/lib/terminfo/x/xterm"

# Using internal 'xterm' definition
my2 = Terminfo::Data.new builtin: "xterm"

p my.header.to_h
p my.extended_header.to_h

# Print out a couple raw values. Use p() which inspects variables
# instead of puts() which would output escape sequences to the terminal.
p my.booleans["auto_left_margin"] # => false
p my.numbers["columns"]           # => 80
p my.strings["back_tab"]          # => \e[Z

Terminfo initialization

Terminfo can read terminfo data from files on disk as well as from internal (compiled-in) storage. There are a total of 4 ways to initialize:

(1) For specific terminfo files, specify absolute or relative path:

data = Terminfo::Data.new path: "/path/to/t/terminfo_file"

(2) For lookup in default terminfo directories, specify term name:

data = Terminfo::Data.new term: "xterm"

The default directory search order, from first to last:

ENV["TERMINFO_DIRS"]/     # (List of directories split by ":")
ENV["HOME"]/.terminfo/
/usr/share/terminfo/
/usr/share/lib/terminfo/
/usr/lib/terminfo/
/usr/local/share/terminfo/
/usr/local/share/lib/terminfo/
/usr/local/lib/terminfo/
/usr/local/ncurses/lib/terminfo/
/lib/terminfo/

Directory search order can be changed by modifying Terminfo.directories.

A file is searched in each directory using the following attempts:

./file
./f/file
./f/fi/file
./66/file # 66 == hex("file"[0].bytes)

(3) For lookup in the module's built-in storage, specify built-in name:

data = Terminfo::Data.new builtin: "xterm"

Built-in terminfo definitions can be changed by modifying the contents of the directory filesystem/. Currently available built-in terminfo files are:

linux
windows-ansi
xterm
xterm-256color

(4) For autodetection, call initialize with no arguments:

data = Terminfo::Data.new

If environment variable ENV["TERMINFO"] is set, term definition will be read from the specified file.

Otherwise, term name will be read from ENV["TERM"] and the corresponding terminfo file will be searched in the above documented directories.

If TERMINFO and TERM are unset, a built-in default of "xterm" will be used.

Terminfo data

Once you have instantiated Terminfo in one of the ways shown above, the following parsed properties and data structures will be available:

data = Terminfo::Data.new term: "xterm"

pp data

#<Terminfo::Data
 @name="xterm",
 @names=["xterm-debian"],
 @description="X11 terminal emulator",

 @header=
  #<Terminfo::Header
   @booleans_size=38,
   @data_size=3360,
   @header_size=12,
   @magic_number=282,
   @names_size=41,
   @numbers_size=15,
   @strings_size=413,
   @strings_table_size=1397,
   @total_size=2344>,

 @extended_header=
  #<Terminfo::ExtendedHeader
   @booleans_size=2,
   @header_size=10,
   @last_strings_table_offset=750,
   @numbers_size=0,
   @strings_size=62,
   @strings_table_size=126,
   @symbol_offsets_size=64,
   @total_size=262>,

 @booleans=
  {"auto_left_margin" => false,
  # ...
  "backspaces_with_bs" => true},

 @numbers=
  {"columns" => 80,
  # ...
  "max_pairs" => 64},

 @strings=
  {"back_tab" => "\e[Z",
  # ...
  "memory_unlock" => "\em"}>

 @extended_booleans=
  {"AX" => true,
  # ...
  "XT" => true},

 @extended_numbers=
  {"some_name" => 0,
  # ...
  },

 @extended_strings=
  {"Cr" => "\e]112\a",
  # ...
  "kc2" => ""}

API documentation

Run crystal docs as usual, then open file docs/index.html.

Also, see examples in the directory examples/.

Testing

Run crystal spec as usual.

Also, see examples in the directory examples/.

Thanks

• All the fine folks on FreeNode IRC channel #crystal-lang and on Crystal's Gitter channel https://gitter.im/crystal-lang/crystal

Other projects

List of interesting or related projects in no particular order:

• https://github.com/crystallabs/tput - Low-level component for building term/console applications in Crystal
• https://github.com/crystallabs/term_colors - Term/console color manipulation library for Crystal
• https://github.com/bew/unibilium.cr - Unibilium bindings for crystal - A terminfo parsing library
• https://github.com/bew/terminfo.cr - A Crystal library to parse terminfo database