Macros to apply color and style to text in supporting terminal emulators. More...

Detailed Description

Macros to apply color and style to text in supporting terminal emulators.

Use ANSI_STYLED, and ANSI_STYLE to customize text color, color intensities, and text styles, such as bold or underlined text.

const char* just_bold1    = ANSI_STYLE(BOLD) "Error!" ANSI_STYLE();
const char* just_bold2    = ANSI_STYLED("Error!", BOLD);
 
const char* just_colored1 = ANSI_STYLE(FOREGROUND(RED)) "Error!" ANSI_STYLE();
const char* just_colored2 = ANSI_STYLED("Error!", FOREGROUND(RED));
 
const char* fancy1 =
  ANSI_STYLE(FOREGROUND_BRIGHT(YELLOW), BACKGROUND(PURPLE), BOLD, UNDERLINED) \
  "Hello," \
  ANSI_STYLE(BACKGROUND_BRIGHT(PRIMARY), ITALIC) \
  " World!" \
  ANSI_STYLE();
 
const char* fancy2 =
  ANSI_STYLED("Hello,", FOREGROUND_BRIGHT(YELLOW), BACKGROUND(PURPLE), BOLD, UNDERLINED) \
  ANSI_STYLED(" World!", BACKGROUND_BRIGHT(PRIMARY), ITALIC);

Files
file	ansi_style.h
	ANSI SGR definitions.

SGR escape sequence
#define	_ANSI_SGR_PREFIX "\x1b["
	ANSI escape prefix.

#define	_ANSI_SGR_SUFFIX "m"
	ANSI color/style suffix.

Color codes
#define	_ANSI_COLOR_CODE_PRIMARY "0"
	ANSI color code for primary color (black in light appearance, white in dark)

#define	_ANSI_COLOR_CODE_BLACK _ANSI_COLOR_CODE_PRIMARY
	Alias for _ANSI_COLOR_CODE_PRIMARY.

#define	_ANSI_COLOR_CODE_RED "1"
	ANSI color code for red.

#define	_ANSI_COLOR_CODE_GREEN "2"
	ANSI color code for green.

#define	_ANSI_COLOR_CODE_YELLOW "3"
	ANSI color code for yellow.

#define	_ANSI_COLOR_CODE_BLUE "4"
	ANSI color code for blue.

#define	_ANSI_COLOR_CODE_PURPLE "5"
	ANSI color code for purple (pink, magenta)

#define	_ANSI_COLOR_CODE_CYAN "6"
	ANSI color code for cyan (light blue)

#define	_ANSI_COLOR_CODE_WHITE "7"
	ANSI color code for white (gray)

#define	_ANSI_COLOR_CODE_RGB(r, g, b)
	ANSI color code for 24-bit RGB colors.

#define	_ANSI_COLOR_CODE_INDEXED(index)
	ANSI color code for 8-bit indexed colors.

Color modifiers
#define	_ANSI_COLOR_MODIFIER_FOREGROUND "3"
	ANSI modifier to make color apply to foreground text.

#define	_ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND "9"
	ANSI modifier to make color apply to foreground text in high intensity.

#define	_ANSI_COLOR_MODIFIER_BACKGROUND "4"
	ANSI modifier to make color apply to background.

#define	_ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND "10"
	ANSI modifier to make color apply to background in high intensity.

Color styles
#define	ANSI_STYLE_FOREGROUND(color)
	ANSI style for foreground text color.

#define	ANSI_STYLE_FG(color)
	Alias for ANSI_STYLE_FOREGROUND.

#define	ANSI_STYLE_FOREGROUND_BRIGHT(color)
	ANSI style for a brighter foreground text color.

#define	ANSI_STYLE_FG_BRIGHT(color)
	Alias for ANSI_STYLE_FOREGROUND_BRIGHT.

#define	ANSI_STYLE_BACKGROUND(color)
	ANSI style for foreground text color.

#define	ANSI_STYLE_BG(color)
	Alias for ANSI_STYLE_BACKGROUND.

#define	ANSI_STYLE_BACKGROUND_BRIGHT(color)
	ANSI style for a brighter foreground text color.

#define	ANSI_STYLE_BG_BRIGHT(color)
	Alias for ANSI_STYLE_BACKGROUND_BRIGHT.

Text styles
#define	ANSI_STYLE_BOLD "1"
	ANSI style for bold text.

