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
This project is licensed under the terms of the MIT license: LICENSE.md
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
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:
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:
Print directives (markup):
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)");
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:
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:
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:
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
AnsiVtConsole.NetCore
This project is licensed under the terms of the MIT license: LICENSE.md
