ansix 0.0.1-prerelease copy "ansix: ^0.0.1-prerelease" to clipboard
ansix: ^0.0.1-prerelease copied to clipboard

Published 19 months ago • verified publishernikosportolos.com• Latest: 0.3.4
[unknown platforms]
→

Metadata

AnsiX is an extended ANSI library that provides tools and extensions for Dart & Flutter projects.

More...

AnsiX #

Language Build codecov License: MIT

ansix

AnsiX is a powerful and easy-to-use library that provides tools and extensions for adding ANSI color and styling support to your Dart & Flutter applications.

You can easily create colorful and visually appealing output for your command-line interfaces, including bold, italic, underline, and strikethrough text, as well as foreground and background colors in a wide range of ANSI-compatible terminals.

Whether you're building a CLI tool, a dart server, or a Flutter application, AnsiX makes it easy to add ANSI styling to your output with minimal effort and maximum flexibility.

Table of contents #

Introduction #

ANSI escape codes, also known as ANSI color codes or ANSI escape sequences, are a set of standardized sequences of characters used in computing to control text formatting, color, and other visual aspects of terminal output.

The ANSI escape codes consist of a special sequence of characters that begins with the escape character (ESC, ASCII code 27) followed by one or more control characters. These control characters can include commands to change the color or background of text, move the cursor to a specific location on the screen, erase part of the screen, and more.

For example, the ANSI escape code "\e[31m" changes the text color to red, while "\e[42m" changes the background color to green. The code "\e[2J" clears the entire screen, and "\e[;H" moves the cursor to the top-left corner of the screen.

ANSI escape codes are widely used in command-line interfaces, terminal emulators, and other text-based applications to provide a richer and more interactive user experience.

AnsiX Features #

ANSI Support #

With AnsiX you can check whether the terminal that is attached to your application supports ANSI escape codes and automatically disable all ANSI formatting to avoid malformed messages in your console.

ANSI support detection #

AnsiX will check if ANSI escape codes are supported in the attached terminal by using the default Dart methods and taking an extra step trying to further detect ANSI support in case default dart implementation fails.

Ensure ANSI support #

For example, when running an application in a terminal that doesn't support ANSI escape codes the formatted text looks like this:

> dart run example/styles.dart

This is a sample text with [bold] style
This is a sample text with [boldUnderline] style
This is a sample text with [dim] style
This is a sample text with [inverse] style
This is a sample text with [italic] style
This is a sample text with [normal] style
This is a sample text with [strikethrough] style
This is a sample text with [underline] style

In the beginning of our application we can run AnsiX.ensureSupportsAnsi(); to ensure that ANSI formatting is supported.

By default, if there's no ANSI support it will throw an error of type AnsiNotSupported.

We can override the default behaviour by setting the setting flag to true:

AnsiX.ensureSupportsAnsi(silent: true);

This will result to displaying the text with no ANSI formatting and ensure the quality and readability of your console messages:

> dart run example/styles.dart

This is a sample text with [bold] style
This is a sample text with [boldUnderline] style
This is a sample text with [dim] style
This is a sample text with [inverse] style
This is a sample text with [italic] style
This is a sample text with [normal] style
This is a sample text with [strikethrough] style
This is a sample text with [underline] style

Force usage of ANSI escape codes #

We can override the default AnsiX behaviour in order to enable ANSI formatting even if ANSI support detection failed, by using the force flag:

AnsiX.ensureSupportsAnsi(force: true);

Use with caution, as it may lead to printing wrongly-formatted text.

Enable/Disable AnsiX #

We can enable ANSI formatting simply by running the following:

AnsiX.enable();
AnsiX.disable();

Theme #

Styles #

ANSI style is a set of formatting codes that can be used to change the appearance of text in a terminal.

These codes include things like bold, italic, underline, and strikethrough, as well as control codes for things like cursor movement and clearing the screen.