#define	ANSI_STYLE_DIM "2"
	ANSI style for dimmer, thinner, less prominent text.

#define	ANSI_STYLE_ITALIC "3"
	ANSI style for italic text.

#define	ANSI_STYLE_UNDERLINED "4"
	ANSI style for underlined text.

#define	ANSI_STYLE_BLINK_SLOW "5"
	ANSI style for slowly blinking text.

#define	ANSI_STYLE_BLINK_FAST "6"
	ANSI style for fast-blinking text.

#define	ANSI_STYLE_NEGATED "7"
	ANSI style swapping foreground and background color settings.

#define	ANSI_STYLE_CONCEALED "8"
	ANSI style for concealed (redacted) text.

#define	ANSI_STYLE_STRIKETHROUGH "9"
	ANSI style for crossed out text (strikethrough)

Formatting macros
#define	ANSI_STYLE(...)
	Builds string literal for a terminal emulator to apply color and text styles to subsequent text.

#define	ANSI_STYLE_RESET _ANSI_SGR_PREFIX ANSI_STYLE_NONE _ANSI_SGR_SUFFIX
	Resets text color and style applied previously back to defaults.

#define	ANSI_STYLED(text, ...)
	Applies ANSI styling but only modifies given text.

Macro Definition Documentation

◆ _ANSI_COLOR_CODE_BLACK

#define _ANSI_COLOR_CODE_BLACK _ANSI_COLOR_CODE_PRIMARY

Alias for _ANSI_COLOR_CODE_PRIMARY.

Definition at line 73 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_BLUE

#define _ANSI_COLOR_CODE_BLUE "4"

ANSI color code for blue.

Definition at line 85 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_CYAN

#define _ANSI_COLOR_CODE_CYAN "6"

ANSI color code for cyan (light blue)

Definition at line 91 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_GREEN

#define _ANSI_COLOR_CODE_GREEN "2"

ANSI color code for green.

Definition at line 79 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_INDEXED

#define _ANSI_COLOR_CODE_INDEXED ( index )

Value:

"8;5;" XTSTR(index)

XTSTR

#define XTSTR(x)

A macro to return the string representation of x.

Definition xtstr.h:33

ANSI color code for 8-bit indexed colors.

Definition at line 100 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_PRIMARY

#define _ANSI_COLOR_CODE_PRIMARY "0"

ANSI color code for primary color (black in light appearance, white in dark)

Definition at line 70 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_PURPLE

#define _ANSI_COLOR_CODE_PURPLE "5"

ANSI color code for purple (pink, magenta)

Definition at line 88 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_RED

#define _ANSI_COLOR_CODE_RED "1"

ANSI color code for red.

Definition at line 76 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_RGB

#define _ANSI_COLOR_CODE_RGB	(	r,
		g,
		b )

Value:

"8;2;" XTSTR(r) ";" XTSTR(g) ";" XTSTR(b)

ANSI color code for 24-bit RGB colors.

Definition at line 97 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_WHITE

#define _ANSI_COLOR_CODE_WHITE "7"

ANSI color code for white (gray)

Definition at line 94 of file ansi_style.h.

◆ _ANSI_COLOR_CODE_YELLOW

#define _ANSI_COLOR_CODE_YELLOW "3"

ANSI color code for yellow.

Definition at line 82 of file ansi_style.h.

◆ _ANSI_COLOR_MODIFIER_BACKGROUND

#define _ANSI_COLOR_MODIFIER_BACKGROUND "4"

ANSI modifier to make color apply to background.

Definition at line 116 of file ansi_style.h.

◆ _ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND

#define _ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND "10"

ANSI modifier to make color apply to background in high intensity.

Definition at line 119 of file ansi_style.h.

◆ _ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND

#define _ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND "9"

ANSI modifier to make color apply to foreground text in high intensity.

Definition at line 113 of file ansi_style.h.

◆ _ANSI_COLOR_MODIFIER_FOREGROUND

#define _ANSI_COLOR_MODIFIER_FOREGROUND "3"

ANSI modifier to make color apply to foreground text.

Definition at line 110 of file ansi_style.h.

◆ _ANSI_SGR_PREFIX

#define _ANSI_SGR_PREFIX "\x1b["

ANSI escape prefix.

Definition at line 57 of file ansi_style.h.

