terminfo
Terminfo
Terminfo is a terminfo parsing library for Crystal.
It supports:
- Auto-detecting and searching for terminfo files
- Parsing terminfo files using regular and extended format
- Summarizing the content of terminfo files
- Providing raw access to parsed terminfo data
- 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