Alba.CsConsoleFormat 0.9.1

CsConsoleFormat: advanced formatting of console output for .NET

• GitHub repository

CsConsoleFormat is a library for formatting text in console based on documents resembling a mix of WPF and HTML: tables, lists, paragraphs, colors, word wrapping, lines etc. Like this:

<Document>
    <Span Color="Red">Hello</Span>
    <Br/>
    <Span Color="Yellow">world!</Span>
</Document>

or like this:

new Document()
    .AddChildren(
        new Span("Hello") { Color = ConsoleColor.Red },
        "\n",
        new Span("world!") { Color = ConsoleColor.Yellow }
    );

Why?

.NET Framework includes only very basic console formatting capabilities. If you need to output a few strings, it's fine. If you want to output a table, you have to calculate column widths manually, often hardcode them. If you want to color output, you have to intersperse writing strings with setting and restoring colors. If you want to wrap words properly or combine all of the above...

The code quickly becomes an unreadable mess. It's just not fun! In GUI, we have MV*, bindings and all sorts of cool stuff. Writing console applications feels like returning to the Stone Age.

CsConsoleFormat to the rescue!

Imagine you have usual Order, OrderItem and Customer classes. Let's create a document which prints the order. There're two syntaxes, you can use either.

XAML (like WPF):

<Document xmlns="urn:alba:cs-console-format"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Span Background="Yellow" Text="Order #"/>
    <Span Text="{Get OrderId}"/>
    <Br/>
    <Span Background="Yellow" Text="Customer: "/>
    <Span Text="{Get Customer.Name}"/>

    <Grid Color="Gray">
        <Grid.Columns>
            <Column Width="Auto"/>
            <Column Width="*"/>
            <Column Width="Auto"/>
        </Grid.Columns>
        <Cell Stroke="Single Wide" Color="White">Id</Cell>
        <Cell Stroke="Single Wide" Color="White">Name</Cell>
        <Cell Stroke="Single Wide" Color="White">Count</Cell>
        <Repeater Items="{Get OrderItems}">
            <Cell>
                <Span Text="{Get Id}"/>
            </Cell>
            <Cell>
                <Span Text="{Get Name}"/>
            </Cell>
            <Cell Align="Right">
                <Span Text="{Get Count}"/>
            </Cell>
        </Repeater>
    </Grid>
</Document>

// Assuming Order.xaml is stored as an Embedded Resource in the Views folder.
Document doc = ConsoleRenderer.ReadDocumentFromResource(GetType(), "Views.Order.xaml", Order);
ConsoleRenderer.RenderDocument(doc);

C# (like LINQ to XML):

using static System.ConsoleColor;

var headerThickness = new LineThickness(LineWidth.Single, LineWidth.Wide);

var doc = new Document()
    .AddChildren(
        new Span("Order #") { Color = Yellow },
        Order.Id,
        "\n",
        new Span("Customer: ") { Color = Yellow },
        Order.Customer.Name,

        new Grid { Color = Gray }
            .AddColumns(
                new Column { Width = GridLength.Auto },
                new Column { Width = GridLength.Star(1) },
                new Column { Width = GridLength.Auto }
            )
            .AddChildren(
                new Cell { Stroke = headerThickness }
                    .AddChildren("Id"),
                new Cell { Stroke = headerThickness }
                    .AddChildren("Name"),
                new Cell { Stroke = headerThickness }
                    .AddChildren("Count"),
                Order.OrderItems.Select(item => new[] {
                    new Cell()
                        .AddChildren(item.Id),
                    new Cell()
                        .AddChildren(item.Name),
                    new Cell { Align = HorizontalAlignment.Right }
                        .AddChildren(item.Count),
                })
            )
    );

ConsoleRenderer.RenderDocument(doc);

Features

• HTML-like elements: paragraphs, spans, tables, lists, borders, separators.
• Layouts: grid, stacking, docking, wrapping, absolute.
• Text formatting: foreground and background colors, character wrapping, word wrapping.
• Unicode formatting: hyphens, soft hyphens, no-break hyphens, spaces, no-break spaces, zero-width spaces.
• Multiple syntaxes (see examples above):
  • Like WPF: XAML with one-time bindings, resources, converters, attached properties, loading documents from assembly resources.
  • Like LINQ to XML: C# with object initializers, setting attached properties via extension methods or indexers, adding children elements by collapsing enumerables and converting objects and strings to elements.
• Drawing: geometric primitives (lines, rectangles) using box-drawing characters, color transformations (dark, light), text, images.
• Internationalization: cultures are respected on every level and can be customized per-element.
• Export to many formats: ANSI text, unformatted text, HTML; RTF, XPF, WPF FixedDocument, WPF FlowDocument.
• JetBrains ReSharper annotations: CanBeNull, NotNull, ValueProvider, Pure etc.
• WPF document control, document converter.

Getting started

1. Install NuGet package Alba.CsConsoleFormat using Package Manager:

    PM> Install-Package Alba.CsConsoleFormat
   

   or .NET CLI:

    > dotnet add package Alba.CsConsoleFormat
   

2. Add using Alba.CsConsoleFormat; to your .cs file.

3. If you're going to use ASCII graphics on Windows, set Console.OutputEncoding = Encoding.UTF8;.

4. If you want to use XAML:

   1. Add XAML file to your project. Set its build action to "Embedded Resource".
   2. Load XAML using ConsoleRenderer.ReadDocumentFromResource.

5. If you want to use pure C#:

   1. Build a document in code starting with Document element as a root.

6. Call ConsoleRenderer.RenderDocument on the generated document.

Links

TODO