Tamar.ANSITerm 0.1.4

ANSITerm

ANSI escape codes and true color formatting for .NET's console.

Install-Package Tamar.ANSITerm -Version 0.1.4
dotnet add package Tamar.ANSITerm --version 0.1.4
<PackageReference Include="Tamar.ANSITerm" Version="0.1.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Tamar.ANSITerm --version 0.1.4
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

ANSITerm

Introduction

ANSITerm.Console re-implements the System.Console class so properties like Console.ForegroundColor would rather take values from the Color struct with 24-bit RGB colors than the basic 16 ConsoleColors, and adapt these colors to the limitations of the given terminal emulator using ANSI escape codes.

Current features

  • Automatic detection and use of:
    • ANSI escape codes.
    • 4-bit (16 colors) XTerm palette sequences<sup>[details]</sup>.
    • 8-bit (256 colors) ANSI palette sequences<sup>[details]</sup>.
    • 24-bit True Color sequences.
  • XTerm sequences for italic, bold, underlined, blink, rapid-blink,reverse color, and faint text formatting styles<sup>[inconsistent support]</sup>.
  • Automatic conversion to the nearest 4-bit or 8-bit colors when the terminal does not support 24-bit true color. The algorithm is quite fast and it calculates via the RGB values and keeps a cache dictionary.
  • Turn on/off features or ignore their terminal support through imperative commands within your code.
  • Write/WriteLine/ReadLine method overloads with foreground and background color parameters to appease the usual code bloat with imperative console formatting.

Terminal support

If support for ANSI escape codes is uncertain, then ANSITerm will virtually take no effect and skip all escape-code-depended formatting, except for colors which will be converted to the nearest 4-bit color and passed as .NET's default System.ConsoleColor.

Escape codes support is determined by the TERM environment variable. ANSITerm tries to search for known terminal types such as xterm, linux and vt100 to ensure escape code support.

8-bit color support is determined by the TERM environment variable for values that include 256color in them, such as xterm-256color.

24-bit color support is determined by COLORTERM environment variable, which is usually set to truecolor by the terminal emulator in question.

XTerm formatting support (including style formatting) is determined by escape code support alone.

Ignore terminal support

If you are certain that you managed to identify your terminal within your code however ANSITerm has failed to detect your terminal, then you may instruct ANSITerm to ignore its own terminal support and enable escape codes anyway by setting the Feature.IgnoreSupport property to true in Console.Config.

Use this with caution. If you haven't identified the terminal properly then the user may see escape characters printed all over the buffer and this will render your application unusable on certain terminals that do not support ANSI escape codes to their full extent as you may have expected.

Turn IgnoreSupport only if you're 100% certain that you've managed to detect a terminal that supports the features you need but ANSITerm fails to detect them automatically. It's also a good idea to allow the user to turn on or off this behavior via external configuration.

Color support

24-bit True Color

If the current terminal supports 24-bit colors, then ANSITerm will use SGR sequences<sup>[what is SGR?]</sup> for RGB colors<sup>[alpha emitted]</sup> without performing any conversions to the nearest 8-bit/4-bit color.

8-bit (256 colors) ANSI palette

If ANSITerm can't determine support for 24-bit colors in the current terminal, then it will resort to ANSI's standard 8-bit 256 colors palette with nearest-color conversions.

4-bit (16 colors) XTerm palette

If ANSITerm can't determine support for 8-bit colors, but escape codes are supported, then it will resort to XTerm's base 4-bit 16 colors with bright and dark variants with nearest-color conversions.

4-bit (16 colors) System.ConsoleColor

If escape codes are not supported at all, then it will resort to .NET's basic system colors by utilizing the well known ConsoleColor enum and nearest-color conversions.

Windows 10 Command Prompt

I've tested CMD's escape code support on both Visual Studio and Rider and experienced different results, thus ANSITerm won't support escape codes on the Windows CMD by default. Windows Terminal is in ANSITerm's todo list.

Examples

Import ANSITerm.Console

ANSITerm.Console's use is fairly similar to .NET's standard System.Console use. A using alias directive should be declared at each source file that makes use of ANSITerm.Console in order to prevent confusion between the standard base class and ANSITerm's class.

using Console = Tamar.ANSITerm.Console;
Text formatting

Multiple formatting ANSI sequences can be applied simultaneously over the current state, and ANSITerm will run an SGR sequence<sup>[what is SGR?]</sup> update every time the formatting is being changed by color or by style (as long as the terminal is able to support escape codes).

Consider using the method overloads for Write, WriteLine, and ReadLine that include foreground and background parameters as shown below. They don't interfere with ForegroundColor or BackgroundColor and will revert back once they done printing.

Console.WriteLine("Red text over white background.", Color.Red, Color.White);
Console.WriteLine("Normal text");
Console.ReadLine(Color.DarkTeal); // The user's input is shown in dark teal as they type, and reverts back to the previous colors when they're done.

Toggle XTerm formatting styles (such as italic/bold/underline) the same way you would set colors.

Console.Italic = true;
Console.WriteLine("Italic text");

Console.Bold = true;
Console.WriteLine("Italic & bold text");

Console.Italic = false;
Console.WriteLine("Bold text");

Console.ResetStyle();
Console.WriteLine("Normal text");

Console.ForegroundColor = Color.MediumPurple;
Console.BackgroundColor = Color.MidnightBlue;
Console.WriteLine("Light purple text over dark blue background.")
Console.ResetColor();

ANSITerm

Introduction

