https://github.com/docelic/terminfo
Library for parsing standard and extended terminfo files
https://github.com/docelic/terminfo
console crystal crystal-lang linux terminal terminfo terminfo-data terminfo-files
Last synced: 12 days ago
JSON representation
Library for parsing standard and extended terminfo files
- Host: GitHub
- URL: https://github.com/docelic/terminfo
- Owner: docelic
- License: mit
- Created: 2019-11-16T00:54:42.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-12-14T00:17:54.000Z (over 4 years ago)
- Last Synced: 2025-02-26T15:54:04.882Z (3 months ago)
- Topics: console, crystal, crystal-lang, linux, terminal, terminfo, terminfo-data, terminfo-files
- Language: Crystal
- Size: 205 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.com/crystallabs/terminfo)
[](https://github.com/crystallabs/terminfo/releases/latest)
[](https://github.com/crystallabs/terminfo/blob/master/LICENSE)
# Terminfo
Terminfo is a terminfo parsing library for Crystal.
It supports:
1. Auto-detecting and searching for terminfo files
1. Parsing terminfo files using regular and extended format
1. Summarizing the content of terminfo files
1. Providing raw access to parsed terminfo data
1. 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`:
```yaml
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.
```crystal
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:
```crystal
data = Terminfo::Data.new path: "/path/to/t/terminfo_file"
```
(2) For lookup in default terminfo directories, specify term name:
```crystal
data = Terminfo::Data.new term: "xterm"
```
The default directory search order, from first to last:
```crystal
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:
```crystal
./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:
```crystal
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:
```crystal
linux
windows-ansi
xterm
xterm-256color
```
(4) For autodetection, call `initialize` with no arguments:
```crystal
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:
```crystal
data = Terminfo::Data.new term: "xterm"
pp data
#,
@extended_header=
#,
@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