ANSI style codes are supported by most terminal emulators and are commonly used in command-line interfaces and text-based programs.

AnsiX supports the following text styles:

  • bold
  • bold underline
  • dim
  • inverse
  • italic
  • strikethrough
  • underline

text-styles

Colors #

ANSI colors are a set of standardized color codes that can be used in text-based interfaces to add color and emphasis to text.

The ANSI color codes are typically supported by terminal emulators and command-line interfaces, and can be used to change the foreground and background colors of text.

The ANSI color codes consist of a special sequence of characters that starts with the escape character (ASCII code 27), followed by the characters '[', the color code, and the letter 'm'.

The color code can be a number between 0 and 255, and is used to specify a specific color in the terminal's color palette.

Most terminals support 8 and 16 colors, as well as 256 (8-bit) colors.

ANSI Color sets

  • System colors

    The 16 ANSI colors are a set of standardized colors used by early computer terminals, and are still commonly used today in various terminal applications.

    They consist of eight basic colors and their corresponding "bright" versions.

  • Extended colors

    Extended colors are a range of additional colors beyond the standard 16-color and 256-color palettes in the ANSI color space.

    They are typically used in modern terminals that support true color or in applications that can generate 24-bit color codes.

    The extended color range allows for a more extensive and diverse color palette, enabling users to choose from millions of possible color combinations.

    Each color is represented by an RGB triplet or hexadecimal value, allowing for precise color selection.

    Overall, the extended color range offers greater flexibility and creative freedom when it comes to designing and displaying text and graphics in a terminal environment.

  • Greyscale colors

    Greyscale colors are a range of neutral colors that range from black to white, passing through shades of grey.

    They are often used to provide contrast with other colors or to create a subdued, monochromatic look.

    In the context of ANSI terminal colors, greyscale colors are represented by a series of shades ranging from black to white, with a total of 24 different shades available.

  • All colors

    Includes all 256 available terminal ANSI colors.

text-styles

Text alignment #

  • AnsiTextAlignment.left
|This is a text with [left] alignment                        |
  • AnsiTextAlignment.center
|           This is a text with [center] alignment           |
  • AnsiTextAlignment.right
|                       This is a text with [right] alignment|

Extensions #

String #

  • withStyle
 String withStyle(final AnsiStyle style)
  • styled
String styled(
  final AnsiTextStyle textStyle, [
  final AnsiColor foreground = AnsiColor.none,
  final AnsiColor background = AnsiColor.none,
])
  • withForegroundColor
String withForegroundColor(final AnsiColor color)
  • withBackgroundColor
String withBackgroundColor(final AnsiColor color)
  • colored
String colored({
  final AnsiColor foreground = AnsiColor.none,
  final AnsiColor background = AnsiColor.none,
})
  • coloredRgb
String coloredRgb({
  final AnsiColor foreground = AnsiColor.none,
  final AnsiColor background = AnsiColor.none,
})

Styles

  • bold
  • italic
  • underline
  • strikethrough

Colors

  • black
  • red
  • green
  • yellow
  • blue
  • fuchsia
  • aqua
  • white

StringBuffer #

  • writeLines

Writes empty lines in buffer:

void writeLines(final int lines)
  • writeSpaces

Writes spaces in buffer with optional background color:

void writeSpaces(
  final int length, [
  final AnsiColor backgroundColor = AnsiColor.none,
])
  • writeColored

Writes a text in buffer with foreground color:

void writeColored(
  final String text,
  final AnsiColor color,
)
  • writeStyled

Writes a styled text in buffer with optional colors:

void writeStyled(
  final String text, {
  required final AnsiTextStyle textStyle,
  final AnsiColor foregroundColor = AnsiColor.none,
  final AnsiColor backgroundColor = AnsiColor.none,
})

Widgets #

AnsiText #

