#include <iosfwd>
#include <string_view>
#include <variant>
#include <cosmos/dso_export.h>
#include <cosmos/utils.hxx>

Classes
class	cosmos::term::ColorSpec
	Complete color specification for ANSI terminals. More...

struct	cosmos::term::FrontColor
	Simple type to represent an ANSI foreground color in bright or normal intensity. More...

struct	cosmos::term::BackColor
	Simple type to represent an ANSI background color in bright or normal intensity. More...

class	cosmos::term::FeatureBase
	Base class to build nested ANSI feature objects. More...

class	cosmos::term::TextEffect
	Base class for easy feature TermControl application on ostreams. More...

struct	cosmos::term::TextEffectT< effect >
	Template for definition of concrete text effect helpers. More...

struct	cosmos::term::ColoredText
	Base class for easy colored text application on ostreams. More...

struct	cosmos::term::ColoredTextT< color, intensity >
	Template for definition of concrete color text helpers. More...

struct	cosmos::term::TextOnColorT< color, intensity >
	Template for definition of concrete background color helpers. More...

Typedefs
typedef TextEffectT< TermControl::UNDERLINE_ON >	cosmos::term::Underlined
	Helper to print underlined text easily onto an ostream.

typedef TextEffectT< TermControl::BLINK_ON >	cosmos::term::Blinking
	Helper to print blinking text easily onto an ostream.

typedef TextEffectT< TermControl::INVERSE_ON >	cosmos::term::Inversed
	Helper to print blinking text easily onto an ostream.

typedef ColoredTextT< TermColor::BLACK >	cosmos::term::Black

typedef ColoredTextT< TermColor::BLACK, ColorIntensity::BRIGHT >	cosmos::term::BrightBlack

typedef TextOnColorT< TermColor::BLACK >	cosmos::term::OnBlack

typedef TextOnColorT< TermColor::BLACK, ColorIntensity::BRIGHT >	cosmos::term::OnBrightBlack

typedef ColoredTextT< TermColor::RED >	cosmos::term::Red

typedef ColoredTextT< TermColor::RED, ColorIntensity::BRIGHT >	cosmos::term::BrightRed

typedef TextOnColorT< TermColor::RED >	cosmos::term::OnRed

typedef TextOnColorT< TermColor::RED, ColorIntensity::BRIGHT >	cosmos::term::OnBrightRed

typedef ColoredTextT< TermColor::GREEN >	cosmos::term::Green

typedef ColoredTextT< TermColor::GREEN, ColorIntensity::BRIGHT >	cosmos::term::BrightGreen

typedef TextOnColorT< TermColor::GREEN >	cosmos::term::OnGreen

typedef TextOnColorT< TermColor::GREEN, ColorIntensity::BRIGHT >	cosmos::term::OnBrightGreen

typedef ColoredTextT< TermColor::YELLOW >	cosmos::term::Yellow

typedef ColoredTextT< TermColor::YELLOW, ColorIntensity::BRIGHT >	cosmos::term::BrightYellow

typedef TextOnColorT< TermColor::YELLOW >	cosmos::term::OnYellow

typedef TextOnColorT< TermColor::YELLOW, ColorIntensity::BRIGHT >	cosmos::term::OnBrightYellow

typedef ColoredTextT< TermColor::BLUE >	cosmos::term::Blue

typedef ColoredTextT< TermColor::BLUE, ColorIntensity::BRIGHT >	cosmos::term::BrightBlue

typedef TextOnColorT< TermColor::BLUE >	cosmos::term::OnBlue

typedef TextOnColorT< TermColor::BLUE, ColorIntensity::BRIGHT >	cosmos::term::OnBrightBlue

typedef ColoredTextT< TermColor::MAGENTA >	cosmos::term::Magenta

typedef ColoredTextT< TermColor::MAGENTA, ColorIntensity::BRIGHT >	cosmos::term::BrightMagenta

typedef TextOnColorT< TermColor::MAGENTA >	cosmos::term::OnMagenta

typedef TextOnColorT< TermColor::MAGENTA, ColorIntensity::BRIGHT >	cosmos::term::OnBrightMagenta

typedef ColoredTextT< TermColor::CYAN >	cosmos::term::Cyan

typedef ColoredTextT< TermColor::CYAN, ColorIntensity::BRIGHT >	cosmos::term::BrightCyan

