Terminal

Terminal detection, coloring policy, and ANSI styling utilities. More...

Enumerations
enum class	sourcemeta::core::TerminalStream : std::uint8_t { TerminalStream::Stdin = 0 , TerminalStream::Stdout = 1 , TerminalStream::Stderr = 2 }
enum class	sourcemeta::core::TerminalColorPolicy : std::uint8_t { TerminalColorPolicy::WhenInteractive , TerminalColorPolicy::Disabled , TerminalColorPolicy::Always }
enum class	sourcemeta::core::TerminalStyle : std::uint8_t {   TerminalStyle::None = 0 , TerminalStyle::Bold = 1 << 0 , TerminalStyle::Red = 1 << 1 , TerminalStyle::Green = 1 << 2 ,   TerminalStyle::Yellow = 1 << 3 , TerminalStyle::Blue = 1 << 4 , TerminalStyle::Cyan = 1 << 5 }

Functions
constexpr auto	sourcemeta::core::terminal_style_is_valid (TerminalStyle style) noexcept -> bool
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_is_interactive (TerminalStream stream) noexcept -> bool
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_is_interactive (int file_descriptor) noexcept -> bool
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_set_color_policy (TerminalColorPolicy policy) noexcept -> void
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_set_color_policy (TerminalStream stream, TerminalColorPolicy policy) noexcept -> void
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_reset_color_policy () noexcept -> void
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_reset_color_policy (TerminalStream stream) noexcept -> void
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_color_policy (TerminalStream stream=TerminalStream::Stdout) noexcept -> TerminalColorPolicy
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_color_enabled (TerminalStream stream) noexcept -> bool
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_sgr_sequence (TerminalStyle style) noexcept -> std::string_view
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_sgr_reset () noexcept -> std::string_view
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_paint (std::string_view text, TerminalStyle style, bool enabled=true) -> std::string
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_paint (TerminalStream stream, std::string_view text, TerminalStyle style) -> std::string
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_paint (std::ostream &output, std::string_view text, TerminalStyle style, bool enabled=true) -> std::ostream &
SOURCEMETA_CORE_TERMINAL_EXPORT auto	sourcemeta::core::terminal_paint (std::ostream &output, TerminalStream stream, std::string_view text, TerminalStyle style) -> std::ostream &

Detailed Description

Terminal detection, coloring policy, and ANSI styling utilities.

This functionality is included as follows:

#include <sourcemeta/core/terminal.h>

Enumeration Type Documentation

TerminalColorPolicy

enum class sourcemeta::core::TerminalColorPolicy : std::uint8_t

strong

Color policy governing ANSI styling output.

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
sourcemeta::core::terminal_set_color_policy(
    sourcemeta::core::TerminalColorPolicy::Disabled);
assert(!sourcemeta::core::terminal_color_enabled(
    sourcemeta::core::TerminalStream::Stdout));

Enumerator
WhenInteractive	Color is applied when the destination stream is connected to an interactive terminal device. See also https://pubs.opengroup.org/onlinepubs/9699919799/functions/isatty.html
Disabled	Styling is unconditionally suppressed.
Always	Styling is unconditionally enabled regardless of destination interactivity.

TerminalStream

enum class sourcemeta::core::TerminalStream : std::uint8_t

strong

Standard I/O streams defined by POSIX.1-2017 (<unistd.h>).

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
const auto stream{sourcemeta::core::TerminalStream::Stdout};
assert(static_cast<int>(stream) == 1);

See also

https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/unistd.h.html

Enumerator
Stdin	Standard input stream (POSIX.1-2017 STDIN_FILENO, 0). See also https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/unistd.h.html
Stdout	Standard output stream (POSIX.1-2017 STDOUT_FILENO, 1). See also https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/unistd.h.html
Stderr	Standard error stream (POSIX.1-2017 STDERR_FILENO, 2). See also https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/unistd.h.html

TerminalStyle

enum class sourcemeta::core::TerminalStyle : std::uint8_t

strong

Text styles and foreground colors defined by ECMA-48 (5th Edition, 1991), Section 8.3.117 "SGR - SELECT GRAPHIC RENDITION" (also standardized as ISO/IEC 6429).

