Icod.TermInfo 0.9.0

Icod.TermInfo

Icod.TermInfo is a managed, dependency-free .NET implementation of the low-level terminal-capability model traditionally supplied by libtinfo.

Version 0.9.0 is the arbitrary-terminal acquisition release. It retains the complete 0.8 in-memory semantic model and adds a pure compiled-terminfo byte parser, explicit conventional-directory loading, deterministic TERMINFO/TERMINFO_DIRS/user/system discovery, and provider-local cache/refresh semantics without introducing a native ncurses dependency or process-global current terminal.

The package targets net10.0, uses C# 13, contains no native ncurses/terminfo payload, and is intended to run on Windows, Linux, and macOS.

Install

For the 0.9.0 release:

dotnet add package Icod.TermInfo --version 0.9.0

The same package contents are intended for NuGet.org and GitHub Packages. Repository development can reference Icod.TermInfo.csproj directly, as the sample project does.

What 0.9.0 provides

• immutable terminal descriptions with canonical name, aliases, and a separate verbose Description;
• a complete ncurses/System V-compatible standard capability catalog: 44 Boolean, 39 numeric, and 414 string table positions;
• canonical standard-capability metadata including fixed future binary index, short name, long/variable name, termcap code, and managed enum identity;
• deterministic read-only enumeration of the standard catalog and of effectively present standard capabilities on each description;
• signed 32-bit standard and extended numeric semantics;
• generic extended Boolean, numeric, and string capabilities with exact case-sensitive names;
• reusable parsed terminfo parameter programs, hardened parsing/evaluation, and per-description bounded lazy expansion caches;
• explicit ExpandExtendedString symmetry for parameterized extended strings;
• reversible 8-bit capability-string semantics: bytes 0x01-0xFF map one-to-one through .NET strings and round-trip with Encoding.Latin1;
• simple and terminal-aware tputs/putp-style output, including xon, pb, npc, pad, affected-line multiplication, and caller-supplied baud-rate semantics;
• semantic monochrome, indexed-color, and direct-RGB inspection and selector expansion;
• built-in dumb, ANSI, DEC VT100/VT102/VT220, xterm indexed/direct-color, winconsole, ms-terminal, and ms-terminal-direct profiles;
• descriptive mouse, focus, bracketed-paste, modified-key, cursor-style, reporting, and clipboard metadata where the selected profile advertises it;
• live terminal-size queries kept distinct from environment/profile defaults;
• explicit and reversible Windows virtual-terminal output enablement, separate from profile selection;
• pure parsing of supported conventional compiled terminfo entries from caller-supplied bytes;
• caller-owned explicit conventional-directory providers with literal/hex first-character lookup and identity verification;
• deterministic system discovery through encoded or directory TERMINFO, user .terminfo, ordered TERMINFO_DIRS, and frozen platform defaults;
• provider-local successful-entry caching with retryable clean misses/failures and new-provider refresh semantics;
• explicit provider composition, including system lookup followed by immutable built-in fallback.

The 0.6.0 behavior of dumb, ansi, and vt100 remains intentionally conservative: dumb is minimal, ansi is the traditional eight-color profile, and vt100 remains monochrome.

Getting started

Terminal resolution remains explicit and conservative. A normal application can search the host database first and then fall back to the immutable built-ins:

using Icod.TermInfo;

TerminalDatabase database =
    new(
        new ITerminalDescriptionProvider[]
        {
            new SystemTerminalDescriptionProvider(),
            TerminalDatabase.BuiltIn,
        });

TerminalDescription terminal =
    TerminalEnvironment.Resolve(
        database,
        TerminalProfiles.Dumb);

Console.WriteLine($"Terminal profile: {terminal.Name}");

TerminalDatabase.BuiltIn remains environment-independent and I/O-free. Unknown names are not silently coerced to ANSI, VT100, or xterm.

To select a known modern profile explicitly:

TerminalDescription xterm =
    TerminalDatabase.BuiltIn.Load("xterm");

TerminalDescription xterm256 =
    TerminalDatabase.BuiltIn.Load("xterm-256color");