typedef TextOnColorT< TermColor::CYAN >	cosmos::term::OnCyan

typedef TextOnColorT< TermColor::CYAN, ColorIntensity::BRIGHT >	cosmos::term::OnBrightCyan

typedef ColoredTextT< TermColor::WHITE >	cosmos::term::White

typedef ColoredTextT< TermColor::WHITE, ColorIntensity::BRIGHT >	cosmos::term::BrightWhite

typedef TextOnColorT< TermColor::WHITE >	cosmos::term::OnWhite

typedef TextOnColorT< TermColor::WHITE, ColorIntensity::BRIGHT >	cosmos::term::OnBrightWhite

Enumerations
enum class	cosmos::term::TermColor : size_t { BLACK = 0 , RED , GREEN , YELLOW , BLUE , MAGENTA , CYAN , WHITE }
	Primitive Colors for ANSI Terminals. More...

enum class	cosmos::term::ColorKind { FRONT , BACK }
	Differentiation between text (front) and background color. More...

enum class	cosmos::term::ColorIntensity { NORMAL , BRIGHT }
	Differentiation of normal and bright color intensity. More...

enum class	cosmos::term::TermControl : size_t { RESET = 0 , UNDERLINE_ON = 4 , UNDERLINE_OFF = 24 , BLINK_ON = 5 , BLINK_OFF = 25 , INVERSE_ON = 7 , INVERSE_OFF = 27 , DEFAULT_FG_COLOR = 39 , DEFAULT_BG_COLOR = 49 }
	Various feature controls for ANSI terminals. More...

enum class	cosmos::term::ANSICode : size_t
	A generic ANSI code e.g. for color indices. More...

Functions
TermControl	cosmos::term::get_off_control (const TermControl ctrl)
	Returns the matching _OFF value for an _ON value of the TermControl enum.

ANSICode	cosmos::term::get_ansi_color_code (const ColorSpec &color)
	Returns the actual ANSI escape code number for the given color specification.

void	cosmos::term::refresh_tty_detection ()
	Reevaluate whether std::cout and std::cerr belong to a TTY.

COSMOS_API std::ostream &	operator<< (std::ostream &o, const cosmos::term::ColorSpec &fc)

COSMOS_API std::ostream &	operator<< (std::ostream &o, const cosmos::term::TermControl p)

COSMOS_API std::ostream &	operator<< (std::ostream &o, const cosmos::term::FeatureBase &fb)

Detailed Description

This header provides ANSI terminal features for printing colored or otherwise marked up text. The ostream operators work only for terminal devices, see Terminal::isTTY().

This is in a separate namespace due to a lot of symbol pollution. Since a lot of types are in here a using namespace cosmos::term can help making code more compact by selectively importing this namespace.

These ostream operators will only output ANSI escape sequences if the associated std::ostream is related to std::cout or std::cerr and if the corresponding backing file descriptor FileNum::STDOUT or FileNum::STDERR are TTY devices. This is checked during library initialization time. You can explicitly cause a reevaluation of these checks by calling term::refresh_tty_detection().

You can also override the detection by setting one of the following environment variables:

COSMOS_FORCE_COLOR_ON: always output ANSI escape sequences on cout and cerr. COSMOS_FORCE_COLOR_OFF: never output ANSI escape sequences on cout and cerr.

Definition in file colors.hxx.

Typedef Documentation

◆ Black

typedef ColoredTextT<TermColor::BLACK> cosmos::term::Black

Definition at line 281 of file colors.hxx.

◆ Blinking

typedef TextEffectT<TermControl::BLINK_ON> cosmos::term::Blinking

Helper to print blinking text easily onto an ostream.

Definition at line 225 of file colors.hxx.

◆ Blue

typedef ColoredTextT<TermColor::BLUE> cosmos::term::Blue

Definition at line 301 of file colors.hxx.

◆ BrightBlack

typedef ColoredTextT<TermColor::BLACK, ColorIntensity::BRIGHT> cosmos::term::BrightBlack

Definition at line 282 of file colors.hxx.

◆ BrightBlue

typedef ColoredTextT<TermColor::BLUE, ColorIntensity::BRIGHT> cosmos::term::BrightBlue

Definition at line 302 of file colors.hxx.