AnsiText(
  'This is a demo message',
  foregroundColor: AnsiColor.white,
  backgroundColor: AnsiColor.deepSkyBlue4,
  fixedWidth: 40,
  textAlignment: AnsiTextAlignment.center,
  textStyle: const AnsiTextStyle(
    bold: true,
  ),
);

AnsiTextStyle #

AnsiTextStyle(
  bold: false,
  boldUnderline: false,
  dim: false,
  inverse: false,
  italic: false,
  strikethrough: false,
  underline: false,
)

AnsiTable #

An ANSI table is a 2D table of data that is formatted with ANSI escape sequences to display borders and optionally add colors or styles in certain cells or text.

The borders are drawn using ASCII or Unicode characters that simulate table lines and corners, and the cells can be colored or styled with different foreground and background colors to improve readability and visual appeal.

These tables are commonly used in command-line interfaces, log files, and other text-based applications to present data in a tabular format that is easy to read and analyze.

AnsiTable({
  this.border = const AnsiBorder(),
  this.data = const <AnsiTableRow>[],
})

  • AnsiTable.fromList

Returns an AnsiTable build from the input list of data.

Arguments:

  • data

    Will use the input list of data to build an AnsiTableColumn.

  • fixedWidth

    If set will use this value as default width for all table cells.

  • keepSameWidth

    If set to true will find the max cell width and use it for the whole table.

  • border

    The AnsiBorder that will be used to draw the table with.

  • defaultAlignment

    The default AnsiTextAlignment that will be used for all table cells.

factory AnsiTable.fromList(
  final List<Object?> data, {
  final int? fixedWidth,
  final AnsiBorder border = const AnsiBorder(),
  final AnsiTextAlignment defaultAlignment = AnsiTextAlignment.left,
})

  • AnsiTable.fromMap

    Returns an AnsiTable build from the input map of data.

Arguments:

  • data

    Will use the keys of the map as headers and their values as data.

  • fixedWidth

    If set will use this value as default width for all table cells.

  • keepSameWidth

    If set to true will find the max cell width and use it for the whole table.

  • border

    The AnsiBorder that will be used to draw the table with.

  • defaultAlignment

    The default AnsiTextAlignment that will be used for all table cells.

  • orientation

    The AnsiOrientation that will be used to draw the table.

factory AnsiTable.fromMap(
  final Map<String, List<Object?>> data, {
  final int? fixedWidth,
  final bool keepSameWidth = false,
  final AnsiBorder border = const AnsiBorder(),
  final AnsiTextAlignment defaultAlignment = AnsiTextAlignment.left,
  final AnsiOrientation orientation = AnsiOrientation.vertical,
})

AnsiBorder #

const AnsiBorder({
  this.type = AnsiBorderType.none,
  this.style = AnsiBorderStyle.none,
  this.color = AnsiColor.none,
})

AnsiBorderStyle

ANSI border styles are a set of characters and escape codes that can be used to draw borders and frames around text or other content in terminal-based applications.

  • AnsiBorderStyle.ascii
------------
|  AnsiX   |
------------
  • AnsiBorderStyle.bold
┏━━━━━━━━━━┓
┃  AnsiX   ┃
┗━━━━━━━━━━┛
  • AnsiBorderStyle.double
╔══════════╗
║  AnsiX   ║
╚══════════╝
  • AnsiBorderStyle.none
  AnsiX
  • AnsiBorderStyle.rounded
╭──────────╮
│  AnsiX   │
╰──────────╯
  • AnsiBorderStyle.square
┌──────────┐
│  AnsiX   │
└──────────┘

AnsiBorderType

  • AnsiBorderType.all
┌───────────────┬───────────────┬───────────────┐
│Name           │Hex            │RGB            │
├───────────────┼───────────────┼───────────────┤
│Red            │#ff0000        │(255, 0, 0)    │
├───────────────┼───────────────┼───────────────┤
│Green          │#008000        │(0, 128, 0)    │
├───────────────┼───────────────┼───────────────┤
│Blue           │#0000ff        │(0, 0, 255)    │
└───────────────┴───────────────┴───────────────┘
  • AnsiBorderType.header
