ansi_escape_codes 2.1.0

SDKdartflutter
Platformandroidioswindowslinuxmacos

Yet another package for using ANSI escape codes and analyzing strings containing the escape codes.

ansi_escape_codes

It's yet another one of many packages to work with ANSI escape codes. But there are a few key features:

  • focused on using constants instead of functions, methods and classes
  • analyzing and parsing strings containing escape codes

Table of contents

  1. Control function constants and predefined values

    1.1. Control codes (C0 set)

    1.2. Control functions ESC Fe (C1 set)

    1.3. Control sequences (CSI)

    1.4. Predefined values

    1.5. Independent control functions ESC Fs

    1.6. Select graphic rendition (SGR)

    1.7. 256-color table

    1.8. 24-bit RGB colors

  2. Analyzing and parsing

    2.1. AnsiParser

    2.2. Quick analysis

    2.3. AnsiPrinter

    2.4. Stacked AnsiPrinter

1. Control function constants and predefined values

Strings containing ANSI escape codes can be constants:

const text = '$fgGreen Green text $resetFg'
    '$bgYellow Yellow background $resetBg'
    '$bold Bold text $resetBoldAndFaint'
    '$italicized Italicized text $resetItalicized'
    '$underlined Underlined text $resetUnderlined';
print(text);

For complex cases there are functions:

final nonConstantText = '${fgRgb(255, 128, 0)} Orange text $resetFg';
print(nonConstantText);

But even in these cases it is possible to switch to constants:

const constantText = '${fgRgbOpen}255;128;0$fgRgbClose Orange text $resetFg';
print(constantText);

Of course, nothing prevents you from using the escape codes themselves directly. But even in this case you can use predefined constants to make the text more readable:

import 'package:ansi_escape_codes/controls.dart';

…

const text1 = '\x1B[38;2;255;128;0m Orange text \x1B[0m';
const text2 = '$ESC[38;2;255;128;0m Orange text $ESC[0m';
const text3 = '${CSI}38;2;255;128;0$SGR Orange text ${CSI}0$SGR';
const text4 = '$CSI$FOREGROUND;$COLOR_RGB;255;128;0$SGR Orange text $CSI$RESET$SGR';
print(text1 == text2); // true
print(text2 == text3); // true
print(text3 == text4); // true

Control codes are deliberately named in SCREAMING_SNAKE_CASE as opposed to the common Dart camelCase. First, this is how they are named in the Standard. Second, in this form they will not prevent you from naming your own variables.

1.1. Control codes (C0 set)

These control functions (control codes) are represented by codes from 0x00 to 0x1F. Some control functions from the C0 set:

ConstantCodeDescription
NUL\x00Null
BEL\x07Bell (terminals can block the bell)
BS\b or \x08Backspace
HT\t or \x09Horizontal tabulation
LF\n or \x0ALine feed
FF\f or \x0CForm feed
CR\r or \x0DCarriage return
ESC\x1BEscape (is used for code extension purposes)
import 'package:ansi_escape_codes/controls.dart';

…

print('\t\r\n' == '$HT$CR$LF'); // true

1.2. Control functions ESC Fe (C1 set)

These control functions are represented by 2-character escape sequences of the form ESC Fe, where ESC is represented by code 0x1B and Fe is represented by codes from 0x40 to 0x5F.

Some control functions from the C1 set:

ConstantCodeDescription
CSIESC [Control Sequence Introducer
STESC \String Terminator
OSCESC ]Operating System Command
HTSESC HCharacter Tabulation Set
import 'package:ansi_escape_codes/controls.dart';

…

// Clear screen
print('Erase screen${CSI}2JScreen erased');

// Set new tabulation stops
print('$HTS        $HTS    $HTS  $HTS');
print('1\t2\t3\t4'); // 1       2   3 4
print('${CSI}3g'); // Reset tabulations stops to default

// Link (it doesn't work everywhere)
print('Go to ${OSC}8;;https://pub.dev/packages/ansi_escape_codes${ST}pub.dev${OSC}8;;$ST')

1.3. Control sequences (CSI)

A control sequence is a string starting with the control function CONTROL SEQUENCE INTRODUCER [CSI] followed by one or more bytes representing parameters, if any, and by one or more bytes identifying the control function. The control function [CSI] itself is an element of the C1 set.

Some control functions from this set:

ConstantCodeDescription
CUUCSI n ACursor up by n lines
CUDCSI n BCursor down by n lines
CUFCSI n CCursor right (forward) by n characters
CUBCSI n DCursor left (backward) by n characters
CUPCSI n;m HCursor position to n-th line, m-th character
EDCSI s JErase in page (in display) (s=2 - entire screen)
DCHCSI n PDelete n characters
ECHCSI n XErase n characters
TBCCSI n gTabulation clear (s=3 - all character tabulation stops are cleared)
SMCSI s hSet mode (s=4 - INSERTION REPLACEMENT MODE)
RMCSI s lReset mode
SGRCSI s… mSelect graphic rendition
import 'package:ansi_escape_codes/controls.dart';

…

// Cursor left by 4 characters
// Delete 1 character ('1')
// Cursor right by 1 character
// Erase 1 character ('3')
print('1234${CSI}4$CUB$CSI$DCH$CSI$CUF$CSI$ECH'); // '2 4'

// Insertion mode
print('${CSI}4${SM}tree${CSI}3${CUB}h'); // three
print('${CSI}4${RM}tree${CSI}3${CUB}h'); // thee

// Italicized text
print('${CSI}3$SGR Italicized text ${CSI}0$SGR');

1.4. Predefined values

Predefined values replace the use of control functions with the style used in Dart.

GoalTemplateFunctionDefault constantDescription
Cursor up${cursorUpOpen}$n$cursorUpClosecursorUpN(int n)cursorUpMoves the cursor up n (default 1) lines.
Cursor down${cursorDownOpen}$n$cursorDownClosecursorDownN(int n)cursorDownMoves the cursor down n (default 1) lines.
Cursor forward${cursorRightOpen}$n$cursorRightClosecursorRightN(int n)cursorRightMoves the cursor right n (default 1) characters.
Cursor back${cursorLeftOpen}$n$cursorLeftClosecursorLeftN(int n)cursorLeftMoves the cursor left n (default 1) characters.
Cursor next line${cursorNextLineOpen}$n$cursorNextLineClosecursorNextLineN(int n)cursorNextLineMoves cursor to beginning of the line n (default 1) lines down.
Cursor prev line${cursorPrevLineOpen}$n$cursorPrevLineClosecursorPrevLineN(int n)cursorPrevLineMoves cursor to beginning of the line n (default 1) lines up.
Cursor horizontal pos${cursorHPosOpen}$n$cursorHPosClosecursorHPosN(int n)cursorHPosMoves the cursor to column n (default 1).
Cursor pos${cursorPosOpen}$row;$col$cursorPosClosecursorPosTo(int row, int col)cursorPosMoves the cursor to row and col.
Cursor horizontal and vertical pos${cursorHVPosOpen}$row;$col$cursorHVPosClosecursorHVPosTo(int row, int col)cursorHVPosSame as cursorPos, just with some differences.
Erase in page${eraseInPageOpen}$s$eraseInPageCloseeraseInPage…Erases part of the page: s=0 (or missing) - to end (eraseInPageToEnd), s=1 - to beginning (eraseInPageToBegin), s=2 - entire page (erasePage).
Erase in line${eraseInLineOpen}$s$eraseInLineCloseeraseInLine…Erases part of the line: s=0 (or missing) - to end (eraseInLineToEnd), s=2 - to beginning (eraseInLineToBegin), s=2 - entire line (eraseLine).
Scroll up${scrollUpOpen}$n$scrollUpClosescrollUpN(int n)scrollUpScroll page up by n (default 1) lines. New lines are added at the bottom.
Scroll down${scrollDownOpen}$n$scrollDownClosescrollDownN(int n)scrollDownScroll page down by n (default 1) lines. New lines are added at the top.
Hide cursorhideCursorShows the cursor.
Show cursorshowCursorHides the cursor.
Save cursorsaveCursorSaves the cursor position, encoding shift state and formatting attributes.
Restore cursorrestoreCursorRestores the cursor position, encoding shift state and formatting attributes from the previous saveCursor if any, otherwise resets these all to their defaults.
print('${CSI}4$CUU' == cursorUpN(4)); // true
print('${CSI}4$CUU' == '${cursorUpOpen}4$cursorUpClose'); // true
print('$CSI$CUU' == cursorUp); // true

1.5. Independent control functions ESC Fs

The paragraph will appear later.

1.6. Select graphic rendition (SGR)

Template for working with graphic rendition:

CSI s… SGR

Where s is:

