.NET C# library for advanced formatting of console output [Apache]
PM> Install-Package Alba.CsConsoleFormat
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(
new Span("Hello") { Color = ConsoleColor.Red },
"\n",
new Span("world!") { Color = ConsoleColor.Yellow }
);
or even like this:
Colors.WriteLine("Hello".Red(), "\n", "world!".Yellow());
.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):
<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 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>
</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.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
);
Install NuGet package Alba.CsConsoleFormat using Package Manager:
PM> Install-Package Alba.CsConsoleFormat
or .NET CLI:
> dotnet add package Alba.CsConsoleFormat
Add using Alba.CsConsoleFormat;
to your .cs file.
If you're going to use ASCII graphics on Windows, set Console.OutputEncoding = Encoding.UTF8;
.
If you want to use XAML:
ConsoleRenderer.ReadDocumentFromResource
.If you want to use pure C#:
Document
element as a root.Call ConsoleRenderer.RenderDocument
on the generated document.
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.
The library contains the following packages:
The library supports the following targets:
Notes:
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.
ConsoleFramework — fully-featured cross-platform console user interface framework. Using ConsoleFramework, you can create interactive user interface with mouse input, but its formatting capabilities are limited.
CsConsoleFormat includes more formatting features: inline text with support for Unicode, more layouts, more everything, so if you only need to output text, CsConsoleFormat is more appropriate. However, if you want an interactive user interface with windows, menus and buttons, ConsoleFramework is the only library out there which supports it.
Colorful.Console — library for coloring text in console and ASCII-art fonts. Supports RGB colors on Windows, falls back to 16 colors on other platforms.
Colorful.Console offers more coloring features: RGB colors, text highlighting based on regular expressions, gradients. However, it falls flat if anything beyond coloring is required as its output is based on calling Console.WriteLine variations, so it suffers from the same basic problems as the standard System.Console. FIGlet fonts are supported by CsConsoleFormat through Colorful.Console, but there's no integration beyond that.
ConsoleTables — simple library for printing tables. (There're several alternatives, but this one is the most popular.)
Almost all features of ConsoleTables are trivial to implement with CsConsoleFormat. ConsoleTables is limited to single-line cells and a few fixed formatting styles.
TODO