◆ _ANSI_SGR_SUFFIX

#define _ANSI_SGR_SUFFIX "m"

ANSI color/style suffix.

Definition at line 60 of file ansi_style.h.

◆ ANSI_STYLE

#define ANSI_STYLE ( ... )

Value:

    _ANSI_SGR_PREFIX \
    __ANSI_APPLY_STYLES(__VA_ARGS__) \
    _ANSI_SGR_SUFFIX

Builds string literal for a terminal emulator to apply color and text styles to subsequent text.

This macro uses ANSI Select Graphic Rendition (SGR) codes to instruct terminal emulators that support SGR to apply custom styling to subsequent text. You output this macro before any text, e.g., by calling puts or printf separately, or by using static string literal concatenation in C. For example, this is how you would format "Hello, World!" such that it appears purple, bold, and underlined. You must append ANSI_STYLE_RESET to return to the default terminal text format.

const char* message =

ANSI_STYLE(FOREGROUND(PURPLE), BOLD, UNDERLINED) "Hello, World!" ANSI_STYLE();

You can also override/chain the current format in the string using static string concatenation.

const char* message =
  ANSI_STYLE(FOREGROUND(PURPLE), BOLD) "styled" ANSI_STYLE(BACKGROUND(YELLOW), ITALIC) \
  "styled" ANSI_STYLE_RESET;

Parameters

...	Variadic style arguments to apply to following text, . e.g., `FOREGROUND(RED)`, `BOLD`, `UNDERLINED`

You may apply multiple styles, currently up to 6, from the following categories.

Color styling

Choose one of the FOREGROUND(color), BACKGROUND(color), or their brighter variants FOREGROUND_BRIGHT(color) and BACKGROUND_BRIGHT(color) as an argument to this macro, with color being one of the following:

PRIMARY is black on white/light terminal backgrounds/themes and white in black/dark themes
RED
GREEN
YELLOW
BLUE
CYAN
WHITE may appear gray
RGB(r, g, b) where r, g, and b are number literals between 0 and 255
INDEXED(index) where index is the ANSI SGR color index between 0 and 255

You may not use FOREGROUND_BRIGHT and BACKGROUND_BRIGHT with the RGB and INDEXED color modes. These macros only make the predefined ANSI colors above appear brighter. You can add up to one foreground style, and up to one background style, i.e., only the normal color style or the _BRIGHT variant.

ANSI_STYLE(FOREGROUND_BRIGHT(PURPLE), BACKGROUND_BRIGHT(YELLOW))
ANSI_STYLE(FOREGROUND_BRIGHT(PURPLE), BACKGROUND(YELLOW))
ANSI_STYLE(FOREGROUND(PURPLE), BACKGROUND_BRIGHT(YELLOW))
ANSI_STYLE(FOREGROUND(PURPLE), BACKGROUND(YELLOW))
ANSI_STYLE(FOREGROUND(PURPLE))
ANSI_STYLE(BACKGROUND(YELLOW))

Text styling

BOLD makes text appear thicker
DIM makes text appear lighter or less intense, i.e., darker

The previous two styles are mutually exclusive (according to ANSI SGR). The following may not be supported by every terminal emulator.

ITALIC
UNDERLINED
STRIKETHROUGH makes text appear crossed out
CONCEALED hides the following text, but is still selectable
BLINK_FAST makes text blink fast
BLINK_SLOW makes text blink slowly
NEGATED swaps foreground and background colors

ANSI_STYLE(BOLD)
ANSI_STYLE(BOLD, UNDERLINED)
ANSI_STYLE(FOREGROUND_BRIGHT(CYAN), BOLD, UNDERLINED)

Returns: Format string literal

Definition at line 336 of file ansi_style.h.

◆ ANSI_STYLE_BACKGROUND

#define ANSI_STYLE_BACKGROUND ( color )

Value:

_ANSI_COLOR_MODIFIER_BACKGROUND __ANSI_COLOR(color)

_ANSI_COLOR_MODIFIER_BACKGROUND

#define _ANSI_COLOR_MODIFIER_BACKGROUND

ANSI modifier to make color apply to background.

Definition ansi_style.h:116

ANSI style for foreground text color.

Definition at line 155 of file ansi_style.h.

◆ ANSI_STYLE_BACKGROUND_BRIGHT

