AnsiVtConsole.NetCore 1.0.26

dotnet add package AnsiVtConsole.NetCore --version 1.0.26                
NuGet\Install-Package AnsiVtConsole.NetCore -Version 1.0.26                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="AnsiVtConsole.NetCore" Version="1.0.26" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add AnsiVtConsole.NetCore --version 1.0.26                
#r "nuget: AnsiVtConsole.NetCore, 1.0.26"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install AnsiVtConsole.NetCore as a Cake Addin
#addin nuget:?package=AnsiVtConsole.NetCore&version=1.0.26

// Install AnsiVtConsole.NetCore as a Cake Tool
#tool nuget:?package=AnsiVtConsole.NetCore&version=1.0.26                

AnsiVtConsole.NetCore AnsiVtConsole.NetCore


AnsiVtConsole.NetCore library provides ANSI VT support (cursor,colors,screen size) for multi-plateform (windows, linux, osx, arm) console applications using C# and .NET Core 6

licence mit This project is licensed under the terms of the MIT license: LICENSE.md
last commit version


title

Features

The library provides functionalities needed to build console applications running in a terminal (WSL/WSL2, cmd.exe, ConEmu, bash, ...) with text interface. That includes:

  • a text printer engine that supports print directives (markup) allowing to manage console functionalities from text itself, as html would do but with a simplest grammar (that can be configured). That makes possible colored outputs, cursor control, text scrolling and also dynamic C# execution (scripting), based on System.Console and ANSI VT100 / VT52 (VT100 type Fp or 3Fp, Fs, CSI, SGR)

  • A ANSI Parser that can identify/remove escape sequences in a text

  • widgets : visual elements with live update, animations, thread safe, combinables together

  • The console output can be controlled by:

    • tokens in a string (print directives)
    • as string shortcuts (dynamic ansi vt strings) powered by SkiaSharp
    • throught API methods

Index

Usage

download the nuget from command line or add it from Visual Studio

@rem version 1.0.21 or any new one
dotnet add package AnsiVtConsole.NetCore --version 1.0.21

Note

When installing the package, the following files are copied into your project:

  • LICENSE.md
  • README.md
  • Component/Parser/ANSI/ansi-seq-patterns.txt
  • assets/example1.png
  • assets/example2.png
  • assets/example3.png
  • assets/example4.png
  • assets/example5.png
  • assets/example6.png
  • assets/output.png
  • assets/ascii-icon.png

you can delete these files EXCEPT ansi-seq-patterns.txt (ANSI grammar) that is required for the ANSI parser to work

these files are set as Content and are copied to output folder on build

// get the ansi vt console
var console = new AnsiVtConsole.NetCore.AnsiVTConsole();

1. using the markup :

console.Write("(br,f=yellow,b=red)yellow text on red background(br)(f=cyan)current time is: (exec=System.DateTime.Now,br)");

2. using the string shortcuts :

using static AnsiVtConsole.NetCore.Component.EchoDirective;

System.Console.Out.Writeline($"{Br}{Yellow}{BRed}yellow text on red background{Br}{Cyan}current time is: {System.DateTime.Now}{Br}");

3. using the ANSI sequences:

using static AnsiVtConsole.NetCore.Component.Console.ANSI;

System.Console.Out.Writeline($"{CRLF}{SGRF("Yellow")}{SGRB("Red")}yellow text on red background{CRLF}{SGRF("Cyan")}current time is: {System.DateTime.Now}{CRLF}");

all outputs:

output

4. using the widgets

/* type writer example
this adds a 'type writer' widget at current cursor location, 
maintains it in place and produces an animation of the text until
the end of the animation
*/
using AnsiVtConsole.NetCore.Component.Widgets.Texts.TypeWriting;

TypeWriter(text)
    .Add(console)   // add to a console and render the widget
    .Wait();        // animated update until end of animation

example output:

widget output

text can contains echo directives that changes the echo behavior. the echo directive syntax is formed according to this pattern: (printDirective) or (printDirective=printDirectiveValue)

  • multiple echo directives can be separated by a , that can be grouped in a single text in parentheses: (echoDirective1,echoDirective2=..,echoDirective3)
  • an echo directive value can be written inside a 'code' text block, depending on each echo directive, with the syntax: [[...]]
  • symbols of this grammar can be configured throught the class: AnsiVtConsole.NetCore.Component.Settings
  • alternatively to the print directives you can use the strings shortcuts from the class: AnsiVtConsole.NetCore.Component.EchoDirective

Available echo directives are defined in the class ``

1. Colorization with SGR (Select Graphic Rendition)