ANSITerm.Console re-implements the System.Console class so properties like Console.ForegroundColor would rather take values from the Color struct with 24-bit RGB colors than the basic 16 ConsoleColors, and adapt these colors to the limitations of the given terminal emulator using ANSI escape codes.

Current features

  • Automatic detection and use of:
    • ANSI escape codes.
    • 4-bit (16 colors) XTerm palette sequences<sup>[details]</sup>.
    • 8-bit (256 colors) ANSI palette sequences<sup>[details]</sup>.
    • 24-bit True Color sequences.
  • XTerm sequences for italic, bold, underlined, blink, rapid-blink,reverse color, and faint text formatting styles<sup>[inconsistent support]</sup>.
  • Automatic conversion to the nearest 4-bit or 8-bit colors when the terminal does not support 24-bit true color. The algorithm is quite fast and it calculates via the RGB values and keeps a cache dictionary.
  • Turn on/off features or ignore their terminal support through imperative commands within your code.
  • Write/WriteLine/ReadLine method overloads with foreground and background color parameters to appease the usual code bloat with imperative console formatting.

Terminal support

If support for ANSI escape codes is uncertain, then ANSITerm will virtually take no effect and skip all escape-code-depended formatting, except for colors which will be converted to the nearest 4-bit color and passed as .NET's default System.ConsoleColor.

Escape codes support is determined by the TERM environment variable. ANSITerm tries to search for known terminal types such as xterm, linux and vt100 to ensure escape code support.

8-bit color support is determined by the TERM environment variable for values that include 256color in them, such as xterm-256color.

24-bit color support is determined by COLORTERM environment variable, which is usually set to truecolor by the terminal emulator in question.

XTerm formatting support (including style formatting) is determined by escape code support alone.

Ignore terminal support

If you are certain that you managed to identify your terminal within your code however ANSITerm has failed to detect your terminal, then you may instruct ANSITerm to ignore its own terminal support and enable escape codes anyway by setting the Feature.IgnoreSupport property to true in Console.Config.

Use this with caution. If you haven't identified the terminal properly then the user may see escape characters printed all over the buffer and this will render your application unusable on certain terminals that do not support ANSI escape codes to their full extent as you may have expected.

Turn IgnoreSupport only if you're 100% certain that you've managed to detect a terminal that supports the features you need but ANSITerm fails to detect them automatically. It's also a good idea to allow the user to turn on or off this behavior via external configuration.

Color support

24-bit True Color

If the current terminal supports 24-bit colors, then ANSITerm will use SGR sequences<sup>[what is SGR?]</sup> for RGB colors<sup>[alpha emitted]</sup> without performing any conversions to the nearest 8-bit/4-bit color.

8-bit (256 colors) ANSI palette

If ANSITerm can't determine support for 24-bit colors in the current terminal, then it will resort to ANSI's standard 8-bit 256 colors palette with nearest-color conversions.

4-bit (16 colors) XTerm palette

If ANSITerm can't determine support for 8-bit colors, but escape codes are supported, then it will resort to XTerm's base 4-bit 16 colors with bright and dark variants with nearest-color conversions.

4-bit (16 colors) System.ConsoleColor

If escape codes are not supported at all, then it will resort to .NET's basic system colors by utilizing the well known ConsoleColor enum and nearest-color conversions.

Windows 10 Command Prompt

I've tested CMD's escape code support on both Visual Studio and Rider and experienced different results, thus ANSITerm won't support escape codes on the Windows CMD by default. Windows Terminal is in ANSITerm's todo list.

Examples

Import ANSITerm.Console

ANSITerm.Console's use is fairly similar to .NET's standard System.Console use. A using alias directive should be declared at each source file that makes use of ANSITerm.Console in order to prevent confusion between the standard base class and ANSITerm's class.

using Console = Tamar.ANSITerm.Console;
Text formatting

Multiple formatting ANSI sequences can be applied simultaneously over the current state, and ANSITerm will run an SGR sequence<sup>[what is SGR?]</sup> update every time the formatting is being changed by color or by style (as long as the terminal is able to support escape codes).

Consider using the method overloads for Write, WriteLine, and ReadLine that include foreground and background parameters as shown below. They don't interfere with ForegroundColor or BackgroundColor and will revert back once they done printing.

Console.WriteLine("Red text over white background.", Color.Red, Color.White);
Console.WriteLine("Normal text");
Console.ReadLine(Color.DarkTeal); // The user's input is shown in dark teal as they type, and reverts back to the previous colors when they're done.

Toggle XTerm formatting styles (such as italic/bold/underline) the same way you would set colors.

Console.Italic = true;
Console.WriteLine("Italic text");

Console.Bold = true;
Console.WriteLine("Italic & bold text");

Console.Italic = false;
Console.WriteLine("Bold text");

Console.ResetStyle();
Console.WriteLine("Normal text");

Console.ForegroundColor = Color.MediumPurple;
Console.BackgroundColor = Color.MidnightBlue;
Console.WriteLine("Light purple text over dark blue background.")
Console.ResetColor();

Release Notes

Added a new configuration API to ANSITerm.
Fixed a bug in `ResetColor` when using with escape codes turned off.
Added option to ignore terminal support and use escape codes anyway.
ForeColor and BackColor are now ForegroundColor and BackgroundColor.
Everything is fully backwards compatible, you can still use the old properties, they re-route your calls to the new properties.

  • .NETCoreApp 2.2

    • No dependencies.
  • .NETStandard 2.0

    • No dependencies.

Version History

Version Downloads Last updated
0.1.4 59 6/7/2019
0.1.3 67 4/29/2019