#define ANSI_STYLE_BACKGROUND_BRIGHT ( color )

Value:

_ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND __ANSI_COLOR(color)

_ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND

#define _ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND

ANSI modifier to make color apply to background in high intensity.

Definition ansi_style.h:119

ANSI style for a brighter foreground text color.

Definition at line 165 of file ansi_style.h.

◆ ANSI_STYLE_BG

#define ANSI_STYLE_BG ( color )

Value:

ANSI_STYLE_BACKGROUND(color)

ANSI_STYLE_BACKGROUND

#define ANSI_STYLE_BACKGROUND(color)

ANSI style for foreground text color.

Definition ansi_style.h:155

Alias for ANSI_STYLE_BACKGROUND.

Warning: This feature is experimental!

Definition at line 162 of file ansi_style.h.

◆ ANSI_STYLE_BG_BRIGHT

#define ANSI_STYLE_BG_BRIGHT ( color )

Value:

ANSI_STYLE_BACKGROUND_BRIGHT(color)

ANSI_STYLE_BACKGROUND_BRIGHT

#define ANSI_STYLE_BACKGROUND_BRIGHT(color)

ANSI style for a brighter foreground text color.

Definition ansi_style.h:165

Alias for ANSI_STYLE_BACKGROUND_BRIGHT.

Warning: This feature is experimental!

Definition at line 172 of file ansi_style.h.

◆ ANSI_STYLE_BLINK_FAST

#define ANSI_STYLE_BLINK_FAST "6"

ANSI style for fast-blinking text.

Definition at line 207 of file ansi_style.h.

◆ ANSI_STYLE_BLINK_SLOW

#define ANSI_STYLE_BLINK_SLOW "5"

ANSI style for slowly blinking text.

Definition at line 205 of file ansi_style.h.

◆ ANSI_STYLE_BOLD

#define ANSI_STYLE_BOLD "1"

ANSI style for bold text.

Must not be combined with ANSI_STYLE_DIM

Definition at line 190 of file ansi_style.h.

◆ ANSI_STYLE_CONCEALED

#define ANSI_STYLE_CONCEALED "8"

ANSI style for concealed (redacted) text.

Definition at line 213 of file ansi_style.h.

◆ ANSI_STYLE_DIM

#define ANSI_STYLE_DIM "2"

ANSI style for dimmer, thinner, less prominent text.

Must not be combined with ANSI_STYLE_BOLD

Definition at line 197 of file ansi_style.h.

◆ ANSI_STYLE_FG

#define ANSI_STYLE_FG ( color )

Value:

ANSI_STYLE_FOREGROUND(color)

ANSI_STYLE_FOREGROUND

#define ANSI_STYLE_FOREGROUND(color)

ANSI style for foreground text color.

Definition ansi_style.h:135

Alias for ANSI_STYLE_FOREGROUND.

Warning: This feature is experimental!

Definition at line 142 of file ansi_style.h.

◆ ANSI_STYLE_FG_BRIGHT

#define ANSI_STYLE_FG_BRIGHT ( color )

Value:

ANSI_STYLE_FOREGROUND_BRIGHT(color)

ANSI_STYLE_FOREGROUND_BRIGHT

#define ANSI_STYLE_FOREGROUND_BRIGHT(color)

ANSI style for a brighter foreground text color.

Definition ansi_style.h:145

Alias for ANSI_STYLE_FOREGROUND_BRIGHT.

Warning: This feature is experimental!

Definition at line 152 of file ansi_style.h.

◆ ANSI_STYLE_FOREGROUND

#define ANSI_STYLE_FOREGROUND ( color )

Value:

_ANSI_COLOR_MODIFIER_FOREGROUND __ANSI_COLOR(color)

_ANSI_COLOR_MODIFIER_FOREGROUND

#define _ANSI_COLOR_MODIFIER_FOREGROUND

ANSI modifier to make color apply to foreground text.

Definition ansi_style.h:110

ANSI style for foreground text color.

Definition at line 135 of file ansi_style.h.

◆ ANSI_STYLE_FOREGROUND_BRIGHT

#define ANSI_STYLE_FOREGROUND_BRIGHT ( color )

Value:

_ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND __ANSI_COLOR(color)

_ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND

#define _ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND

ANSI modifier to make color apply to foreground text in high intensity.

Definition ansi_style.h:113