Bitwise operators allow combining TerminalStyle::Bold with a foreground color (for example TerminalStyle::Bold | TerminalStyle::Red). Only one foreground color may be active at a time. If multiple foreground colors are combined, the first matching color in declaration order (Red > Green > Yellow > Blue > Cyan) takes precedence.

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
const auto style{sourcemeta::core::TerminalStyle::Bold |
                 sourcemeta::core::TerminalStyle::Green};
assert(sourcemeta::core::terminal_style_is_valid(style));

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

Enumerator
None	Normal display / no style (plain text, ECMA-48 SGR parameter 0).
Bold	Bold or increased intensity (ECMA-48 SGR parameter 1).
Red	Red foreground color (ECMA-48 SGR parameter 31).
Green	Green foreground color (ECMA-48 SGR parameter 32).
Yellow	Yellow foreground color (ECMA-48 SGR parameter 33).
Blue	Blue foreground color (ECMA-48 SGR parameter 34).
Cyan	Cyan foreground color (ECMA-48 SGR parameter 36).

Function Documentation

terminal_color_enabled()

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_color_enabled ( TerminalStream stream ) -> bool

noexcept

Determine whether styling is enabled for the specified stream.

For example:

#include <sourcemeta/core/terminal.h>
 
const bool enabled{sourcemeta::core::terminal_color_enabled(
    sourcemeta::core::TerminalStream::Stdout)};

terminal_color_policy()

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_color_policy ( TerminalStream stream = TerminalStream::Stdout ) -> TerminalColorPolicy

noexcept

Retrieve the current color policy for the specified stream.

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
const auto policy{sourcemeta::core::terminal_color_policy()};
assert(policy == sourcemeta::core::TerminalColorPolicy::WhenInteractive ||
       policy == sourcemeta::core::TerminalColorPolicy::Disabled ||
       policy == sourcemeta::core::TerminalColorPolicy::Always);

terminal_is_interactive() [1/2]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_is_interactive ( int file_descriptor ) -> bool

noexcept

Check whether the specified file descriptor is connected to an interactive terminal, according to POSIX.1-2017 isatty().

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
assert(!sourcemeta::core::terminal_is_interactive(-1));

See also

https://pubs.opengroup.org/onlinepubs/9699919799/functions/isatty.html

terminal_is_interactive() [2/2]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_is_interactive ( TerminalStream stream ) -> bool

noexcept

Check whether the specified stream is connected to an interactive terminal, according to POSIX.1-2017 isatty().

For example:

#include <sourcemeta/core/terminal.h>
 
const bool is_term{sourcemeta::core::terminal_is_interactive(
    sourcemeta::core::TerminalStream::Stdout)};

See also

https://pubs.opengroup.org/onlinepubs/9699919799/functions/isatty.html

terminal_paint() [1/4]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_paint	(	std::ostream &	output,
		std::string_view	text,
		TerminalStyle	style,
		bool	enabled = true ) -> std::ostream &

Stream styled text with ECMA-48 Select Graphic Rendition (SGR) control sequences to an output stream without heap allocation.

For example:

#include <sourcemeta/core/terminal.h>
#include <iostream>
 
sourcemeta::core::terminal_paint(
    std::cout, "Success", sourcemeta::core::TerminalStyle::Green, true);

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

terminal_paint() [2/4]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_paint	(	std::ostream &	output,
		TerminalStream	stream,
		std::string_view	text,
		TerminalStyle	style ) -> std::ostream &

Stream styled text with ECMA-48 Select Graphic Rendition (SGR) control sequences to an output stream for the given stream destination.

For example:

#include <sourcemeta/core/terminal.h>
#include <iostream>
 
sourcemeta::core::terminal_paint(
    std::cerr, sourcemeta::core::TerminalStream::Stderr, "Fatal",
    sourcemeta::core::TerminalStyle::Red);

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

terminal_paint() [3/4]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_paint	(	std::string_view	text,
		TerminalStyle	style,
		bool	enabled = true ) -> std::string

Wrap text in ECMA-48 Select Graphic Rendition (SGR) control sequences for the given style if enabled is true.

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
const std::string text{sourcemeta::core::terminal_paint(
    "Alert", sourcemeta::core::TerminalStyle::Red, true)};
