fe::term Namespace Reference

Lightweight stream-based terminal colors for diagnostics and CLI output. More...

Enumerations
enum class	Mode {   Auto ,   Never ,   Always }
	Controls whether color escape sequences are emitted. More...
enum class	FG {   Black ,   Red ,   Green ,   Yellow ,   Blue ,   Magenta ,   Cyan ,   Gray ,   Grey = Gray ,   Reset }
	Foreground colors that can be streamed into an std::ostream. More...

Functions
Mode	mode () noexcept
	Returns the current terminal color mode.
void	set_mode (Mode m) noexcept
	Overrides the current terminal color mode.
void	resolve_mode (std::ostream &os=std::cerr) noexcept
	Resolves Mode::Auto to Mode::Always or Mode::Never, depending on whether os refers to a terminal.
std::ostream &	operator<< (std::ostream &os, FG color)
	Streams the ANSI escape sequence for color when colors are enabled for os.

Detailed Description

Lightweight stream-based terminal colors for diagnostics and CLI output.

Include fe/term.h and stream a fe::term::FG value into an std::ostream:

std::cerr << fe::term::FG::Red << "error: " << fe::term::FG::Reset << "unexpected token\n";

The current behavior is controlled via fe::term::Mode and can be overridden with fe::term::set_mode. In fe::term::Mode::Auto, colors are emitted only for std::cout, std::cerr, std::clog, or streams sharing those buffers when they refer to terminals. FE also respects the common environment conventions NO_COLOR, CLICOLOR=0, and CLICOLOR_FORCE (unless it is set to 0).

Note that a std::formatter never sees the destination stream - it formats into a detached buffer. Hence, embedding a fe::term::FG value in a std::format/std::print format string resolves fe::term::Mode::Auto to "no color". If you emit colors this way, call fe::term::resolve_mode once at startup to decide fe::term::Mode::Auto up front based on a representative stream.

Enumeration Type Documentation

FG

enum class fe::term::FG

strong

Foreground colors that can be streamed into an std::ostream.

Enumerator
Black
Red
Green
Yellow
Blue
Magenta
Cyan
Gray
Grey
Reset

Definition at line 54 of file term.h.

Mode

enum class fe::term::Mode

strong

Controls whether color escape sequences are emitted.

Enumerator
Auto
Never
Always

Definition at line 47 of file term.h.

Function Documentation

mode()

Mode fe::term::mode ( )

inlinenoexcept

Returns the current terminal color mode.

Definition at line 189 of file term.h.

Referenced by resolve_mode().

operator<<()

std::ostream & fe::term::operator<< ( std::ostream & os, FG color )

inline

Streams the ANSI escape sequence for color when colors are enabled for os.

Definition at line 207 of file term.h.

resolve_mode()

void fe::term::resolve_mode ( std::ostream & os = std::cerr )

inlinenoexcept

Resolves Mode::Auto to Mode::Always or Mode::Never, depending on whether os refers to a terminal.

A std::formatter cannot see its destination stream, so FG values embedded in a std::format/std::print format string never detect a terminal in Mode::Auto. Call this once at startup to make formatted output colored as well; explicit modes are left untouched:

fe::term::resolve_mode(); // decide based on stderr
std::print(std::cerr, "{}error:{} ...", fe::term::FG::Red, fe::term::FG::Reset);

Definition at line 202 of file term.h.

References Always, Auto, mode(), Never, and set_mode().

set_mode()

void fe::term::set_mode ( Mode m )

inlinenoexcept

Overrides the current terminal color mode.

Definition at line 192 of file term.h.

Referenced by resolve_mode().