stc::colour Namespace Reference

Module for ANSI colours. More...

Namespaces
namespace	_detail

Typedefs
using	FgColour = _detail::Colouriser< _detail::FOREGROUND >
using	BgColour = _detail::Colouriser< _detail::BACKGROUND >

Enumerations
enum class	FourBitColour {   BLACK = 30 , RED = 31 , GREEN = 32 , YELLOW = 33 ,   BLUE = 34 , MAGENTA = 35 , CYAN = 36 , WHITE = 37 ,   BRIGHT_BLACK = 90 , BRIGHT_RED = 91 , BRIGHT_GREEN = 92 , BRIGHT_YELLOW = 93 ,   BRIGHT_BLUE = 94 , BRIGHT_MAGENTA = 95 , BRIGHT_CYAN = 96 , BRIGHT_WHITE = 97 }
enum class	Typography {   BOLD = 1 , FAINT = 2 , ITALIC = 3 , UNDERLINE = 4 ,   SLOW_BLINK = 5 , RESET_INTENSITY = 22 , NO_ITALIC = 23 , NO_UNDERLINE = 24 ,   NO_BLINKING = 25 }

Functions
template<Typography feature, typename CharT >
static constexpr std::basic_ostream< CharT > &	use (std::basic_ostream< CharT > &stream)
template<bool val = true, typename CharT >
static constexpr std::basic_ostream< CharT > &	force (std::basic_ostream< CharT > &stream)
template<typename CharT >
static constexpr std::basic_ostream< CharT > &	reset (std::basic_ostream< CharT > &stream)
template<FourBitColour Colour, typename CharT >
static constexpr std::basic_ostream< CharT > &	fg (std::basic_ostream< CharT > &stream)
template<uint8_t r, uint8_t g, uint8_t b, typename CharT >
static constexpr std::basic_ostream< CharT > &	fg (std::basic_ostream< CharT > &stream)
template<FourBitColour Colour, typename CharT >
static constexpr std::basic_ostream< CharT > &	bg (std::basic_ostream< CharT > &stream)
template<uint8_t r, uint8_t g, uint8_t b, typename CharT >
static constexpr std::basic_ostream< CharT > &	bg (std::basic_ostream< CharT > &stream)

Detailed Description

Module for ANSI colours.

Interfaces with std::ostreams to print colour and some other ANSI codes.

Example use:

// 4 bit
std::cout << stc::colour::fg<stc::colour::FourBitColour::RED> << "Whatever" << stc::colour::reset << std::endl;
// 8 bit
std::cout << stc::colour::fg<240> << "Whatever" << stc::colour::reset << std::endl;
// 24 bit
std::cout << stc::colour::fg<240, 0, 240> << "Whatever" << stc::colour::reset << std::endl;

fg and bg have the exact same interface, but change foreground and background colours respectively. In addition to colour, stc::colour::use exists, which takes an stc::colour::Typography.

Like typography, 8 bit colours are hard-coded in stc::colour::FourBitColour.

General usability note

Though very outside the scope of this module, do be aware of the usability of the thing you make when you involve colour. Unless you go full TUI and control the background, the user can and will have themes that may not work with the colours you use. Particularly if you hard-code black or white, you run the risk of picking a colour that corresponds to the user's background colour, making your CLI app unusable.

None of the colour types guarantee that your CLI app will be legible on all themes, but you do minimise the risk significantly by sticking to just a few colours. If you do anything major with colour, you'll probably want to offer the user a way to change the colours at an app level. Again, out of scope for the module, but this is not discussed nearly often enough, so I might as well mention it.

Typedef Documentation

BgColour

using stc::colour::BgColour = typedef _detail::Colouriser<_detail::BACKGROUND>

FgColour

using stc::colour::FgColour = typedef _detail::Colouriser<_detail::FOREGROUND>

Enumeration Type Documentation

FourBitColour

enum class stc::colour::FourBitColour

strong

Special values used for four bit colours. This is a standalone enum because both 8 and 24 bit colours use an entire range (0-255 and 3x 0-255 respectively), whereas 4 bit colours are contrived bullshit.