assert(text == "\033[31mAlert\033[0m");

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

terminal_paint() [4/4]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_paint	(	TerminalStream	stream,
		std::string_view	text,
		TerminalStyle	style ) -> std::string

Wrap text in ECMA-48 Select Graphic Rendition (SGR) control sequences for the given stream destination.

For example:

#include <sourcemeta/core/terminal.h>
 
const std::string text{sourcemeta::core::terminal_paint(
    sourcemeta::core::TerminalStream::Stderr, "Error",
    sourcemeta::core::TerminalStyle::Red)};

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

terminal_reset_color_policy() [1/2]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_reset_color_policy ( ) -> void

noexcept

Reset the color policy across all streams to default (TerminalColorPolicy::WhenInteractive).

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
sourcemeta::core::terminal_set_color_policy(
    sourcemeta::core::TerminalColorPolicy::Disabled);
sourcemeta::core::terminal_reset_color_policy();
assert(sourcemeta::core::terminal_color_policy() ==
       sourcemeta::core::TerminalColorPolicy::WhenInteractive);

terminal_reset_color_policy() [2/2]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_reset_color_policy ( TerminalStream stream ) -> void

noexcept

Reset the color policy for a specific stream to default (TerminalColorPolicy::WhenInteractive).

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
sourcemeta::core::terminal_set_color_policy(
    sourcemeta::core::TerminalStream::Stderr,
    sourcemeta::core::TerminalColorPolicy::Disabled);
sourcemeta::core::terminal_reset_color_policy(
    sourcemeta::core::TerminalStream::Stderr);
assert(sourcemeta::core::terminal_color_policy(
           sourcemeta::core::TerminalStream::Stderr) ==
       sourcemeta::core::TerminalColorPolicy::WhenInteractive);

terminal_set_color_policy() [1/2]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_set_color_policy ( TerminalColorPolicy policy ) -> void

noexcept

Set the global color policy across all streams.

For example:

#include <sourcemeta/core/terminal.h>
 
sourcemeta::core::terminal_set_color_policy(
    sourcemeta::core::TerminalColorPolicy::Disabled);

terminal_set_color_policy() [2/2]

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_set_color_policy ( TerminalStream stream, TerminalColorPolicy policy ) -> void

noexcept

Set the color policy for a specific stream.

For example:

#include <sourcemeta/core/terminal.h>
 
sourcemeta::core::terminal_set_color_policy(
    sourcemeta::core::TerminalStream::Stderr,
    sourcemeta::core::TerminalColorPolicy::Disabled);

terminal_sgr_reset()

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_sgr_reset ( ) -> std::string_view

noexcept

Return the ECMA-48 Select Graphic Rendition (SGR) reset control sequence ("\033[0m").

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
assert(sourcemeta::core::terminal_sgr_reset() == "\033[0m");

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

terminal_sgr_sequence()

SOURCEMETA_CORE_TERMINAL_EXPORT auto sourcemeta::core::terminal_sgr_sequence ( TerminalStyle style ) -> std::string_view

noexcept

Return the ECMA-48 Select Graphic Rendition (SGR) control sequence for the given style.

Returns an empty string view if style is TerminalStyle::None.

For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
const auto seq{sourcemeta::core::terminal_sgr_sequence(
    sourcemeta::core::TerminalStyle::Bold)};
assert(seq == "\033[1m");

See also

https://ecma-international.org/publications-and-standards/standards/ecma-48/

terminal_style_is_valid()

auto sourcemeta::core::terminal_style_is_valid ( TerminalStyle style ) -> bool

nodiscardconstexprnoexcept

Check whether a terminal style configuration is valid and canonical.

A style is valid if it contains only defined bit flags and at most one foreground color. For example:

#include <sourcemeta/core/terminal.h>
#include <cassert>
 
assert(sourcemeta::core::terminal_style_is_valid(
    sourcemeta::core::TerminalStyle::Bold |
    sourcemeta::core::TerminalStyle::Red));
assert(!sourcemeta::core::terminal_style_is_valid(
    sourcemeta::core::TerminalStyle::Red |
    sourcemeta::core::TerminalStyle::Green));