TerminalDescription xtermDirect =
    TerminalDatabase.BuiltIn.Load("xterm-direct256");

TerminalDescription winConsole =
    TerminalDatabase.BuiltIn.Load("winconsole");

TerminalDescription windowsTerminal =
    TerminalDatabase.BuiltIn.Load("ms-terminal");

TerminalDescription windowsTerminalDirect =
    TerminalDatabase.BuiltIn.Load("ms-terminal-direct");

Aliases remain exact and intentional. For example, vt100-am resolves to vt100, and vt200 resolves to vt220. Windows identities are not aliases for ANSI or xterm.

Standard and extended capabilities

Typed lookup is the preferred API for standard capabilities:

bool automaticMargins =
    terminal.GetBoolean(BooleanCapability.AutoRightMargin);

int? columns =
    terminal.GetNumber(NumericCapability.Columns);

string? clear =
    terminal.GetString(StringCapability.ClearScreen);

Traditional short-name lookup remains available:

bool hasColors = terminal.TryGetNumber("colors", out int colors);
bool hasClear = terminal.TryGetString("clear", out string? clear);

The complete standard catalog is inspectable in compiled-table order. Managed enum values are deliberately independent from those binary indices:

StandardCapabilityMetadata<StringCapability> cupMetadata =
    StandardCapabilityCatalog.GetMetadata(
        StringCapability.CursorAddress);

Console.WriteLine(
    $"{cupMetadata.ShortName}: binary index {cupMetadata.BinaryIndex}");

foreach (StandardCapabilityMetadata<NumericCapability> metadata
    in StandardCapabilityCatalog.NumericCapabilities)
{
    Console.WriteLine(
        $"{metadata.ShortName} / {metadata.LongName}");
}

A terminal description also exposes its effective standard capabilities in the same deterministic order:

Console.WriteLine(terminal.Description ?? "(no verbose description)");

foreach (KeyValuePair<NumericCapability, int> capability
    in terminal.NumericCapabilities)
{
    Console.WriteLine($"{capability.Key} = {capability.Value}");
}

Absent and internally canceled capabilities do not appear as effective present values. Extended capabilities remain separately enumerable through ExtendedCapabilities.

Modern capabilities which are not part of the fixed standard terminfo vocabulary are carried through the extended-capability store:

if (xterm.TryGetExtendedString("BE", out string? enablePaste))
{
    Console.WriteLine("Bracketed-paste enable metadata is present.");
}

if (xterm.TryGetExtendedString("XM", out _))
{
    string enableMouse =
        xterm.ExpandExtendedString("XM", 1);
}

Extended names are case-sensitive. Standard capability names cannot be silently shadowed by extended capabilities.

Reusable arbitrary-source parameter programs can be parsed once and expanded repeatedly. Structural/type analysis remains internal safety machinery rather than a second public model:

TermInfoParameterProgram program =
    TermInfoParameterProgram.Parse("%p1%{1}%+%d");

Console.WriteLine(program.Source);     // %p1%{1}%+%d
Console.WriteLine(program.Expand(41)); // 42

Per-description standard and extended expansion use bounded lazy caches owned by the immutable description. There is no process-global arbitrary-string cache.

Color inspection

Color semantics are derived from raw terminfo data rather than from terminal-name checks:

TerminalColorSupport support =
    TerminalColors.GetColorSupport(xterm256);

Console.WriteLine(support.Model);             // Indexed
Console.WriteLine(support.Tier);              // Color256
Console.WriteLine(support.IndexedColorCount); // 256

Raw colors, pairs, ncv, selectors, bce, ccc, hls, initc, op, oc, and extended RGB/CO metadata remain authoritative. pairs is never synthesized from colors.

Indexed color

Use the semantic helper rather than embedding ANSI escape strings:

string foreground =
    TerminalColors.ExpandForeground(
        TerminalProfiles.Xterm256Color,
        196);

TermInfoOutput.PutP(foreground, Console.Out);

The helper validates the terminal's advertised indexed range and expands the terminal's own setaf capability through the shared parameter engine.

Direct RGB color

Direct profiles expose an RGB layout and any retained indexed prefix:

