Gapotchenko.FX.Console 2022.2.7

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
dotnet add package Gapotchenko.FX.Console --version 2022.2.7
NuGet\Install-Package Gapotchenko.FX.Console -Version 2022.2.7
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Gapotchenko.FX.Console" Version="2022.2.7" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Gapotchenko.FX.Console --version 2022.2.7
#r "nuget: Gapotchenko.FX.Console, 2022.2.7"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Gapotchenko.FX.Console as a Cake Addin
#addin nuget:?package=Gapotchenko.FX.Console&version=2022.2.7

// Install Gapotchenko.FX.Console as a Cake Tool
#tool nuget:?package=Gapotchenko.FX.Console&version=2022.2.7

Overview

The module provides virtual terminal functionality, console traits and useful primitives for .NET console apps.

Virtual Terminal

From the very beginning, computers used to employ teletypes as primary input/output devices. A teletype usually consisted of a keyboard and printer in a single box.

At later stages of development, teletypes were swapped with specialized computer terminals such as VT100. Those electronic devices provided not only the basic input/output capabilities, but also colors, pseudographics, and a custom control language based around a then-emerging ANSI X3.64 standard.

Unix operating systems have a built-in support for ANSI escape sequences that constitute the control language defined by the standard. Windows ignored that practice for a long time, up until Windows 10 version 1511.

What ANSI Escape Sequences Are Useful For?

Indeed, .NET base class library already provides System.Console class with ForegroundColor, BackroundColor and other properties for controlling the console.

ANSI escape sequences become handy when the complexity of console output reaches a certain level:

Advanced console visualization

It would be a very involved code to render such an output with a set of imperative calls.

But we can do better with ANSI escape sequences:

using Gapotchenko.FX.Console;
using System;

VirtualTerminal.EnableProcessing();

Console.WriteLine(
    "                 \x1b[35m__                     _             \x1b[34m_   _ ______ _______ \n" +
    "\x1b[42;32m██████\x1b[49m         \x1b[35m / _|                   | |           \x1b[34m| \\ | |  ____|__   __|\n" +
    "\x1b[42;32m██\x1b[49m     __ _ ___\x1b[35m| |_ _   _ ___  ___ __ _| |_ ___  _ __\x1b[34m|  \\| | |__     | |   \n" +
    "\x1b[42;32m█████\x1b[49m / _` |_  /\x1b[35m  _| | | / __|/ __/ _` | __/ _ \\| '__\x1b[34m| . ` |  __|    | |   \n" +
    "\x1b[42;32m██\x1b[49m   | (_| |/ /\x1b[35m| | | |_| \\__ \\ (_| (_| | || (_) | |\x1b[34m_ | |\\  | |____   | |   \n" +
    "\x1b[42;32m██████\x1b[49m\\__,_/___|\x1b[35m_|  \\__,_|___/\\___\\__,_/___\\___/|_(\x1b[34m_)|_| \\_|______|  |_|\x1b[0m");

Please note that the implementation starts with a call to VirtualTerminal.EnableProcessing method. It is provided by Gapotchenko.FX.Console module and ensures that support of ANSI escape sequences is activated for the console. In case when the host OS does not provide a native support for them, the method switches to a virtual terminal emulation.

In this way, ANSI X3.64 control language is guaranteed to work on the widest range of host operating systems.

Console Traits

Gapotchenko.FX.Console module provides ConsoleTraits class that allows to programmatically retrieve the current console capabilities.

IsColorAvailable

ConsoleTraits.IsColorAvailable boolean property indicates whether console color output is available. Console color is usually always available unless program standard output streams are redirected.

IsColorInhibited

ConsoleTraits.IsColorInhibited boolean property indicates whether console color output is inhibited.

Console color may be inhibited by the host system or a user preference. For example, a NO_COLOR environment variable can be used to inhibit console colors as described by the corresponding specification.

IsColorEnabled

ConsoleTraits.IsColorEnabled boolean property indicates whether console color output is enabled. The console color is enabled when it is available and not inhibited.

The value of the property can be used by a program to automatically tune the output according to the usage context and user preference. Like so:

