spectre.console/README.md

Spectre.Console

A .NET Standard 2.0 library that makes it easier to create beautiful console applications.
It is heavily inspired by the excellent Rich library for Python.

Table of Contents

1. Features
2. Example
3. Installing
4. Usage
   4.1. Using the static API
   4.2. Creating a console
5. Running examples

Features

• Written with unit testing in mind.
• Supports tables, grids, panels, and a rich inspired markup language.
• Supports the most common SRG parameters when it comes to text styling such as bold, dim, italic, underline, strikethrough, and blinking text.
• Supports 3/4/8/24-bit colors in the terminal.
  The library will detect the capabilities of the current terminal and downgrade colors as needed.

Example

Installing

The fastest way of getting started using Spectre.Console is to install the NuGet package.

dotnet add package Spectre.Console

Usage

The Spectre.Console API is stateful and is not thread-safe. If you need to write to the console from different threads, make sure that you take appropriate precautions, just like when you use the regular System.Console API.

If the current terminal does not support ANSI escape sequences, Spectre.Console will fallback to using the System.Console API.

NOTE: This library is currently under development and APIs might change or get removed at any point up until a 1.0 release.

Using the static API

The static API is perfect when you just want to output text like you usually do with the System.Console API, but prettier.

AnsiConsole.Foreground = Color.CornflowerBlue;
AnsiConsole.Decoration = Decoration.Underline | Decoration.Bold;
AnsiConsole.WriteLine("Hello World!");

AnsiConsole.Reset();
AnsiConsole.MarkupLine("[bold yellow on red]{0}[/] [underline]world[/]!", "Goodbye");

If you want to get a reference to the default IAnsiConsole, you can access it via AnsiConsole.Console.

Creating a console

Sometimes it's useful to explicitly create a console with specific capabilities, such as during unit testing when you want control over the environment your code runs in.

It's recommended to not use AnsiConsole in code that run as part of a unit test.

IAnsiConsole console = AnsiConsole.Create(
    new AnsiConsoleSettings()
    {
        Ansi = AnsiSupport.Yes,
        ColorSystem = ColorSystemSupport.TrueColor,
        Out = new StringWriter(),
    });

NOTE: Even if you can specify a specific color system to use when manually creating a console, remember that the user's terminal might not be able to use it, so unless you're creating an IAnsiConsole for testing, always use ColorSystemSupport.Detect and AnsiSupport.Detect.

Running examples

To see Spectre.Console in action, install the dotnet-example global tool.

> dotnet tool install -g dotnet-example

Now you can list available examples in this repository:

> dotnet example

╭────────────┬───────────────────────────────────────┬──────────────────────────────────────────────────────╮
│ Name       │ Path                                  │ Description                                          │
├────────────┼───────────────────────────────────────┼──────────────────────────────────────────────────────┤
│ Borders    │ examples/Borders/Borders.csproj       │ Demonstrates the different kind of borders.          │
│ Calendars  │ examples/Calendars/Calendars.csproj   │ Demonstrates how to render calendars.                │
│ Colors     │ examples/Colors/Colors.csproj         │ Demonstrates how to use colors in the console.       │
│ Columns    │ examples/Columns/Columns.csproj       │ Demonstrates how to render data into columns.        │
│ Emojis     │ examples/Emojis/Emojis.csproj         │ Demonstrates how to render emojis.                   │
│ Exceptions │ examples/Exceptions/Exceptions.csproj │ Demonstrates how to render formatted exceptions.     │
│ Grids      │ examples/Grids/Grids.csproj           │ Demonstrates how to render grids in a console.       │
│ Info       │ examples/Info/Info.csproj             │ Displays the capabilities of the current console.    │
│ Links      │ examples/Links/Links.csproj           │ Demonstrates how to render links in a console.       │
│ Panels     │ examples/Panels/Panels.csproj         │ Demonstrates how to render items in panels.          │
│ Rules      │ examples/Rules/Rules.csproj           │ Demonstrates how to render horizontal rules (lines). │
│ Tables     │ examples/Tables/Tables.csproj         │ Demonstrates how to render tables in a console.      │
╰────────────┴───────────────────────────────────────┴──────────────────────────────────────────────────────╯

And to run an example:

> dotnet example tables
┌──────────┬──────────┬────────┐
│ Foo      │ Bar      │ Baz    │
├──────────┼──────────┼────────┤
│ Hello    │ World!   │        │
│ Bonjour  │ le       │ monde! │
│ Hej      │ Världen! │        │
└──────────┴──────────┴────────┘