f=ConsoleColor      : set foreground color
f8=Int32            : set foreground 8bit color index, where 0 <= index <= 255
f24=Int32:Int32:Int32 : set foreground 24bit color red:green:blue, where 0 <= red,green,blue <= 255
f=ConsoleColor      : set foreground color
b=ConsoleColor      : set background color
b8=Int32            : set background 8bit color index, where 0 <= index <= 255
b24=Int32:Int32:Int32 : set background 24bit color red:green:blue, where 0 <= red,green,blue <= 255
df=ConsoleColor     : set default foreground
db=ConsoleColor     : set default background
bkf                 : backup foreground color
bkb                 : backup background color
rsf                 : restore foreground color
rsb                 : restore background color
rdc                 : restore default colors```

ConsoleColor := darkblue|darkgreen|darkcyan|darkred|darkmagenta|darkyellow|gray|darkgray|blue|green|cyan|red|magenta|yellow|white (not case sensitive)

2. Text decoration (vt100) with SGR (Select Graphic Rendition)

uon                 : underline on
invon               : inverted colors on
tdoff               : text decoration off and reset default colors
lion                : ligtht colors
bon                 : bold on
blon                : blink on

3. CSI (Control Sequence Introducer)

cls                 : clear screen
br                  : jump begin of next line (line break)
bkcr                : backup cursor position
rscr                : restore cursor position
crx=Int32           : set cursor x (0<=x<=WindowWidth)
cry=Int32           : set cursor y (0<=y<=WindowHeight)
crh                 : hide cursor
crs                 : show cursor
cleft               : move cursor left
cright              : move cursor right
cup                 : move cursor up
cdown               : move cursor down
cnleft=Int32        : move cursor n characters left
cnright=Int32       : move cursor n characters right
cnup=Int32          : move cursor n lines up
cndown=Int32        : move cursor n lines down
cl                  : clear line
clleft              : clear line from cursor left
clright             : clear line from cursor right
fillright           : fill line from cursor right
chome               : move cursor to upper left corner
tab                 : add a tab

4. Script engine

exec=CodeBlock|[[CodeBlock]] : executes and echo result of a C# code block
using static AnsiVtConsole.NetCore.Component.Parser.ANSI;
using cons=AnsiVtConsole.NetCore;
// get the ansi vt console
var console = new cons.AnsiVTConsole();

console.Out.WriteLine("current date is: (exec=System.DateTime.Now.Date)");

5. Application control

info                : output infos about the console
exit                : exit the current process

6. ANSI Sequences

ANSI sequences are defined in AnsiVtConsole.NetCore.Component.Console and can be used directly to build ANSI strings

using static AnsiVtConsole.NetCore.Component.Parser.ANSI;
using cons=AnsiVtConsole.NetCore;
// get the ansi vt console
var console = new cons.AnsiVTConsole();

var str = $"{SGR_Underline}{SGR_CrossedOut}my text{SGR_SetBackgroundColor24bits(15,152,123)}in color";
System.Console.WriteLine(str);

// is equivalent to:

cons.Out.WriteLine("(SGR_Underline,SGR_SlowBlink)my text(SGRB24=15:152:123)in color");

// or to:

cons.Out.WriteLine("(uon,blon)my text(f24=15:152:123)in color");

7. Unicode characters

Unicode characters are defined in the class AnsiVtConsole.NetCore.Component.Console.


using static AnsiVtConsole.NetCore.Component.Console.Unicode;
using cons=AnsiVtConsole.NetCore;
// get the ansi vt console
var console = new cons.AnsiVTConsole();

console.Out.WriteLine($"it's the (bkf,f=red){Demi}(rsf) or the (bkf,f=yellow){Quar}(rsf) of it");

console.Out.WriteLine("(f=cyan,EdgeTopLeft,BarHorizontal,EdgeTopRight)");
console.Out.WriteLine("(f=cyan,BarVertical,f=blue,Box,f=cyan,BarVertical)");
console.Out.WriteLine("(f=cyan,EdgeBottomLeft,BarHorizontal,EdgeBottomRight)");

example6

Command line interface tool for your shells

The project AnsiVtConsole.NetCore.CommandLine build a command line tool that calls the AnsiVtConsole WriteLine method. With that you can add to you shell scripts the outputs provided by AnsiVtConsole:

out.exe "(br,f=yellow,b=red)yellow text on red background(br)(f=cyan)current time is: (exec=System.DateTime.Now,br)"

outputs:

output

out.exe "(br,f=yellow,b=red)yellow text on red background(br)(f=cyan)current time is: (exec=System.DateTime.Now,br)" --raw

outputs:

\e[4m\e[0m\e[0K\r\n\e[4m\e[0m\e[37m\e[93m\e[101myellow text on red background\e[4m\e[0m\e[0K\r\n\e[4m\e[0m\e[37m\e[96mcurrent time is: 13/06/2020 06:17:15\e[4m\e[0m\e[0K\r\n\e[4m\e[0m\e[37m

this tool accepts these arguments:

out.exe <text> [--raw [--esc-only] [--hexa] ] 
  • if --err outputs to standard error stream instead of standard output stream
  • if --raw, parse ANSI and non printable characters to show them by their names or representations
  • if --raw these options are avalaibles :
    • --esc-only : disable only knowns non printable characters (from ASCII)
    • --hexa : use the hexa unix format for non printable characters

Note

the command line tool is built upon the library CommandLine.NetCore. For more information for this, please refers to:

Examples

project AnsiConsole.NetCore.Examples.Widgets

this project once compiled provides a live demo in the console of widgets implemented in the current version of the library. To try these examples, compile and run the project AnsiVtConsole.NetCore.Examples.Widgets:

title

example of an Image widget. This widget is delivered in the package: AnsiVtConsole.NetCore.Imaging

example7

project AnsiConsole.NetCore.Examples.ANSI

Colorization

To try these examples, compile and run the project AnsiVtConsole.NetCore.Examples.ANSI:

example1 example2

AnsiVtConsole markup and Ansi/Vt parsing

example5

Versions history

1.0.21,1.0.22,1.0.23,1.0.24,1.0.25,1.0.26 - 2-16-2024

  • fix nuget content files

1.0.20 - 1-23-2023

  • animated widgets
  • properties animator
  • widgets: text,type writer,gradient,gradient bar,text timer
  • widget image in a separated project AnsiVtConsole.NetCore.Imaging using SkiaSharp
  • examples projects
  • fluent methods for ContextTextWriterWrapper
  • doc update

1.0.19 - 1-17-2023

  • add widgets feature + RaimbowText widget
  • add example
  • doc update

1.0.18 - 1-1-2023

  • add symbols and sources in package
  • new editorconfig and code clean up
  • command out for a shell available in AnsiVtConsole.NetCore.CommandLine.Out that compiles to out.exe
  • doc update

1.0.17 - 10-1-2023

  • add setting that make it possible to disable ansi/vt in console ouputs: AnsiVtConsole.NetCore.Component.Settings : IsMarkupDisabled,IsRawOutputEnabled,ReplaceNonPrintableCharactersByTheirName,RemoveANSISequences
  • add methods to get output text in various formats (without ansi,with unparsed markup,in shell escaped characters) : GetText,GetRawText,ANSIParser.GetText
  • add grammar file for ANSI parser
  • enable buffering mode for any print directive
  • update doc

1.0.16 - 5-1-2022

  • fix nupkg. add deployment of documentation files
  • update doc

1.0.14,1.0.15 - 12-17-2022

  • fix LogError,LogWarning

1.0.13 - 12-17-2022

  • fix refactoring Write,WriteLine
  • add default empty string to log methods

1.0.12 - 12-17-2022

  • rename Writeln methods by WriteLine
  • suppress Log,Logln & logger refactoring
  • add code documentation

AnsiVtConsole.NetCore.Imaging

1.0.0 - 21-1-2023


Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on AnsiVtConsole.NetCore:

Package Downloads
CommandLine.NetCore

Provides support to handle command line arguments (parse, validate, command pattern) for .Net Core console applications with ANSI VT support (cursor,colors,screen size) for multi-plateform (windows, linux, osx, arm) console applications using C# and .NET Core 6 or higher

AnsiVtConsole.NetCore.Imaging

ANSI VT console library for .Net Core system console Imaging component

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.26 714 2/15/2024
1.0.24 262 2/15/2024
1.0.20 4,965 1/23/2023
1.0.19 935 1/18/2023
1.0.18 919 1/14/2023
1.0.17 1,142 1/10/2023
1.0.16 966 1/5/2023
1.0.15 1,166 12/17/2022
1.0.14 815 12/17/2022
1.0.13 806 12/17/2022
1.0.12 795 12/17/2022
1.0.11 774 12/16/2022
1.0.9 766 12/14/2022

`1.0.21,1.0.22,1.0.23,1.0.24,1.0.25,1.0.26` - 2-16-2024
- fix nuget content files

`1.0.20` - 1-23-2023
- animated widgets
- properties animator
- widgets: text,type writer,gradient,gradient bar,text timer
- widget image in a separated project AnsiVtConsole.NetCore.Imaging using SkiaSharp
- examples projects
- fluent methods for ContextTextWriterWrapper
- doc update

`1.0.19` - 1-17-2023
- add **widgets** feature + RaimbowText widget
- add example
- doc update

`1.0.18` - 1-1-2023
- add symbols and sources in package
- new editorconfig and code clean up
- command `out` for a shell available in `AnsiVtConsole.NetCore.CommandLine.Out` that compiles to `out.exe`
- doc update

`1.0.17` - 10-1-2023
- add setting that make it possible to disable ansi/vt in console ouputs: `AnsiVtConsole.NetCore.Component.Settings` : `IsMarkupDisabled`,`IsRawOutputEnabled`,`ReplaceNonPrintableCharactersByTheirName`,`RemoveANSISequences`
- add methods to get output text in various formats (without ansi,with unparsed markup,in shell escaped characters) : `GetText`,`GetRawText`,`ANSIParser.GetText`
- add grammar file for ANSI parser
- enable buffering mode for any print directive
- update doc

`1.0.16` - 5-1-2022
- fix nupkg. add deployment of documentation files
- update doc

`1.0.14,1.0.15` - 12-17-2022
- fix LogError,LogWarning

`1.0.13` - 12-17-2022
- fix refactoring Write,WriteLine
- add default empty string to log methods

`1.0.12` - 12-17-2022
- rename Writeln methods by WriteLine
- suppress Log,Logln & logger refactoring
- add code documentation