◆ BrightCyan

typedef ColoredTextT<TermColor::CYAN, ColorIntensity::BRIGHT> cosmos::term::BrightCyan

Definition at line 312 of file colors.hxx.

◆ BrightGreen

typedef ColoredTextT<TermColor::GREEN, ColorIntensity::BRIGHT> cosmos::term::BrightGreen

Definition at line 292 of file colors.hxx.

◆ BrightMagenta

typedef ColoredTextT<TermColor::MAGENTA, ColorIntensity::BRIGHT> cosmos::term::BrightMagenta

Definition at line 307 of file colors.hxx.

◆ BrightRed

typedef ColoredTextT<TermColor::RED, ColorIntensity::BRIGHT> cosmos::term::BrightRed

Definition at line 287 of file colors.hxx.

◆ BrightWhite

typedef ColoredTextT<TermColor::WHITE, ColorIntensity::BRIGHT> cosmos::term::BrightWhite

Definition at line 317 of file colors.hxx.

◆ BrightYellow

typedef ColoredTextT<TermColor::YELLOW, ColorIntensity::BRIGHT> cosmos::term::BrightYellow

Definition at line 297 of file colors.hxx.

◆ Cyan

typedef ColoredTextT<TermColor::CYAN> cosmos::term::Cyan

Definition at line 311 of file colors.hxx.

◆ Green

typedef ColoredTextT<TermColor::GREEN> cosmos::term::Green

Definition at line 291 of file colors.hxx.

◆ Inversed

typedef TextEffectT<TermControl::INVERSE_ON> cosmos::term::Inversed

Helper to print blinking text easily onto an ostream.

Definition at line 227 of file colors.hxx.

◆ Magenta

typedef ColoredTextT<TermColor::MAGENTA> cosmos::term::Magenta

Definition at line 306 of file colors.hxx.

◆ OnBlack

typedef TextOnColorT<TermColor::BLACK> cosmos::term::OnBlack

Definition at line 283 of file colors.hxx.

◆ OnBlue

typedef TextOnColorT<TermColor::BLUE> cosmos::term::OnBlue

Definition at line 303 of file colors.hxx.

◆ OnBrightBlack

typedef TextOnColorT<TermColor::BLACK, ColorIntensity::BRIGHT> cosmos::term::OnBrightBlack

Definition at line 284 of file colors.hxx.

◆ OnBrightBlue

typedef TextOnColorT<TermColor::BLUE, ColorIntensity::BRIGHT> cosmos::term::OnBrightBlue

Definition at line 304 of file colors.hxx.

◆ OnBrightCyan

typedef TextOnColorT<TermColor::CYAN, ColorIntensity::BRIGHT> cosmos::term::OnBrightCyan

Definition at line 314 of file colors.hxx.

◆ OnBrightGreen

typedef TextOnColorT<TermColor::GREEN, ColorIntensity::BRIGHT> cosmos::term::OnBrightGreen

Definition at line 294 of file colors.hxx.

◆ OnBrightMagenta

typedef TextOnColorT<TermColor::MAGENTA, ColorIntensity::BRIGHT> cosmos::term::OnBrightMagenta

Definition at line 309 of file colors.hxx.

◆ OnBrightRed

typedef TextOnColorT<TermColor::RED, ColorIntensity::BRIGHT> cosmos::term::OnBrightRed

Definition at line 289 of file colors.hxx.

◆ OnBrightWhite

typedef TextOnColorT<TermColor::WHITE, ColorIntensity::BRIGHT> cosmos::term::OnBrightWhite

Definition at line 319 of file colors.hxx.

◆ OnBrightYellow

typedef TextOnColorT<TermColor::YELLOW, ColorIntensity::BRIGHT> cosmos::term::OnBrightYellow

Definition at line 299 of file colors.hxx.

◆ OnCyan

typedef TextOnColorT<TermColor::CYAN> cosmos::term::OnCyan

Definition at line 313 of file colors.hxx.

◆ OnGreen

typedef TextOnColorT<TermColor::GREEN> cosmos::term::OnGreen

Definition at line 293 of file colors.hxx.

◆ OnMagenta

typedef TextOnColorT<TermColor::MAGENTA> cosmos::term::OnMagenta

Definition at line 308 of file colors.hxx.

◆ OnRed