TerminalDescription direct =
    TerminalProfiles.XtermDirect256;

TerminalColorSupport support =
    TerminalColors.GetColorSupport(direct);

TerminalRgbColor purple =
    new(0x80, 0x40, 0xC0);

string foreground =
    TerminalColors.ExpandForeground(
        direct,
        purple);

The selected xterm direct profiles use packed 8/8/8 RGB semantics and retain 8, 16, or 256 indexed entries according to their CO metadata. The library validates collisions between packed RGB values and that retained indexed prefix instead of guessing.

Cursor positioning and full-screen primitives

Parameterized standard capabilities use the same terminfo expansion engine:

string move =
    xterm.Expand(
        StringCapability.CursorAddress,
        10,
        20);

Profiles can also advertise cursor-addressing lifecycle and cursor-visibility primitives:

string? enter =
    xterm.GetString(StringCapability.EnterCursorAddressingMode);
string? leave =
    xterm.GetString(StringCapability.ExitCursorAddressingMode);
string? hideCursor =
    xterm.GetString(StringCapability.CursorInvisible);
string? normalCursor =
    xterm.GetString(StringCapability.CursorNormal);

These are capability strings, not a session manager. Icod.TermInfo does not decide when to enter full-screen mode, hide the cursor, recover from exceptions, or restore terminal state. A caller or future higher-level terminal library owns that lifecycle.

Mouse, focus, paste, and clipboard metadata

The modern xterm profiles carry descriptive protocol metadata such as:

• standard kmous plus extended XM/xm mouse strings;
• focus enable/disable and focus-in/focus-out strings;
• bracketed-paste enable/disable and begin/end strings;
• modified-key strings;
• cursor-style and terminal-reporting strings;
• OSC 52 clipboard/selection metadata where present in the selected profile.

This package does not decode mouse events, focus events, keys, or paste payloads. It also does not perform clipboard operations or terminal probing. The metadata is intentionally available so a future Icod.Terminal-style layer can consume it without teaching Icod.TermInfo about live input state.

VT100 and padding

VT100 strings preserve their historical terminfo padding annotations through parameter expansion:

TerminalDescription vt100 = TerminalProfiles.Vt100;

string move =
    vt100.Expand(
        StringCapability.CursorAddress,
        10,
        20);

// move contains ESC[11;21H$<5>

Applications should emit capability strings through the output layer. Modern terminals normally use the default PaddingMode.Ignore, which removes delay annotations without writing them literally:

TermInfoOutput.TPuts(
    move,
    affectedLines: 1,
    Console.Out);

Physical or serial terminals can opt into delays:

TermInfoOutput.TPuts(
    move,
    affectedLines: 1,
    Console.Out,
    PaddingMode.Delay);

The output API also supports asynchronous TextWriter output, byte streams with a caller-selected encoding, character callbacks, and an injectable ITermInfoDelayProvider.

Exact capability bytes

Capability strings are protocol byte data, not application text. For data originating in conventional compiled terminfo, Icod.TermInfo uses a one-to-one Latin-1 bridge: byte 0x80 is represented by \u0080, byte 0xFF by \u00FF, and so on. Use Encoding.Latin1 when exact capability bytes must be emitted:

using MemoryStream stream = new();

TermInfoOutput.TPuts(
    "\u0080",
    affectedLines: 1,
    stream,
    Encoding.Latin1);

byte[] bytes = stream.ToArray(); // { 0x80 }

This does not prescribe the encoding of application text. Text encoding remains caller-owned.

Terminal-aware padding

When padding policy needs terminal facts, pass immutable TermInfoOutputOptions explicitly:

TermInfoOutputOptions options =
    new(
        vt100,
        baudRate: 9600,
        paddingMode: PaddingMode.Delay);

TermInfoOutput.TPuts(
    move,
    affectedLines: 1,
    Console.Out,
    options);

The library never discovers baud rate and never owns a tty/file descriptor. Advisory padding is suppressed according to the terminal's xon and pb capabilities; mandatory padding remains mandatory unless the caller explicitly chooses PaddingMode.Ignore. PaddingMode.PadCharacters also honors npc and pad.