┌───────────────┬───────────────┬───────────────┐
│Name           │Hex            │RGB            │
└───────────────┴───────────────┴───────────────┘
 Red             #ff0000         (255, 0, 0)     
 Green           #008000         (0, 128, 0)     
 Blue            #0000ff         (0, 0, 255)
  • AnsiBorderType.inside
Name           │Hex            │RGB            
───────────────┼───────────────┼───────────────
Red            │#ff0000        │(255, 0, 0)    
───────────────┼───────────────┼───────────────
Green          │#008000        │(0, 128, 0)    
───────────────┼───────────────┼───────────────
Blue           │#0000ff        │(0, 0, 255)
  • AnsiBorderType.insideHorizontal
Name            Hex             RGB            
───────────────────────────────────────────────
Red             #ff0000         (255, 0, 0)    
───────────────────────────────────────────────
Green           #008000         (0, 128, 0)    
───────────────────────────────────────────────
Blue            #0000ff         (0, 0, 255)
  • AnsiBorderType.insideVertical
Name           │Hex            │RGB            
Red            │#ff0000        │(255, 0, 0)    
Green          │#008000        │(0, 128, 0)    
Blue           │#0000ff        │(0, 0, 255)
  • AnsiBorderType.none
Name           Hex            RGB            
Red            #ff0000        (255, 0, 0)    
Green          #008000        (0, 128, 0)    
Blue           #0000ff        (0, 0, 255)
  • AnsiBorderType.outside
┌─────────────────────────────────────────────┐
│Name           Hex            RGB            │
│Red            #ff0000        (255, 0, 0)    │
│Green          #008000        (0, 128, 0)    │
│Blue           #0000ff        (0, 0, 255)    │
└─────────────────────────────────────────────┘
  • AnsiBorderType.outsideHorizontal
│Name           Hex            RGB            │
│Red            #ff0000        (255, 0, 0)    │
│Green          #008000        (0, 128, 0)    │
│Blue           #0000ff        (0, 0, 255)    │
  • AnsiBorderType.outsideVertical
───────────────────────────────────────────────
Name           Hex            RGB
Red            #ff0000        (255, 0, 0)
Green          #008000        (0, 128, 0)
Blue           #0000ff        (0, 0, 255)
───────────────────────────────────────────────

Examples #

import 'package:ansix/ansix.dart';

void main() {
  // Ensure that the attached terminal supports ANSI formatting
  AnsiX.ensureSupportsAnsi();

  // String extensions
  print('This is a bold text'.bold());
  print('This is a text with red foreground color'.red());

  // StringBuffer extensions
  print(StringBuffer()
    ..writeWithForegroundColor('Hello ', AnsiColor.blue)
    ..writeStyled(
      'AnsiX ',
      textStyle: const AnsiTextStyle(bold: true),
      foregroundColor: AnsiColor.aquamarine2,
    )
    ..writeWithForegroundColor('!', AnsiColor.fuchsia)
    ..writeWithForegroundColor('!', AnsiColor.red1)
    ..writeWithForegroundColor('!', AnsiColor.darkOrange3)
    ..toString());
}

You can check the example folder for more samples.

Changelog #

Check the changelog to learn what's new in AnsiX.

Contribution #

Check the contribution guide if you want to help with AnsiX.

← Metadata

16
likes
0
points
6.03k
downloads

Publisher

verified publishernikosportolos.com

Weekly Downloads

Metadata

AnsiX is an extended ANSI library that provides tools and extensions for Dart & Flutter projects.

Repository (GitHub)
View/report issues

Documentation

Documentation

License

unknown (license)

Dependencies

collection, data_class_plugin, meta, path

More

Packages that depend on ansix

Back