typedef TextOnColorT<TermColor::RED> cosmos::term::OnRed

Definition at line 288 of file colors.hxx.

◆ OnWhite

typedef TextOnColorT<TermColor::WHITE> cosmos::term::OnWhite

Definition at line 318 of file colors.hxx.

◆ OnYellow

typedef TextOnColorT<TermColor::YELLOW> cosmos::term::OnYellow

Definition at line 298 of file colors.hxx.

◆ Red

typedef ColoredTextT<TermColor::RED> cosmos::term::Red

Definition at line 286 of file colors.hxx.

◆ Underlined

typedef TextEffectT<TermControl::UNDERLINE_ON> cosmos::term::Underlined

Helper to print underlined text easily onto an ostream.

Definition at line 223 of file colors.hxx.

◆ White

typedef ColoredTextT<TermColor::WHITE> cosmos::term::White

Definition at line 316 of file colors.hxx.

◆ Yellow

typedef ColoredTextT<TermColor::YELLOW> cosmos::term::Yellow

Definition at line 296 of file colors.hxx.

Enumeration Type Documentation

◆ ANSICode

enum class cosmos::term::ANSICode : size_t

strong

A generic ANSI code e.g. for color indices.

Definition at line 126 of file colors.hxx.

126 : size_t {

127};

◆ ColorIntensity

enum class cosmos::term::ColorIntensity

strong

Differentiation of normal and bright color intensity.

Definition at line 64 of file colors.hxx.

                          {
        NORMAL,
        BRIGHT
};

◆ ColorKind

enum class cosmos::term::ColorKind

strong

Differentiation between text (front) and background color.

Definition at line 58 of file colors.hxx.

                     {
        FRONT,
        BACK
};

◆ TermColor

enum class cosmos::term::TermColor : size_t

strong

Primitive Colors for ANSI Terminals.

There are 16 different colors when taking bright variants into account. The colors can be used both for text color and background color.

Definition at line 44 of file colors.hxx.

                     : size_t {
        // the integer values denote the offset from the base ANSI escape code
        // for front/back bright/normal colors.
        BLACK = 0,
        RED,
        GREEN,
        YELLOW,
        BLUE,
        MAGENTA,
        CYAN,
        WHITE
};

◆ TermControl

enum class cosmos::term::TermControl : size_t

strong

Various feature controls for ANSI terminals.

Enumerator
RESET	Remove all attributes currently set (including colors)
UNDERLINE_ON	Underlined text.
BLINK_ON	Blinking text.
INVERSE_ON	Inverse fg/bg colors.
DEFAULT_FG_COLOR	Set default fg color.
DEFAULT_BG_COLOR	Set default bg color.

Definition at line 113 of file colors.hxx.

                       : size_t {
        RESET            = 0,  
        UNDERLINE_ON     = 4,  
        UNDERLINE_OFF    = 24,
        BLINK_ON         = 5,  
        BLINK_OFF        = 25,
        INVERSE_ON       = 7,  
        INVERSE_OFF      = 27,
        DEFAULT_FG_COLOR = 39, 
        DEFAULT_BG_COLOR = 49  
};

Function Documentation

◆ get_ansi_color_code()

ANSICode COSMOS_API cosmos::term::get_ansi_color_code ( const ColorSpec & color )

Returns the actual ANSI escape code number for the given color specification.

Definition at line 88 of file colors.cxx.

                                                     {
        size_t code = color.isFrontColor() ? 30 : 40;
        if (color.isBright())
                code += 60;
 
        return ANSICode{code + to_integral(color.getColor())};
}

◆ get_off_control()

TermControl COSMOS_API cosmos::term::get_off_control ( const TermControl ctrl )

Returns the matching _OFF value for an _ON value of the TermControl enum.

This can throw an exception on unexpected input.

Definition at line 96 of file colors.cxx.

                                                    {
        switch(ctrl) {
        case TermControl::UNDERLINE_ON: return TermControl::UNDERLINE_OFF;
        case TermControl::BLINK_ON:     return TermControl::BLINK_OFF;
        case TermControl::INVERSE_ON:   return TermControl::INVERSE_OFF;
        default: cosmos_throw (UsageError("bad value"));
                 return TermControl::RESET; /* to silence compiler warning */
        }
}

◆ operator<<() [1/3]