Compatibility-shaped API

TermInfoCompatibility provides familiar terminfo operation names while retaining managed semantics and explicit terminal ownership:

bool am =
    TermInfoCompatibility.TiGetFlag(xterm, "am");

int? colorCount =
    TermInfoCompatibility.TiGetNum(xterm, "colors");

string? cup =
    TermInfoCompatibility.TiGetStr(xterm, "cup");

There is no process-global cur_term, no sentinel-pointer result, and no hidden persistent expansion state. Persistent uppercase %P/%g variables require an explicit caller-owned TermInfoExpansionContext.

Terminal size

Live dimensions are distinct from configured and profile-default dimensions:

TerminalSize size;

if (TerminalEnvironment.TryGetLiveSize(out size))
{
    Console.WriteLine($"Live: {size.Columns}x{size.Rows}");
}
else if (TerminalEnvironment.TryGetEnvironmentSize(out size))
{
    Console.WriteLine($"Configured: {size.Columns}x{size.Rows}");
}
else if (TerminalEnvironment.TryGetProfileSize(terminal, out size))
{
    Console.WriteLine($"Profile default: {size.Columns}x{size.Rows}");
}

A failed live query never substitutes COLUMNS/LINES or a profile default. Fallback order belongs to the caller.

Windows virtual-terminal output

Windows VT output mode is always opt-in:

using IDisposable? mode =
    WindowsVirtualTerminal.TryEnableOutput();

The helper returns null on non-Windows systems, redirected output, non-console handles, or when Windows refuses the mode change. When it changes console mode, disposing the returned lease restores the exact previous mode. Loading a terminal profile never changes console state.

Windows profile selection is separate and side-effect free:

TerminalDescription console =
    TerminalProfiles.WinConsole;

TerminalDescription wt =
    TerminalProfiles.MsTerminal;

TerminalDescription wtDirect =
    TerminalProfiles.MsTerminalDirect;

winconsole describes the authoritative modern Windows Console terminfo identity. ms-terminal is the indexed-color Windows Terminal identity, while ms-terminal-direct advertises direct RGB through the same generic color engine used by other profiles. WT_SESSION, WT_PROFILE_ID, and COLORTERM do not silently select or mutate any profile.

Custom terminal providers

Applications can add descriptions without changing the built-in database or generic engines:

TerminalDescription example =
    new TerminalDescriptionBuilder("example-terminal")
        .SetBoolean(BooleanCapability.AutoRightMargin)
        .SetNumber(NumericCapability.Columns, 80)
        .SetNumber(NumericCapability.Lines, 24)
        .SetExtendedBoolean("exampleFlag")
        .SetExtendedString("exampleString", "value")
        .Build();

ITerminalDescriptionProvider provider =
    new InMemoryTerminalDescriptionProvider(
        new[] { example });

TerminalDatabase database =
    new(new[] { provider });

Provider ordering is explicit and deterministic; the first provider that resolves a name wins.

Compiled terminfo acquisition

For a task-oriented explanation of parser formats, directory layout, discovery precedence, option boundaries, errors, caching, and refresh, see docs/0.9.0-ACQUISITION-GUIDE.md. The focused samples/Icod.TermInfo.Acquisition.Sample executable demonstrates the same public acquisition paths without emitting terminal-control strings.

Parse caller-supplied bytes

The parser is independently usable and has no filesystem or environment dependency:

byte[] entry = File.ReadAllBytes("xterm.compiled");

TerminalDescription parsed =
    CompiledTermInfoParser.Parse(entry);

CompiledTermInfoParserOptions bounds accepted entry size. Malformed or unsupported compiled data throws CompiledTermInfoFormatException; it is not reported as a clean provider miss.

Load an explicit directory

When an application owns a conventional terminfo directory tree, use DirectoryTerminalDescriptionProvider:

ITerminalDescriptionProvider applicationTermInfo =
    new DirectoryTerminalDescriptionProvider(
        "/opt/myapp/share/terminfo");

TerminalDescription terminal =
    new TerminalDatabase(
        new[] { applicationTermInfo })
        .Load("my-terminal");

