GitHub - Athari/CsConsoleFormat: .NET C# library for advanced formatting of console output [Apache] (original) (raw)

PM> Install-Package Alba.CsConsoleFormat

GitHub license GitHub license GitHub license Badges
AppVeyor build master AppVeyor tests master
GitHub release version GitHub release date GitHub commits since release GitHub open issues GitHub closed issues GitHub pull requests
NuGet release version NuGet downloads MyGet pre-release version MyGet downloads
FOSSA license scan CII best practices Libraries.io Dependencies kandi X-Ray

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:

Hello
world!

or like this:

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

or even like this:

Colors.WriteLine("Hello".Red(), "\n", "world!".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 the usual Order, OrderItem and Customer classes. Let's create a document which prints the order. There're two major syntaxes, you can use either.

XAML (like WPF):


<Grid Color="Gray">
    <Grid.Columns>
        <Column Width="Auto"/>
        <Column Width="*"/>
        <Column Width="Auto"/>
    </Grid.Columns>
    <Cell Stroke="Single Double" Color="White">Id</Cell>
    <Cell Stroke="Single Double" Color="White">Name</Cell>
    <Cell Stroke="Single Double" 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>

// 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.Double, LineWidth.Single);

var doc = new Document( new Span("Order #") { Color = Yellow }, Order.Id, "\n", new Span("Customer: ") { Color = Yellow }, Order.Customer.Name, new Grid { Color = Gray, Columns = { GridLength.Auto, GridLength.Star(1), GridLength.Auto }, Children = { new Cell("Id") { Stroke = headerThickness }, new Cell("Name") { Stroke = headerThickness }, new Cell("Count") { Stroke = headerThickness }, Order.OrderItems.Select(item => new[] { new Cell(item.Id), new Cell(item.Name), new Cell(item.Count) { Align = Align.Right }, }) } } );

ConsoleRenderer.RenderDocument(doc);

C# (like npm/colors):

using Alba.CsConsoleFormat.Fluent;

Colors.WriteLine( "Order #".Yellow(), Order.Id, "\n", "Customer: ".Yellow(), Order.Customer.Name, // the rest is the same );

Features

Getting started

  1. Install NuGet package Alba.CsConsoleFormat using Package Manager:
 PM> Install-Package Alba.CsConsoleFormat

or .NET CLI: 

 > dotnet add package Alba.CsConsoleFormat
  1. Add using Alba.CsConsoleFormat; to your .cs file.
  2. If you're going to use ASCII graphics on Windows, set Console.OutputEncoding = Encoding.UTF8;.
  3. 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.
  4. If you want to use pure C#:
    1. Build a document in code starting with Document element as a root.
  5. Call ConsoleRenderer.RenderDocument on the generated document.

Choosing syntax

XAML (like WPF) forces clear separation of views and models which is a good thing. However, it isn't strongly typed, so it's easy to get runtime errors if not careful. Syntax-wise it's a combination of XML verbosity (<Grid><Grid.Columns><Column/></Grid.Columns></Grid>) and conciseness of short enums (Color="White") and converters (Stroke="Single Double").

XAML library in Mono is currently very buggy. If you want to build a cross-platform application, using XAML may be problematic. However, if you need to support only Windows and are experienced in WPF, XAML should feel natural.

XAML is only partially supported by Visual Studio + ReSharper: syntax highlighting and code completion work, but library-specific markup extensions are't understood by code completion, so incorrect errors may be displayed.

C# (like LINQ to XML) allows performing all sorts of transformations with objects right in the code, thanks to LINQ and collapsing of enumerables when adding children elements. When using C# 6, which supports using static, accessing some of enumerations can be shortened. The only place with loose typing is adding of children using collection initializer of Element.Children (or constructor of Element).

Building documents in code is fully supported by IDE, but code completion may cause lags if documents are built with huge single statements.

Framework Compatibility

The library contains the following packages:

The library supports the following targets:

Notes:

  1. Alba.CsConsoleFormat can be ported to .NET Framework 3.5 if someone actually needs it. It's just not worth the hassle otherwise as it requires changes to Portable.Xaml library.
  2. Alba.CsConsoleFormat-NoXaml can be supported on .NET Standard 1.0, Windows Phone 8.0 and other platforms, but they don't support console. WPF control belongs to the "just for fun" genre, but if somebody actually needs something like this on other platforms, it can be ported.

License

Copyright © 2014–2018 Alexander "Athari" Prokhorov

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Some parts of the library are based on ConsoleFramework © Igor Kostomin under MIT license.

TODO