Skip to content

Latest commit

 

History

History
214 lines (135 loc) · 7.93 KB

README.md

File metadata and controls

214 lines (135 loc) · 7.93 KB
Raw
ANSI Console

ANSI Console

Lightweight and flexible text formatter
for creating beautiful console applications.

Nuget Nuget GitHub GitHub code size in bytes



About

ANSI Console aims to be as developer friendly and easy to use as possible. The reason this library was created is because many of the already existing libraries doesn't provide a good user interface. The main purpose of this library is to fix this, console formatting should be accessible and fun!

Install

> dotnet add package ANSI.Console

Or download ANSI.Console directly from NuGet.

Features

  • Color formatting using: System.ConsoleColor, System.Drawing.Color, RGB, HEX, Named/known colors (list) and True color (24-bit format with over 16.7 million colors, Wikipedia)
  • Styles: Bold, Italic, Underlined, Overlined, Strike-through, Inverted, Faint, Opacity, Blink, Uppercase and Lowercase.
  • Hyperlinks
  • Custom inline formatting method FormatANSI.
  • Chainable formatting methods.
  • ANSI initialization for the system console (If not enabled already).
  • Builds on-top of the default Console using string extension methods.
  • Mapping methods using generators
  • Gradients with unlimited colors

Learn more about ANSI escape sequences here.

Initialization

One should always initialize the ANSI console mode before writing anything to the console. The line below will try to initialize returning true if successful. If initialization failed, disable all ANSI codes from being printed without needing to change any of your formatting logic. Colors and formatting is automatically disabled for systems with the NO_COLOR environment variable enabled, read more here.

if (!ANSIInitializer.Init(false)) ANSIInitializer.Enabled = false;

Colors and styles

Colors

  • Use regular ConsoleColor.
"My text".Color(ConsoleColor.Red)
  • Or even better, any Color.
"My text".Color(Color.IndianRed)
  • Too long still? Use just the color name.
"My text".Color("IndianRed")
  • Want more control? Use hexadecimal color values.
"My text".Color("#775500")
  • Or even RGB color values.
"My text".Color(256, 127, 0)

Styles

You can chain all formatting styles in any order.

"My text".Bold().Italic().Color("IndianRed").Underlined().StrikeThrough().Blink();

Opacity

Add opacity easily using .Opacity(percent). percent must be between 0 and 100. The code below could be rewritten and improved using the map method below.

Console.WriteLine($"{"O".Opacity(10)}{"p".Opacity(20)}{"a".Opacity(30)}{"c".Opacity(50)}{"i".Opacity(60)}{"t".Opacity(80)}{"y".Opacity(90)}");

Links

Use .Link() if the text is also a valid URL. This only works on strings, and not if you have used any other formatting method before it.

"https://www.nuget.org/packages/ANSI.Console".Link().Bold();

If you fancy using a custom title, use .Link(url). This can be used in any order in the chained formatting list.

"ANSI.Console".Bold().Link("https://www.nuget.org/packages/ANSI.Console");

Map

Use the MapANSI method to generate custom patterns, highlighting or anything else you can think of.

Console.WriteLine("Every second letter is yellow".MapANSI((c, i) => i % 2 == 0 ? c.Color(ConsoleColor.Yellow) : c.ToANSI()));

Gradients

Add text gradients interpolating between any amount of colors. The first argument is the background color.

Console.WriteLine("This is a gradient".Gradient(ANSIString.FromConsoleColor(Console.BackgroundColor), Color.Yellow, Color.Red, Color.Blue, Color.Cyan));

Or background gradients. The first argument is the foreground color. (Sadly the two cannot be combined yet. But maybe in a future release if there is interest)

Console.WriteLine("This is a gradient".GradientBackground(Color.Black, Color.Yellow, Color.Red, Color.Blue, Color.Cyan));

Inline formatting using FormatANSI

Format text directly in line, applying the corresponding ANSI format in the formatting array to the matching `(color|(background|))text´ in the text. Use `color|text´ to add foreground color, and `|background|text´ to only add background color.

Example: Only color

Console.WriteLine($"This `Green|text´ has `Black|Gray|inline {"formatted".Italic().NoClear()}´ `Yellow|c´`Orange|o´`Red|l´`Purple|o´`Blue|r´`Aqua|s´".FormatANSI());

Example: Multi formatted

Console.WriteLine("`Red|This´ is `|Green|a´ `Blue|formatted´ `string´".FormatANSI(ANSIFormatting.Bold | ANSIFormatting.Overlined, ANSIFormatting.None, ANSIFormatting.Blink, ANSIFormatting.Inverted));

formatted result

Inline colors using FormatColor

Unless you don't want any other formatting that colors, use this method instead. You don't need to specify the color in the text itself, but as arguments to the FormatColor method.

This is perfect if you want to quickly spice-up your console applications usage/about/help message or manual page.

Console.WriteLine($"This `text´ has `inline {"formatted".Italic().NoClear()}´ `c´`o´`l´`o´`r´`s´".FormatColor(ConsoleColor.Green, ConsoleColor.Magenta, ConsoleColor.Yellow, ConsoleColor.DarkYellow, ConsoleColor.Red, ConsoleColor.DarkMagenta, ConsoleColor.Blue, ConsoleColor.Cyan));

NO_COLOR

No formatting will be applied for systems where console color output has explicitly been requested to be turned off using the environment variable NO_COLOR. See more information about this initiative at https://no-color.org.

This can be overwritten by setting the ANSIInitializer.Enabled = true.

Resources

Blogs

Related projects