fe::term Namespace Reference

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

Typedefs
using	ScopedMode = Restore<Mode, &mode, &set_mode>
	Overrides the color mode for the duration of the scope.

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.
bool	use_color (std::ostream &os) noexcept
	Whether color escape sequences are emitted for os right now.
std::optional< size_t >	width (std::ostream &os) noexcept
	Number of columns of the terminal os refers to.
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.

Use fe::term::use_color to branch on whether color will actually be emitted, e.g. to keep a plain-text fallback in sync with the colored rendering.

Typedef Documentation

ScopedMode

using fe::term::ScopedMode = Restore<Mode, &mode, &set_mode>

Overrides the color mode for the duration of the scope.

Warning

The mode is global, so this affects every stream - and every thread - while it is alive.

Definition at line 226 of file term.h.

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 60 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 53 of file term.h.

Function Documentation

mode()

Mode fe::term::mode ( )

inlinenoexcept

Returns the current terminal color mode.

Definition at line 184 of file term.h.

References mode().

Referenced by mode(), resolve_mode(), and use_color().

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 241 of file term.h.

References operator<<(), and use_color().

Referenced by operator<<().

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 236 of file term.h.

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

Referenced by resolve_mode().

set_mode()

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

inlinenoexcept

Overrides the current terminal color mode.

Definition at line 222 of file term.h.

References set_mode().

Referenced by resolve_mode(), and set_mode().

use_color()

bool fe::term::use_color ( std::ostream & os )

inlinenoexcept

Whether color escape sequences are emitted for os right now.

In Mode::Auto this is decided by whether os refers to a terminal, so a detached buffer (anything a std::formatter writes into) yields false; see resolve_mode. Use this to keep a plain-text fallback in sync with what operator<<(std::ostream&, FG) will emit, e.g. to spell out a marker only when it cannot be conveyed by color.

Definition at line 191 of file term.h.

References Always, Auto, mode(), Never, fe::unreachable(), and use_color().

Referenced by operator<<(), fe::Error::str(), and use_color().

width()

std::optional< size_t > fe::term::width ( std::ostream & os )

inlinenoexcept

Number of columns of the terminal os refers to.

Unlike use_color, this ignores Mode and always asks the actual stream.

Returns

std::nullopt if os is not a terminal or its size cannot be determined.

Definition at line 205 of file term.h.

References width().

Referenced by width().