Module embedded_text::plugin::ansi

In-band text styling using ANSI escape codes

Sometimes you need more flexibility than what a single style object can provide, like changing MonoFont color for a specific word in the text. embedded-text supports this use case by using a subset of the standard ANSI escape codes. These are special character sequences you can use in the text to change the MonoFont style of the text itself. This documentation does not aim to provide a full specification of all the ANSI escape codes, only describes the supported subset.

Note: if embedded-text fails to parse an escape sequence, it will ignore the \x1b character and display the rest as normal text.

All escape sequences start with the \x1b[ sequence, where \x1b is the ASCII escape character. embedded-text supports a subset of the SGR parameters, which are numeric codes with specific functions, followed by a number of parameters and end with the m character.

Currently, embedded-text supports changing the text and background colors. To do this, you have the following options:

Standard color codes

The standard color codes option is the simplest, and least flexible way to set color.

Color name	Text color	Background color	RGB888
Black	\x1b[30m	\x1b[40m	12,12,12
Red	\x1b[31m	\x1b[41m	197,15,31
Green	\x1b[32m	\x1b[42m	19,161,14
Yellow	\x1b[33m	\x1b[43m	193,156,0
Blue	\x1b[34m	\x1b[44m	0,55,218
Magenta	\x1b[35m	\x1b[45m	136,23,152
Cyan	\x1b[36m	\x1b[46m	58,150,221
White	\x1b[37m	\x1b[47m	204,204,204
Gray (Bright Black)	\x1b[90m	\x1b[100m	118,118,118
Bright Red	\x1b[91m	\x1b[101m	231,72,86
Bright Green	\x1b[92m	\x1b[102m	22,198,12
Bright Yellow	\x1b[93m	\x1b[103m	249,241,165
Bright Blue	\x1b[94m	\x1b[104m	59,120,255
Bright Magenta	\x1b[95m	\x1b[105m	180,0,158
Bright Cyan	\x1b[96m	\x1b[106m	97,214,214
Bright White	\x1b[97m	\x1b[107m	242,242,242

8 bit colors

8 bit colors are in the form of either \x1b[38;5;<n>m (text color) or \x1b[48;5;<n>m (background color) sequence. Here, <n> marks a parameter that determines the color. <n> can have the following values:

• 0-15: standard colors in the order of the above table. For example, \x1b[38;5;12m is the Bright Blue color.
• 16-231: 6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
• 232-255: grayscale from black to white

24 bit colors

8 bit colors are in the form of either \x1b[38;2;<r>;<g>;<b>m (text color) or \x1b[48;2;<r>;<g>;<b>m (background color) sequence. Here, <r>, <g> and <b> can take any value between 0 and 255.

Supported color types

embedded-text supports all color types that are included in embedded-graphics.

If you wish to use a different color type, the types needs to implement From<Rgb888>.

Other text styling options

The following SGR sequences are supported:

• \x1b[0m: Reset everything
• \x1b[4m: Underlined text
• \x1b[24m: Turn off text underline
• \x1b[9m: Crossed out/strikethrough text
• \x1b[29m: Turn off strikethrough
• \x1b[39m: Reset text color
• \x1b[49m: Reset background color

Reset style options to default

embedded-text supports the Reset all (\x1b[0m), Default text color (\x1b[39m) and Default background color (\x1b[49m) codes. These codes can be used to reset colors to transparent (i.e. no pixels drawn for text or background).

In addition, Reset all turns off the underlined and crossed out styles.

Other supported ANSI escape codes

Besides changing text style, you can also move the cursor using ANSI escape codes! You have the following options:

• Move the cursor forward <n> characters: \x1b[<n>C. This command will stop at the end of line, so you can use it to simulate a highlighted line, for example. Note: Moving the cursor forward fills the line with the background color. If you want to avoid this, make sure to reset the background color before moving the cursor!
• Move the cursor backward <n> characters: \x1b[<n>D. This command will stop at the start of line.

Structs

Ansi

Ansi sequence parser plugin.