class

Termisu::Terminfo::Parser

Inherits Reference / Object

Binary terminfo database parser.

Parses compiled terminfo database files in the ncurses binary format, supporting both standard 16-bit and extended 32-bit formats. The parser uses name-based capability lookup via the Capabilities::STRING_CAPS ordering to map capability names to their escape sequences.

Binary Format

The terminfo binary format consists of:

  • Header (12 bytes): Magic number and section sizes
  • Names section: Terminal names (pipe-separated)
  • Booleans section: Boolean capabilities (1 byte each)
  • Numbers section: Numeric capabilities (2 or 4 bytes each)
  • Strings section: String capability offsets (2 bytes each)
  • String table: Null-terminated string data

Format Detection

  • Magic 0o432 (282): Standard format with 16-bit numbers
  • Magic 542: Extended format with 32-bit numbers

Error Handling

The parser raises ParseError with specific error types:

  • InvalidMagic: Unrecognized format identifier
  • TruncatedData: File smaller than header indicates
  • InvalidHeader: Negative or unreasonable header values
  • InvalidOffset: String offsets point outside data bounds

Usage

data = File.read("/usr/share/terminfo/x/xterm-256color")
caps = Parser.parse(data, ["clear", "bold", "smcup"])
# Raises ParseError if data is malformed

Constants

EXTENDED_MAGIC = 542_i16

Magic number for extended 32-bit terminfo format.

HEADER_LENGTH = 12

Size of terminfo binary header in bytes.

MAGIC = 282_i16

Magic number for standard 16-bit terminfo format.

MAX_BOOLEANS_COUNT = 512
MAX_NAMES_LENGTH = 4096

Maximum reasonable header values to detect corruption.

MAX_NUMBERS_COUNT = 512
MAX_STRINGS_COUNT = 512
MAX_TABLE_SIZE = 65536

Constructors

new(data : Bytes)
Source

Class methods

parse(data : Bytes, cap_names : Array(String)) : Hash(String, String)

Parses terminfo binary data and returns requested capabilities.

Creates a new parser instance and extracts the specified capabilities from the terminfo database.

Parameters

  • data: Raw terminfo binary data
  • cap_names: Array of capability names to extract (e.g., ["clear", "bold"])

Returns

Hash mapping capability names to their escape sequence values.

Raises

  • ParseError if the data is malformed or corrupted
Source
parse?(data : Bytes, cap_names : Array(String)) : Hash(String, String) | Nil

Parses terminfo data, returning nil on parse errors instead of raising.

Useful when you want to handle parse failures gracefully without exceptions.

Returns

Hash of capabilities, or nil if parsing failed.

Source

Instance methods

parse(required_caps : Array(String)) : Hash(String, String)

Parses capability values from terminfo binary data.

Resolves each requested capability name to its STRING_CAPS index and decodes only those entries from the strings section, skipping the hundreds of unrequested capabilities a terminfo file typically carries.

Parameters

  • required_caps: Capability names to extract

Returns

Hash of capability name => escape sequence. Missing capabilities are omitted.

Raises

  • ParseError with specific type on malformed data
Source