kameloso.terminal.colours

A collection of functions that relate to applying ANSI effects to text.

This submodule has to do with terminal text colouring and is therefore gated behind version Colours.

Modules

defs module kameloso.terminal.colours.defs: Enum definitions of ANSI codes.
tags module kameloso.terminal.colours.tags: A collection of functions used to translate tags in messages into terminal colours.

Members

Functions

applyANSI void applyANSI(Sink sink, uint code, ANSICodeType overrideType): Applies an ANSI code to a passed output range.
applyTruecolour void applyTruecolour(Sink sink, uint r, uint g, uint b, Flag!"brightTerminal" bright, Flag!"normalise" normalise): Produces a terminal colour token for the colour passed, expressed in terms of red, green and blue, then writes it to the passed output range.
asANSI string asANSI(uint code): Returns an ANSI format sequence containing the passed code.
asTruecolour string asTruecolour(string word, uint r, uint g, uint b, Flag!"brightTerminal" bright, Flag!"normalise" normalise): Produces a terminal colour token for the colour passed, expressed in terms of red, green and blue. Convenience function to colour a piece of text without being passed an output sink to fill into.
colourByHash auto colourByHash(string word, CoreSettings settings): Shorthand function to colour a passed word by the hash of it.
colourByHash auto colourByHash(string word, Flags flags): Shorthand function to colour a passed word by the hash of it.
getColourByHash auto getColourByHash(string word, Flags flags): Hashes the passed string and picks an ANSI colour for it by modulo.
getColourByHash auto getColourByHash(string word, CoreSettings settings): Hashes the passed string and picks an ANSI colour for it by modulo.
getColourByHashImpl auto getColourByHashImpl(string word, bool brightTerminal, bool extendedColours): Hashes the passed string and picks an ANSI colour for it by modulo. Implementation function.
invert string invert(string line, string toInvert, Flag!"caseSensitive" caseSensitive): Terminal-inverts the colours of a piece of text in a string.
normaliseColours void normaliseColours(uint r, uint g, uint b): Takes a colour and, if it deems it is too dark to see on a black terminal background, makes it brighter.
normaliseColoursBright void normaliseColoursBright(uint r, uint g, uint b): Takes a colour and, if it deems it is too bright to see on a light terminal background, makes it darker.
withANSI string withANSI(string text, uint code, ANSICodeType overrideType): Applies an ANSI code to a passed string and returns it as a new one. Convenience function to colour a piece of text without being passed an output sink to fill into.

Examples

Appender!(char[]) sink;

// Output range version
sink.put("Hello ");
sink.applyANSI(TerminalForeground.red, ANSICodeType.foreground);
sink.put("world!");
sink.applyANSI(TerminalForeground.default_, ANSICodeType.foreground);

with (TerminalForeground)
{
    // Normal string-returning versions
    writeln("Hello ", red.asANSI, "world!", default_.asANSI);
    writeln("H3LL0".withANSI(red), ' ', "W0RLD!".withANSI(default_));
}

// Also accepts RGB form
sink.put(" Also");
sink.applyTruecolour(128, 128, 255);
sink.put("magic");
sink.applyANSI(TerminalForeground.default_);

with (TerminalForeground)
{
    writeln("Also ", asTruecolour(128, 128, 255), "magic", default_.asANSI);
}

immutable line = "Surrounding text kameloso surrounding text";
immutable kamelosoInverted = line.invert("kameloso");
assert(line != kamelosoInverted);

immutable nicknameTint = "nickname".getColourByHash(*kameloso.common.settings);
immutable substringTint = "substring".getColourByHash(*kameloso.common.settings);

It is used heavily in the Printer plugin, to format sections of its output in different colours, but it's generic enough to use anywhere.

The output range versions are cumbersome but necessary to minimise the number of strings generated.

kameloso.terminal.colours

Modules

Members

Functions

Examples

See Also

Meta

License

Copyright

Authors