The provider performs exact-name lookup only and propagates malformed-entry, permission, and I/O failures.

Construct a restricted system provider

Each system discovery category can be disabled independently:

SystemTerminalDescriptionProvider restricted =
    new(
        new SystemTerminalDescriptionProviderOptions(
            useEnvironment: false,
            useUserDatabase: false,
            useSystemDatabases: false));

That provider has no enabled acquisition source and therefore returns a clean miss for valid terminal names.

Use normal system discovery

The default system provider snapshots its permitted discovery inputs at construction:

SystemTerminalDescriptionProvider system =
    new();

On non-Windows systems this can search encoded/directory TERMINFO, the user-local .terminfo database, TERMINFO_DIRS, and frozen platform defaults. Windows does not invent Unix-style implicit roots; explicit TERMINFO, TERMINFO_DIRS, and DirectoryTerminalDescriptionProvider remain available.

Compose system and built-in fallback

TerminalDatabase is itself an ITerminalDescriptionProvider, so built-in fallback remains explicit:

TerminalDatabase database =
    new(
        new ITerminalDescriptionProvider[]
        {
            new SystemTerminalDescriptionProvider(),
            TerminalDatabase.BuiltIn,
        });

The first provider which resolves the requested name wins. TerminalDatabase.BuiltIn is never mutated by system discovery.

Sample applications

The repository contains two executable samples with deliberately different purposes.

General terminal API sample

samples/Icod.TermInfo.Sample demonstrates:

• conservative environment resolution with an explicit dumb fallback;
• system-to-built-in provider composition for ordinary resolution;
• verbose description plus standard catalog/per-description enumeration;
• reusable standard and extended parameterized-string expansion;
• exact Latin-1 capability-byte output;
• terminal-aware padding with explicit terminal facts;
• semantic indexed/direct color inspection and expansion;
• Windows Console and Windows Terminal profile selection without side effects;
• full-screen/cursor-visibility capability discovery without taking ownership of a full-screen session;
• live/configured/profile size selection;
• redirection handling and explicit Windows VT enablement;
• a custom provider implementation.

Run the ordinary demonstration with:

dotnet run --project samples/Icod.TermInfo.Sample/Icod.TermInfo.Sample.csproj

For CI, documentation checks, or any environment where terminal-control output is inappropriate, use the non-interactive descriptive mode:

dotnet run --project samples/Icod.TermInfo.Sample/Icod.TermInfo.Sample.csproj -- --describe-only --profile xterm-direct256

--profile <name> selects an exact built-in profile instead of consulting TERM. --describe-only exercises metadata/enumeration, expansion, byte-output, padding, profile, color, and extended-capability APIs but emits no terminal-control strings to the active terminal.

Compiled terminfo acquisition sample

samples/Icod.TermInfo.Acquisition.Sample is a focused, non-interactive sample for the new 0.9 acquisition layer. It demonstrates:

parse <compiled-file>
directory <root> <terminal-name>
system <terminal-name>
restricted <terminal-name>
fallback <terminal-name>

For example:

dotnet run --project samples/Icod.TermInfo.Acquisition.Sample/Icod.TermInfo.Acquisition.Sample.csproj -- system xterm-256color

and:

dotnet run --project samples/Icod.TermInfo.Acquisition.Sample/Icod.TermInfo.Acquisition.Sample.csproj -- directory /usr/share/terminfo xterm

The sample prints the resolved terminal identity, aliases, selected numeric facts, and standard/extended capability counts. It does not write any capability string to the terminal.

See samples/README.md, samples/Icod.TermInfo.Acquisition.Sample/README.md, and docs/0.9.0-ACQUISITION-GUIDE.md for the complete examples.

Project-family boundary

Icod.TermInfo owns immutable terminal-description data, acquisition of that data, and pure transformations required to interpret, expand, and output terminal capabilities. It does not own a live terminal session, a child pseudo-terminal, or a virtual screen.

The intended family boundary is now explicit:

• Icod.TermInfo — descriptions, compiled-database acquisition, capability semantics, parameter expansion, and output transformation;
• future Icod.Terminal — raw/cooked session ownership, input decoding, keyboard/mouse/paste/focus events, active probing/negotiation, full-screen/cursor lifecycle, clipboard/hyperlink operations, and progress helpers;
• future Icod.Pty — Unix PTY and Windows ConPTY creation, resize propagation, and child-process plumbing;
• future Icod.Curses — Unicode cell/grid state, damage/refresh optimization, windows, pads, panels, menus, forms, and widgets;
• future source/tooling work — .ti parsing, use= inheritance, tic/infocmp-class tools, termcap conversion, and optional database-maintenance functionality.

The broader dependency inventory is recorded in docs/FUTURE-WORK-INVENTORY.md.

0.9.0 arbitrary-terminal acquisition

Version 0.8 completed terminfo semantics in memory. Version 0.9 adds the acquisition layer without redesigning that semantic model.

The implemented 0.9 dependency chain is:

pure compiled-byte parser
    -> explicit directory provider
    -> TERMINFO / TERMINFO_DIRS / user / platform discovery
    -> provider-local cache and refresh semantics
    -> frozen API/package contract

The parser independently accepts caller-supplied bytes and supports the frozen conventional 0432, ncurses extended-section, and 01036 / signed-32-bit formats. Directory and system providers reuse that parser rather than embedding their own binary logic. Encoded TERMINFO=hex:... and TERMINFO=b64:... entries use the same parser path.

0.9 deliberately does not include .ti source parsing, tic/infocmp, termcap, Berkeley-DB hashed terminfo stores, divergent historical vendor binary formats, live input/session management, active probing, PTYs, curses, terminal emulation, or graphics protocols.

See docs/0.9.0-ACQUISITION-GUIDE.md for the consumer-facing acquisition guide, Icod.TermInfo-Development-Roadmap-0.9.0.md for the detailed frozen tranche contract, docs/0.9.0-CONTRACT-AUDIT.md for the final completion evidence, docs/0.9.0-T40-API-PACKAGE-FREEZE.md for the release-candidate API/package freeze, and docs/FUTURE-WORK-INVENTORY.md for the post-0.9 dependency map.

Build, test, and pack

dotnet restore Icod.TermInfo.sln

dotnet build Icod.TermInfo.sln -c Debug
dotnet test Icod.TermInfo.sln -c Debug

dotnet build Icod.TermInfo.sln -c Release
dotnet test Icod.TermInfo.sln -c Release

dotnet pack Icod.TermInfo.csproj -c Release --output artifacts

Then run the release verifier appropriate to the host.

On Windows Command Prompt:

.github\scripts\verify-release-package.cmd artifacts

On a Bash-capable host:

bash .github/scripts/verify-release-package.sh artifacts

Both wrappers run the same C# metadata/package validation, an isolated package-reference-only smoke consumer, and the sample's non-interactive --describe-only path. Windows package validation does not require Bash or Python.

Only pushes to main run the Release build/test, package-validation, and publication workflow. Pull requests run the separate pr-build-and-test.yaml validation workflow and never publish packages. After the main Release matrix succeeds, package validation verifies the exact artifacts and the downstream Release deployment job publishes them to NuGet.org and GitHub Packages.

See docs/RELEASING.md for the release procedure and docs/0.9.0-CONTRACT-AUDIT.md for the final completion evidence. Tag v0.9.0 only after the exact final main candidate passes the complete workflow; no source/package content should change between that successful validation and tagging.

Scope

Icod.TermInfo is not curses, a terminal emulator, a PTY implementation, a termios session manager, an input-event parser, or a general terminal UI toolkit. It intentionally carries low-level descriptive data which those higher-level systems may consume.

See Icod.TermInfo-Development-Roadmap-0.8.0.md for the frozen 0.8.0 contract, Icod.TermInfo-Development-Roadmap-0.9.0.md for the 0.9.0 acquisition-release contract, and docs/FUTURE-WORK-INVENTORY.md for the broader terminal-system dependency map. The 0.6.0 and 0.7.0 roadmaps remain historical frozen contracts.

License

Licensed under the GNU Lesser General Public License v3.0 or later. See LICENSE.