COSMOS_API std::ostream & operator<<	(	std::ostream &	o,
		const cosmos::term::ColorSpec &	fc )

Definition at line 134 of file colors.cxx.

                                                                     {
        if (!cosmos::term::isTTYStream(o))
                return o;
        const auto code = get_ansi_color_code(fc);
 
        return o << cosmos::term::build_ansi_command(code);
}

◆ operator<<() [2/3]

COSMOS_API std::ostream & operator<<	(	std::ostream &	o,
		const cosmos::term::FeatureBase &	fb )

Definition at line 148 of file colors.cxx.

                                                                       {
        using namespace cosmos::term;
 
        if (!cosmos::term::isTTYStream(o)) {
                if (!fb.hasNextFeature())
                        return o << fb.getText();
                else {
                        const auto features = get_features(fb);
                        return o << features.back()->getText();
                }
        }
 
        // simple case without dynamic allocation
        if (!fb.hasNextFeature()) {
                return o << build_ansi_command(fb.getOnCode()) << fb.getText() << build_ansi_command(fb.getOffCode());
        }
 
        // complex case with nested features
        std::vector<cosmos::term::ANSICode> on_codes, off_codes;
        const auto features = get_features(fb);
        for (const auto feature: features) {
                on_codes.push_back(feature->getOnCode());
                off_codes.push_back(feature->getOffCode());
        }
 
        assert (features.back()->hasText());
        return o << build_ansi_command(on_codes) << features.back()->getText() << build_ansi_command(off_codes);
}

◆ operator<<() [3/3]

COSMOS_API std::ostream & operator<<	(	std::ostream &	o,
		const cosmos::term::TermControl	p )

Definition at line 142 of file colors.cxx.

                                                                     {
        if (!cosmos::term::isTTYStream(o))
                return o;
        return o << cosmos::term::build_ansi_command(cosmos::term::ANSICode{cosmos::to_integral(p)});
}

◆ refresh_tty_detection()

COSMOS_API void cosmos::term::refresh_tty_detection ( )

Reevaluate whether std::cout and std::cerr belong to a TTY.

During libcosmos initialization time the color API checks whether std::cout and std::cerr are associated with terminal devices. If this is not the case then ANSI escape sequences are transparently disabled on these streams and only plain text is output.

Should your program reassociate the stdout or stderr streams or their backing file descriptors during program execution then you can call this function explicitly to reevaluate them. This function is by nature not fully multithreading safe if threads are using the color I/O functions in parallel while changing the stdio properties.

Definition at line 72 of file colors.cxx.

                             {
        if (proc::get_env_var("COSMOS_FORCE_COLOR_ON")) {
                stdout_is_tty = stderr_is_tty = true;
                return;
        } else if (proc::get_env_var("COSMOS_FORCE_COLOR_OFF")) {
                stdout_is_tty = stderr_is_tty = false;
                return;
        }
 
        Terminal output{FileDescriptor{FileNum::STDOUT}};
        Terminal error{FileDescriptor{FileNum::STDERR}};
 
        stdout_is_tty = output.isTTY();
        stderr_is_tty = error.isTTY();
}

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ Black

◆ Blinking

◆ Blue

◆ BrightBlack

◆ BrightBlue

◆ BrightCyan

◆ BrightGreen

◆ BrightMagenta

◆ BrightRed

◆ BrightWhite

◆ BrightYellow

◆ Cyan

◆ Green

◆ Inversed

◆ Magenta

◆ OnBlack

◆ OnBlue

◆ OnBrightBlack

◆ OnBrightBlue

◆ OnBrightCyan

◆ OnBrightGreen

◆ OnBrightMagenta

◆ OnBrightRed

◆ OnBrightWhite

◆ OnBrightYellow

◆ OnCyan

◆ OnGreen

◆ OnMagenta

◆ OnRed

◆ OnWhite

◆ OnYellow

◆ Red

◆ Underlined

◆ White

◆ Yellow

Enumeration Type Documentation

◆ ANSICode

◆ ColorIntensity

◆ ColorKind

◆ TermColor

◆ TermControl

Function Documentation

◆ get_ansi_color_code()

◆ get_off_control()

◆ operator<<() [1/3]

◆ operator<<() [2/3]

◆ operator<<() [3/3]

◆ refresh_tty_detection()