if (ConsoleTraits.IsColorEnabled)
{
    Console.WriteLine(
        "                 \x1b[35m__                     _             \x1b[34m_   _ ______ _______ \n" +
        "\x1b[42;32m██████\x1b[49m         \x1b[35m / _|                   | |           \x1b[34m| \\ | |  ____|__   __|\n" +
        "\x1b[42;32m██\x1b[49m     __ _ ___\x1b[35m| |_ _   _ ___  ___ __ _| |_ ___  _ __\x1b[34m|  \\| | |__     | |   \n" +
        "\x1b[42;32m█████\x1b[49m / _` |_  /\x1b[35m  _| | | / __|/ __/ _` | __/ _ \\| '__\x1b[34m| . ` |  __|    | |   \n" +
        "\x1b[42;32m██\x1b[49m   | (_| |/ /\x1b[35m| | | |_| \\__ \\ (_| (_| | || (_) | |\x1b[34m_ | |\\  | |____   | |   \n" +
        "\x1b[42;32m██████\x1b[49m\\__,_/___|\x1b[35m_|  \\__,_|___/\\___\\__,_/___\\___/|_(\x1b[34m_)|_| \\_|______|  |_|\x1b[0m");
}
else
{
    Console.WriteLine(
@" ______           __                     _             _   _ ______ _______ 
|  ____|         / _|                   | |           | \ | |  ____|__   __|
| |__   __ _ ___| |_ _   _ ___  ___ __ _| |_ ___  _ __|  \| | |__     | |   
|  __| / _` |_  /  _| | | / __|/ __/ _` | __/ _ \| '__| . ` |  __|    | |   
| |___| (_| |/ /| | | |_| \__ \ (_| (_| | || (_) | |_ | |\  | |____   | |   
|______\__,_/___|_|  \__,_|___/\___\__,_/___\___/|_(_)|_| \_|______|  |_|");
}

WillDisappearOnExit

ConsoleTraits.WillDisappearOnExit boolean property indicates whether a console window will immediately disappear on program exit. Such situation can occur when a console app is directly launched from a graphical shell. In Windows, you can achieve that by creating a desktop shortcut to a console app, then running it.

A program can use the value of WillDisappearOnExit property to hold the console window in a visible state so that the user could read the output. Like so:

if (ConsoleTraits.WillDisappearOnExit)
{
    Console.WriteLine();
    Console.WriteLine("Press any key to exit . . .");
    Console.ReadKey(true);
}

MoreTextWriter for Paginated Output

MoreTextWriter class from Gapotchenko.FX.Console module automatically manages pagination when written text exceeds the height of a console area visible to the user.

The functionality is similar to more command line utility but can be used right within a program. This allows to provide an additional convenience for the end users.

Let's take a look on example:

Console output pagination

By pressing Page Down and Down Arrow keys it is possible to scroll the console output.

Below is a simple program that demonstrates the use of MoreTextWriter:

using Gapotchenko.FX.Console;
using System;

var more = new MoreTextWriter(Console.Out);

for (int i = 1; i < 100; ++i)
    more.WriteLine(i);

It produces the following output:

Console sample output

The keys, colors, and styling are fully customizable by class inheritance.

Commonly Used Types

  • Gapotchenko.FX.Console.ConsoleTraits
  • Gapotchenko.FX.Console.VirtualTerminal

Other Modules

Let's continue with a look at some other modules provided by Gapotchenko.FX:

Or look at the full list of modules.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 is compatible.  netcoreapp2.1 is compatible.  netcoreapp2.2 was computed.  netcoreapp3.0 is compatible.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net46 is compatible.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 is compatible.  net472 is compatible.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2022.2.7 432 5/1/2022
2022.2.5 400 5/1/2022
2022.1.4 418 4/6/2022
2021.2.21 437 1/21/2022
2021.2.20 408 1/17/2022
2021.1.5 346 7/6/2021
2020.2.2-beta 290 11/21/2020
2020.1.15 443 11/5/2020
2020.1.9-beta 303 7/14/2020
2020.1.8-beta 300 7/14/2020
2020.1.7-beta 312 7/14/2020