The underlying ANSI colour format for 4 bit colours also differentiates foreground and background by the raw value. Black foreground is 30, while black background is 40. Bright black foreground is 90, bright black background is 100. Letting you, the end user, keep track of all these values fucking sucks, so an enum is better.

Also, it's just 16 values to hardcode, with background just being these values + 10, with any value other than these specific colour values doing all kinds of other shit. Passing 38 by accident invokes the start of the 8 and 24 bit colour modes (which is 38;5;n and 38;2;r;g;b respectively).

See also

https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit

Enumerator
BLACK
RED
GREEN
YELLOW
BLUE
MAGENTA
CYAN
WHITE
BRIGHT_BLACK
BRIGHT_RED
BRIGHT_GREEN
BRIGHT_YELLOW
BRIGHT_BLUE
BRIGHT_MAGENTA
BRIGHT_CYAN
BRIGHT_WHITE

Typography

enum class stc::colour::Typography

strong

Represents typographic elements. This set is kept to a minimal mostly universally supported set of codes. This cuts out many technically supported codes due to feature support, and this interface aims to make it more clear what is and isn't supported.

Note that RESET is not included even though it is supported, because it has a standalone function for naming and brevity purposes.

See also

https://en.wikipedia.org/wiki/ANSI_escape_code#Select_Graphic_Rendition_parameters

Enumerator
BOLD
FAINT
ITALIC
UNDERLINE
SLOW_BLINK
RESET_INTENSITY	Resets BOLD and FAINT
NO_ITALIC
NO_UNDERLINE
NO_BLINKING

Function Documentation

bg() [1/2]

template<FourBitColour Colour, typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::bg ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Foreground colour for 4 bit colours.

See also

stc::colour::FourBitColour

https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit

Foreground colour for 8 bit colours.

Note that unlike four bit colours, 8 bit colours use a full uint8_t (from 0 to 255), so the values themselves are not named in an enum.

See also

https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit

bg() [2/2]

template<uint8_t r, uint8_t g, uint8_t b, typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::bg ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Foreground colour for 24 bit colours.

Takes three template arguments corresponding to the red, green, and blue respectively, and works identically to standard RGB colours.

Note that while the underlying ANSI guarantees the colour you provide is used, there's no guarantee it'll render visibly everywhere. Remember that some people use light mode or theme variants that may not work with the colour you've picked. You need to be extra aware of theming when using this function.

See also

https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit

fg() [1/2]

template<FourBitColour Colour, typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::fg ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Foreground colour for 4 bit colours.

See also

stc::colour::FourBitColour

https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit

Foreground colour for 8 bit colours.

Note that unlike four bit colours, 8 bit colours use a full uint8_t (from 0 to 255), so the values themselves are not named in an enum.

See also

https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit

fg() [2/2]

template<uint8_t r, uint8_t g, uint8_t b, typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::fg ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Foreground colour for 24 bit colours.

Takes three template arguments corresponding to the red, green, and blue respectively, and works identically to standard RGB colours.

Note that while the underlying ANSI guarantees the colour you provide is used, there's no guarantee it'll render visibly everywhere. Remember that some people use light mode or theme variants that may not work with the colour you've picked. You need to be extra aware of theming when using this function.

See also

https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit

force()

template<bool val = true, typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::force ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Can be used to force colouring to happen. By default, colouring is only applied if the stream is a TTY. If it isn't, colours are disabled. This means if stdout/stderr is redirected, or if you write to a stringstream, no colours are written. You can override this here, by using

ss << stc::colour::force
    << // commands

If you force it, but then want to set it back into default mode, supply stc::colour::force<false> instead.

reset()

template<typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::reset ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Prints the reset ANSI code, clearing all active effects.

use()

template<Typography feature, typename CharT >

static constexpr std::basic_ostream< CharT > & stc::colour::use ( std::basic_ostream< CharT > &  stream )

staticconstexpr

Used to enable typography features. Only some typography features are supported, as described in the Typography struct.