NE.Console 3.0.0

NE.Console

A .NET library for terminal output that is meant to be looked at: panels, tables, progress bars, task lists, spinners, interactive prompts, levelled logging and rule-based highlighting — plus a live layout that repaints a whole screen in place.

Targets net10.0. One dependency: NE.Colors, which owns the colour table and everything that maps a colour down to what a terminal can show.

Install

dotnet add package NE.Console

Released to nuget.org.

A first look

using NE.Console.Rendering;
using NE.Console.Rendering.Logging;
using NE.Console.Rendering.Progress;

Panel.Render("NE.Console", ["Progress bars, tasks, spinners, prompts, logs and panels."]);

ConsoleLog.Info("Starting");

using ProgressBar progress = new();
progress.SetTotal(20).SetLabel("Downloading").Start();

for (var i = 0; i < 20; i++)
{
    progress.Advance();
    progress.SetStatusText($"{i + 1} of 20");
}

progress.Complete();

examples/DemoApp.Console walks through everything below; it needs a real terminal:

dotnet run --project examples/DemoApp.Console

What is in it

Colours come from NE.Colors: TextColor.From(ColorName.Comet) names one, Palette is the shortlist this library paints with, and TextColor.FromConsoleColor asks for one of the terminal's own sixteen instead.

The rendering model

Everything drawn in place is a list of strings, rebuilt from scratch every frame. ConsoleLayout holds regions in order, concatenates their lines into one frame and hands it to a renderer that diffs against the previous frame and rewrites only the lines that changed.

using ConsoleLayout screen = new();

DisplayRegion grid = new();
LogRegion events = new();

screen.UseFullScreen().AddRegion(grid).AddRegion(events).Start();

KeyLoop.Run(screen, key =>
{
    events.Append($"pressed {key.Key}");
    return key.KeyChar is 'q' or 'Q';
});

Two layout modes: the default draws below the cursor and scrolls with the terminal, while UseFullScreen() enters the alternate screen buffer and anchors the frame at the top, leaving the shell's scrollback untouched.

Worth knowing:

• Width is measured in visible characters. Use AnsiText.VisibleLength, PadRight, Truncate and Fit rather than string.Length — they skip SGR sequences, and anything coloured misaligns without them.
• A full-screen frame is cut at the bottom without saying so, at ConsoleViewport.Height.
• A Panel without SetWidth resizes to its content, so a panel sharing a row with something else jumps as that content changes. Pin the width.
• Console.WriteLine during a live layout is intercepted, erased around and repainted. Writing to the console any other way corrupts the frame.
• Colour capability is detected once, at first touch of TerminalCapabilities.Current, and lands on one of four modes: true colour, 256 colours, the sixteen slots, or none. NO_COLOR forces the last and FORCE_COLOR paints even where ANSI was not detected. Below true colour a colour is mapped to the nearest palette entry or the nearest slot. Assign TerminalCapabilities.Current to declare a terminal instead of detecting one — which is what a test of anything coloured has to do, because on a build agent output is redirected and detection turns colour off.

Asking questions

Prompts own the keyboard from the call until they return an answer:

SelectPrompt colors = new("Pick a colour:");
colors.AddOption("Red").AddOption("Green").AddOption("Blue").AllowCustomAnswer();

var picked = colors.Ask();

SelectionList is the other shape: a region that draws itself into a frame and moves on arrows, Tab and digits, while the caller keeps the key loop and decides what confirming means. Use it when the list is part of the picture rather than an interruption.

Contributing

This repository is a read-only mirror. Development happens in a private repository and everything here is generated from it, so pull requests are switched off here — anything merged would be erased by the next release.

Issues are open and welcome — bugs, questions and feature requests all belong here.

License

MIT. See LICENSE.