ANSI style for a brighter foreground text color.

Definition at line 145 of file ansi_style.h.

◆ ANSI_STYLE_ITALIC

#define ANSI_STYLE_ITALIC "3"

ANSI style for italic text.

Definition at line 200 of file ansi_style.h.

◆ ANSI_STYLE_NEGATED

#define ANSI_STYLE_NEGATED "7"

ANSI style swapping foreground and background color settings.

Definition at line 210 of file ansi_style.h.

◆ ANSI_STYLE_RESET

#define ANSI_STYLE_RESET _ANSI_SGR_PREFIX ANSI_STYLE_NONE _ANSI_SGR_SUFFIX

Resets text color and style applied previously back to defaults.

Append this escape sequence after any styles applied using ANSI_STYLE.

This is equivalent to ANSI_STYLE()

Definition at line 348 of file ansi_style.h.

◆ ANSI_STYLE_STRIKETHROUGH

#define ANSI_STYLE_STRIKETHROUGH "9"

ANSI style for crossed out text (strikethrough)

Definition at line 216 of file ansi_style.h.

◆ ANSI_STYLE_UNDERLINED

#define ANSI_STYLE_UNDERLINED "4"

ANSI style for underlined text.

Definition at line 202 of file ansi_style.h.

◆ ANSI_STYLED

#define ANSI_STYLED	(		text,
			... )

Value:

ANSI_STYLE(__VA_ARGS__) text ANSI_STYLE_RESET

Applies ANSI styling but only modifies given text.

Like ANSI_STYLE, but the the ANSI styling does not need to be reset after an invocation of this macro.

Warning: This feature is experimental!
Experimental API, may change in the future.

Parameters

text	Text to style
...	Variadic style arguments to apply to `text`, e.g., `FOREGROUND(RED)`, `BOLD`, `UNDERLINED`

Example:

DEBUG(ANSI_STYLED("fatal error", FG(RED), BOLD) ": programmer error!!");

DEBUG

#define DEBUG(...)

Print debug information to stdout.

Definition debug.h:121

Definition at line 367 of file ansi_style.h.

Detailed Description

Files

SGR escape sequence

Color codes

Color modifiers

Color styles

Text styles

Formatting macros

Macro Definition Documentation

◆ _ANSI_COLOR_CODE_BLACK

◆ _ANSI_COLOR_CODE_BLUE

◆ _ANSI_COLOR_CODE_CYAN

◆ _ANSI_COLOR_CODE_GREEN

◆ _ANSI_COLOR_CODE_INDEXED

◆ _ANSI_COLOR_CODE_PRIMARY

◆ _ANSI_COLOR_CODE_PURPLE

◆ _ANSI_COLOR_CODE_RED

◆ _ANSI_COLOR_CODE_RGB

◆ _ANSI_COLOR_CODE_WHITE

◆ _ANSI_COLOR_CODE_YELLOW

◆ _ANSI_COLOR_MODIFIER_BACKGROUND

◆ _ANSI_COLOR_MODIFIER_BRIGHT_BACKGROUND

◆ _ANSI_COLOR_MODIFIER_BRIGHT_FOREGROUND

◆ _ANSI_COLOR_MODIFIER_FOREGROUND

◆ _ANSI_SGR_PREFIX

◆ _ANSI_SGR_SUFFIX

◆ ANSI_STYLE

Color styling

Text styling

◆ ANSI_STYLE_BACKGROUND

◆ ANSI_STYLE_BACKGROUND_BRIGHT

◆ ANSI_STYLE_BG

◆ ANSI_STYLE_BG_BRIGHT

◆ ANSI_STYLE_BLINK_FAST

◆ ANSI_STYLE_BLINK_SLOW

◆ ANSI_STYLE_BOLD

◆ ANSI_STYLE_CONCEALED

◆ ANSI_STYLE_DIM

◆ ANSI_STYLE_FG

◆ ANSI_STYLE_FG_BRIGHT

◆ ANSI_STYLE_FOREGROUND

◆ ANSI_STYLE_FOREGROUND_BRIGHT

◆ ANSI_STYLE_ITALIC

◆ ANSI_STYLE_NEGATED

◆ ANSI_STYLE_RESET

◆ ANSI_STYLE_STRIKETHROUGH

◆ ANSI_STYLE_UNDERLINED

◆ ANSI_STYLED