IndexConstantPredefined valueDescription
0RESETresetDefault rendition (implementation-defined), cancels the effect of any preceding occurrence of SGR
1BOLDboldBold or increased intensity
2FAINTfaintFaint, decreased intensity or second color
3ITALICIZEDitalicizedItalicized
4UNDERLINEDunderlinedSingly underlined
5SLOWLY_BLINKINGslowlyBlinkingSlowly blinking (less then 150 per minute)
6RAPIDLY_BLINKINGrapidlyBlinkingRapidly blinking (150 per minute or more)
7NEGATIVEnegativeNegative image
8CONCEALEDconcealedConcealed characters
9CROSSEDOUTcrossedOutCrossed-out (characters still legible but marked as to be deleted)
10PRIMARY_FONTPrimary (default) font
11ALT_FONT_1First alternative font
12ALT_FONT_2Second alternative font
13ALT_FONT_3Third alternative font
14ALT_FONT_4Fourth alternative font
15ALT_FONT_5Fifth alternative font
16ALT_FONT_6Sixth alternative font
17ALT_FONT_7Seventh alternative font
18ALT_FONT_8Eighth alternative font
19ALT_FONT_9Ninth alternative font
20FRAKTURFraktur (Gothic)
21DOUBLY_UNDERLINEDdoublyUnderlinedDoubly underlined
22NOT_BOLD_NOT_FAINTresetBoldAndFaintNormal colour or normal intensity (neither bold nor faint)
23NOT_ITALICIZEDresetItalicizedNot italicized, not fraktur
24NOT_UNDERLINEDresetUnderlinedNot underlined (neither singly nor doubly)
25NOT_BLINKINGresetBlinkingSteady (not blinking)
27NOT_NEGATIVEresetNegativePositive image (not negative)
28NOT_CONCEALEDresetConcealedRevealed characters (not concealed)
29NOT_CROSSEDOUTresetCrossedOutNot crossed out
30FG_BLACKfgBlackBlack display (color #0 from 256-color table)
31FG_REDfgRedRed display (color #1 from 256-color table)
32FG_GREENfgGreenGreen display (color #2 from 256-color table)
33FG_YELLOWfgYellowYellow display (color #3 from 256-color table)
34FG_BLUEfgBlueBlue display (color #4 from 256-color table)
35FG_MAGENTAfgMagentaMagenta display (color #5 from 256-color table)
36FG_CYANfgCyanCyan display (color #6 from 256-color table)
37FG_WHITEfgWhiteWhite display (color #7 from 256-color table)
38FOREGROUNDfg256…/fgRgb…Display color from 256-color table or by RGB
39FG_DEFAULTfgDefaultDefault display color (implementation-defined)
40BG_BLACKbgBlackBlack background (color #0 from 256-color table)
41BG_REDbgRedRed background (color #1 from 256-color table)
42BG_GREENbgGreenGreen background (color #2 from 256-color table)
43BG_YELLOWbgYellowYellow background (color #3 from 256-color table)
44BG_BLUEbgBlueBlue background (color #4 from 256-color table)
45BG_MAGENTAbgMagentaMagenta background (color #5 from 256-color table)
46BG_CYANbgCyanCyan background (color #6 from 256-color table)
47BG_WHITEbgWhiteWhite background (color #7 from 256-color table)
48BACKGROUNDbg256…/bgRgb…Background color from 256-color table or by RGB
49BG_DEFAULTbgDefaultDefault background color (implementation-defined)
51FRAMEDframedFramed
52ENCIRCLEDencircledEncircled
53OVERLINEDoverlinedOverlined
54NOT_FRAMED_NOT_ENCIRCLEDresetFramedAndEncircledNot framed, not encircled
55NOT_OVERLINEDresetOverlinedNot overlined
58UNDERLINE_COLORunderlineColor256…/underlineColorRgb…Underline color from 256-color table or by RGB
59UNDERLINE_COLOR_DEFAULTunderlineColorDefaultDefault underline color
73SUPERSCRIPTEDsuperscriptedSuperscripted
74SUBSCRIPTEDsubscriptedSubscripted
75NOT_SUPER_NOT_SUBSCRIPTEDresetSuperAnsSubscriptedNot superscripted, not subscipted
90FG_HIGH_BLACKfgHighBlackHigh black display (color #8 from 256-color table)
91FG_HIGH_REDfgHighRedHigh red display (color #9 from 256-color table)
92FG_HIGH_GREENfgHighGreenHigh green display (color #10 from 256-color table)
93FG_HIGH_YELLOWfgHighYellowHigh yellow display (color #11 from 256-color table)
94FG_HIGH_BLUEfgHighBlueHigh blue display (color #12 from 256-color table)
95FG_HIGH_MAGENTAfgHighMagentaHigh magenta display (color #13 from 256-color table)
96FG_HIGH_CYANfgHighCyanHigh cyan display (color #14 from 256-color table)
97FG_HIGH_WHITEfgHighWhiteHigh white display (color #15 from 256-color table)
100BG_HIGH_BLACKbgHighBlackHigh black background (color #8 from 256-color table)
101BG_HIGH_REDbgHighRedHigh red background (color #9 from 256-color table)
102BG_HIGH_GREENbgHighGreenHigh green background (color #10 from 256-color table)
103BG_HIGH_YELLOWbgHighYellowHigh yellow background (color #11 from 256-color table)
104BG_HIGH_BLUEbgHighBlueHigh blue background (color #12 from 256-color table)
105BG_HIGH_MAGENTAbgHighMagentaHigh magenta background (color #13 from 256-color table)
106BG_HIGH_CYANbgHighCyanHigh cyan background (color #14 from 256-color table)
107BG_HIGH_WHITEbgHighWhiteHigh white background (color #15 from 256-color table)

Example:

print('${CSI}4$SGR' == underlined); // true
print('$CSI$UNDERLINED$SGR' == underlined); // true

print('$underlined Underlined text $resetUnderlined');

print('$fgYellow$bgGreen Yellow on green $resetBg$resetFg');

1.7. 256-color table

https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit

Template for setting the color from 256-color table:

CSI FOREGROUND/BACKGROUND/UNDERLINE_COLOR;COLOR_256;n SGR

Where n is:

IndexConstantPredefined valueComment
0BLACK(fg/bg/underline)256Black
1RED(fg/bg/underline)256Red
2GREEN(fg/bg/underline)256Green
3YELLOW(fg/bg/underline)256Yellow
4BLUE(fg/bg/underline)256Blue
5MAGENTA(fg/bg/underline)256Magenta
6CYAN(fg/bg/underline)256Cyan
7WHITE(fg/bg/underline)256White
8HIGH_BLACK(fg/bg/underline)256HighBlack
9HIGH_RED(fg/bg/underline)256HighRed
10HIGH_GREEN(fg/bg/underline)256HighGreen
11HIGH_YELLOW(fg/bg/underline)256HighYellow
12HIGH_BLUE(fg/bg/underline)256HighBlue
13HIGH_MAGENTA(fg/bg/underline)256HighMagenta
14HIGH_CYAN(fg/bg/underline)256HighCyan
15HIGH_WHITE(fg/bg/underline)256HighWhite
16-231RGB_<r><g><b>(fg/bg/underline)256Rgb<r><g><b>r,g,b are numbers from 0 to 5 (6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b)
232-255GRAY<n>(fg/bg/underline)256Gray<n>n is a number from 0 to 23 (grayscale from dark to light in 24 steps)

Example:

const text1 = '$CSI$FOREGROUND;$COLOR_256;$YELLOW$SGR Yellow text $CSI$FG_DEFAULT$SGR';
const text2 = '$fg256Open$YELLOW$fg256Close Yellow text $resetFg';
final text3 = '${fg256(YELLOW)} Yellow text $resetFg'; // Not constant!
const text4 = '$fg256Yellow Yellow text $resetFg';
print(text1 == text2); // true
print(text2 == text3); // true
print(text3 == text4); // true

You can also use functions to get the color index:

int rgb(int r, int g, int b); // r,g,b are numbers from 0 to 5
int gray(int level); // level is number from 0 to 23

And use next functions to set the color from 256-color table by index:

String fg256(int index); // index is number from 0 to 255
String bg256(int index);
String underline256(int index);

Example:

const text1 = '$fg256Rgb550 Yellow text $resetFg';
const text2 = '$fg256Open$RGB_550$fg256Close Yellow text $resetFg';
final text3 = '${fg256(RGB_550)} Yellow text $resetFg';
final text4 = '${fg256(rgb(5, 5, 0))} Yellow text $resetFg';
print(text1 == text2); // true
print(text2 == text3); // true
print(text3 == text4); // true

1.8. 24-bit RGB colors

https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit

Template for setting the color from 256-color table:

CSI FOREGROUND/BACKGROUND/UNDERLINE_COLOR;COLOR_RGB;r;g;b SGR

Where r, g and b are the corresponding color components in the RGB form.

You can use next functions to set the color by RGB:

String fgRgb(int r, int g, int b); // r,g,b are numbers from 0 to 255
String bgRgb(int r, int g, int b);
String underlineRgb(int r, int g, int b);

Example:

const text1 = '$CSI$BACKGROUND;$COLOR_RGB;44;43;124$SGR Ultramarine $CSI$FG_DEFAULT$SGR';
const text2 = '${bgRgbOpen}44;43;124$fg256Close Ultramarine $resetFg';
final text3 = '${bgRgb(44, 43, 124)} Ultramarine $resetFg'; // Not constant!
print(text1 == text2); // true
print(text2 == text3); // true

2. Analyzing and parsing

2.1. AnsiParser

AnsiParser allows you to analyze text containing escape codes:

const text = '$bold Bold $fgCyan Bold+cyan $resetBoldAndFaint Cyan ';
final parser = AnsiParser(text);
parser.matches.forEach(print);
// Match(start: 0, end: 4, entity: Sgr(bold), state: SgrState(bold))
// Match(start: 4, end: 10, entity: Text(' Bold '), state: SgrState(bold))
// Match(start: 10, end: 15, entity: Sgr(fgCyan), state: SgrState(bold, foreground: Color16(Colors.cyan)))
// Match(start: 15, end: 26, entity: Text(' Bold+cyan '), state: SgrState(bold, foreground: Color16(Colors.cyan)))
// Match(start: 26, end: 31, entity: Sgr(resetBoldAndFaint), state: SgrState(foreground: Color16(Colors.cyan)))
// Match(start: 31, end: 37, entity: Text(' Cyan '), state: SgrState(foreground: Color16(Colors.cyan)))

In this way we can, for example, remove all escape codes:

final buf = StringBuffer();
for (final m in parser.matches) {
  switch (m.entity) {
    case Text(:final string):
      buf.write(string);
    case EscapeCode():
      break;
  }
}
print(buf); // ' Bold  Bold+cyan  Cyan '

There is a ready-made method for this:

print(parser.removeAll());

Or replace the escape codes with a readable form:

final buf = StringBuffer();
for (final m in parser.matches) {
  final result = switch (m.entity) {
    EscapeCode(:final id) => '[$id]',
    Text(:final string) => string,
  };
  buf.write(result);
}
print(buf); // [bold] Bold [fgCyan] Bold+cyan [resetBoldAndFaint] Cyan

You can also use ready-made methods for this:

print(parser.replaceAll((e) => '[${e.id}]'));
print(parser.showControlFunctions());

You can find out the length of plain text without escape codes using length:

print(parser.length == parser.removeAll().length); // true
print(parser.length); // 23

The state at a particular position can be found with stateAtPos.

final state = parser.stateAtPos(7);
print(state); // SgrState(bold, foreground: Color16(Colors.cyan))
print(state.isBold); // true
print(state.isItalicized); // false
print(state.foreground?.id); // fgCyan
print(state.background?.id); // null

The position in stateAtPos is specified in the plaintext range (pos < parser.length) and can also point to the position behind the text (pos == parser.length) to find out the final state. The final state can also be obtained using finalState.

print(parser.stateAtPos(23) == parser.finalState); // true
print(parser.finalState); // SgrState(foreground: Color16(Colors.cyan))

In the above example, the text state was not set to default, i.e. the text was not closed:

print(parser.isClosed); // false

The easiest way to close a text is to add a reset at the end of it:

const closedText = '$text$reset';
print(AnsiParser(closedText).isClosed); // true

The substring method allows you to retrieve a piece of text by computing together its state:

final substring = parser.substring(7, maxLength: 9);
print(AnsiParser(substring).showControlFunctions()); // [fgCyan;bold]Bold+cyan[reset]

By default, the substring is closed. Escape codes is always included in the string in optimized form:

const test1 = '$fgCyan$bold';
final test2 = substring.substring(0, substring.indexOf('Bold'));
print(test1.showEscapeCodes()); // [CSI 36 SGR][CSI 1 SGR]
print(test2.showEscapeCodes()); // [CSI 36;1 SGR]
print(AnsiParser(test1).showControlFunctions()); // [fgCyan][bold]
print(AnsiParser(test2).showControlFunctions()); // [fgCyan;bold]
print(test1.length); // 9
print(test2.length); // 7

To optimize the entire string, there is an optimize method:

const text = '$fgWhite$bold$resetBoldAndFaint$fgGreen$underlined'
    "$resetUnderlined$faint$faint What's in here? $resetBoldAndFaint$resetFg";
print(text.length); // 63
final parser = AnsiParser(text);
print(parser.showControlFunctions());
// [fgWhite][bold][resetBoldAndFaint][fgGreen][underlined][resetUnderlined][faint][faint] What's in here? [resetBoldAndFaint][resetFg]

final optimizedText = parser.optimize();
print(optimizedText.length); // 28
print(AnsiParser(optimizedText).showControlFunctions());
// [fgGreen;faint] What's in here? [reset]

2.2. Quick analysis

You can quickly analyze a string without using AnsiParser by using extensions.

import 'package:ansi_escape_codes/extensions.dart';

…

const text = '${fgRed}ERROR$reset';
print(text.hasEscapeCodes); // true
print(text.hasCsi); // true
print(text.hasSgr); // true
print(text.hasForeground); // true
print(text.hasBackground); // false
print(text.showEscapeCodes()); // [CSI 31 SGR]ERROR[CSI 0 SGR]

The method showControlCodes allows to show all control codes from C0 set in a string:

const text = 'Tab: \t Line feed: \n Carriage return: \r Bell: \x07';

print(text.showControlCodes());
// Tab: \t Line feed: \n Carriage return: \r Bell: \x07

print(text.showControlCodes(preferStyle: ControlCodeStyle.charCode));
// Tab: \x09 Line feed: \x0A Carriage return: \x0D Bell: \x07

print(text.showControlCodes(preferStyle: ControlCodeStyle.abbr));
// Tab: [HT] Line feed: [LF] Carriage return: [CR] Bell: [BEL]

print(text.showControlCodes(preferStyle: ControlCodeStyle.unicodeSymbol));
// Tab: ␉ Line feed: ␊ Carriage return: ␍ Bell: ␇

You can quickly remove all codes using the methods:

const text = '$saveCursor$cursorRight$italicized$bgGreen$fgYellow Text $resetFg$resetBg$resetItalicized$restoreCursor';
print(AnsiParser(text).showControlFunctions());
// [saveCursor][CSI CUF][italicized][bgGreen][fgYellow] Text [resetFg][resetBg][resetItalicized][restoreCursor]

print(AnsiParser(text.removeBackground()).showControlFunctions());
// [saveCursor][CSI CUF][italicized][fgYellow] Text [resetFg][resetItalicized][restoreCursor]

print(AnsiParser(text.removeBackground().removeForeground()).showControlFunctions());
// [saveCursor][CSI CUF][italicized] Text [resetItalicized][restoreCursor]

print(AnsiParser(text.removeSgr()).showControlFunctions());
// [saveCursor][CSI CUF] Text [restoreCursor]

print(AnsiParser(text.removeCsi()).showControlFunctions());
// [saveCursor] Text [restoreCursor]

print(text.removeEscapeCodes().showEscapeCodes());
// ' Text '

2.3. AnsiPrinter

Escape codes do not allow you to set default values for your text. The foreground and background colors depend on the implementation of the terminal you are using. And so if you want to use some other values, you cannot use resetFg (CSI FOREGROUND_DEFAULT SGR) and resetBg (CSI BACKGROUND_DEFAULT SGR). Each time you will have to substitute your own values instead:

const text =
    '${bgRgbOpen}44;43;124$bgRgbClose${fgRgbOpen}224;192;64$fgRgbClose Default text '
    '$bgWhite$fgBlack Highlighted text '
    '${bgRgbOpen}44;43;124$bgRgbClose${fgRgbOpen}224;192;64$fgRgbClose Default text again $reset';
print(text);

You can move the color setting to constants and use them everywhere:

const bgDefault = '${bgRgbOpen}44;43;124$bgRgbClose';
const fgDefault = '${fgRgbOpen}224;192;64$fgRgbClose';
const text = '$bgDefault$fgDefault Default text '
    '$bgWhite$fgBlack Highlighted text '
    '$bgDefault$fgDefault Default text again $reset';
print(text);

Or you can use AnsiPrinter:

const text = ' Default text '
    '$bgWhite$fgBlack Highlighted text '
    '$resetBg$resetFg Default text again $reset';
final printer = AnsiPrinter(
  defaultState: SgrPlainState(
    background: ColorRgb(44, 43, 124),
    foreground: ColorRgb(224, 192, 64),
  ),
);
printer.print(text);

The printer itself will substitute the correct values where the state returns to default. The texts will remain clean, and you can change the default values or remove them altogether at any time.

Additionally, Dart allows you to use zones to hide the use of the printer under the hood:

void main() {
  runZonedAnsiPrinter(
    defaultState: SgrPlainState(
      background: ColorRgb(44, 43, 124),
      foreground: ColorRgb(224, 192, 64),
    ),
    () {
      // … Your application code …

      const text = ' Default text '
          '$bgWhite$fgBlack Highlighted text '
          '$resetBg$resetFg Default text again $reset';

      print(text); // Use the usual print
    },
  );
}

All calls to the print function will be intercepted and modified to use the values you need.

If you need the codes for debugging Flutter apps, you'll notice that when debugging iOS apps, the console will receive messages with escaped escape codes in them. This is a known issue and is currently (02.2025) unresolved: https://github.com/flutter/flutter/issues/20663. There is no way around this issue. But there are two ways to minimize it.

The first way is to use the log method from 'dart:developer'. The log outputs the escape codes on iOS correctly:

import 'dart:developer';

…

runZonedAnsiPrinter(
  defaultState: const SgrPlainState(
    background: Color16.green,
    foreground: Color16.yellow,
  ),
  output: log,
  () {
    const text = ' Default text '
        '$bgWhite$fgBlack Highlighted text '
        '$resetBg$resetFg Default text again $reset';
    print(text);
  },
);

Unfortunately, the log method outputs long messages (more than 128 characters) as <collected>. And it is easy to exceed the allowed size when using escape codes. In the example above, the text does not fit in this size if RGB colors are used.

And secondly, log works only from IDE. Testers who don't use IDE won't see anything in the console.

So in most cases on iOS, it's left to disable escape codes for the most part:

runZonedAnsiPrinter(
  defaultState: …,
  ansiCodesEnabled: !Platform.isIOS,
  () {
    const text = ' Default text '
        '$bgWhite$fgBlack Highlighted text '
        '$resetBg$resetFg Default text again $reset';
    print(text);
  },
);

2.4. Stacked AnsiPrinter

Escape codes allow you to do simple text decoration. But a slightly more complex design requires much more effort. One example is given above, when you need a default style different from the one provided by the terminal.

Imagine that you have a template for text into which you will insert other text, that is sent to you externally. But the person who sends you this text decides to highlight it:

String makeMessage(String name) {
  const template = 'Dear {name}! We are pleased to present to you …';

  return template.replaceAll('{name}', name);
}

…

const name = '${bold}Sam$resetBoldAndFaint';

…

final text = makeMessage(name);
print(text);
// Dear [bold]Sam[resetBoldAndFaint]! We are pleased to present to you …

Without noticing it, at some point your designer decides to make changes to the template:

const template = '${bold}Dear {name}, welcome to us!$resetBoldAndFaint We are pleased to present to you …';

…

final text = makeMessage(name);
print(text);
// [bold]Dear [bold]Sam[resetBoldAndFaint], welcome to us![resetBoldAndFaint] We are pleased to present to you …

But the escape codes don't accumulate, double bold equals single bold. And first resetBoldAndFaint cancels the bold text. And we don't get what we want at all. To fix it, we need to return the state of the text after insertion to the state it was before insertion. But it makes it much more difficult to use the escape codes. AnsiPrinter helps solve this problem:

final printer = AnsiPrinter(stacked: true);
printer.print(text);
// [bold]Dear Sam, welcome to us![resetBoldAndFaint] We are pleased to present to you …

AnsiPrinter with the stacked parameter accumulates state changes and sequentially disables them, translating the current state into the standard escape sequence on output:

const text = '$bold 1 $bold 2 $bold 3 $resetBoldAndFaint 2 $resetBoldAndFaint 1 $resetBoldAndFaint';
final printer1 = AnsiPrinter();
final printer2 = AnsiPrinter(stacked: true);
printer1.print(text); // '[bold] 1  2  3 [resetBoldAndFaint] 2  1 '
printer2.print(text); // '[bold] 1  2  3  2  1 [resetBoldAndFaint]'

That's all for now.