TerminalColors

Usage

use TerminalColors;

or

import TerminalColors;

This module provides utilities for styling terminal output with colors and modifiers using ANSI escape codes.

The primary type is styledText, which can be used with various factory functions to create styled text with color and text modifiers (e.g., bold, italic, underline).

color defines various color options, including standard ANSI colors and RGB colors for both 256 color terminals and truecolor (24-bit) terminals.

The modifiers record defines a subset of widely supported ANSI text modifiers, which can be combined together.

type styledText : writeSerializable

The styledTest type contains all of the styling information for a piece of text, including the text itself.

This type should not be instantiated directly, instead prefer the various factory functions like style, red, bold, etc.

For example,

writeln(red("Hello, world!").bold().underline());
type color : writeSerializable

The color type represents a terminal color that can be applied to text.

This type should not be instantiated directly, instead prefer the various factory functions like red(), rgb256(), etc.

type modifiers : writeSerializable

The modifiers type represents various text modifiers that can be applied to styled text, such as bold, italic, underline, etc.

This type should not be instantiated directly. If you just need the modifier, use a factory function like bold() or italic().

Modifiers can be combined together like bold() + italic() or bold() + underline() to apply multiple text modifiers. You can also apply these modifiers to existing styles like red("Hello") + bold() + italic() or red("Hello").mod(bold()).mod(italic()).

proc style(text = "") : styledText

Creates a new styledText with the given text. This serves as the base for creating more complex styled text by applying colors and modifiers to it.

For example, the following are all equivalent ways to create bold, red text using style.

writeln(style().fg(red()).bold(), "Hello, world!", reset());
writeln(style("Hello, world!").fg(red()).bold());
proc styledText.fg(c: color, intense = false)

Sets the foreground color (text color) of a styledText.

For example, to create blue text:

writeln(style("Hello, world!").fg(blue()));
proc styledText.bg(c: color, intense = false)

Sets the background color of a styledText.

For example, to create text with a red background:

writeln(style("Hello, world!").bg(red()));
proc styledText.add(m: modifiers)

Adds text modifiers (e.g., bold, italic, underline) to a styledText.

For example, to create bold and underlined text the following are all equivalent:

writeln(style("Hello, world!").mod(bold() + underline()));
writeln(style("Hello, world!").mod(bold()).mod(underline()));
proc styledText.bold() : styledText

This family of functions applies specific modifiers to a styledText. These are convenience functions that call add with the appropriate modifier.

For example, the following are equivalent ways to create bold text:

writeln(style("Hello, world!").bold());
writeln(style("Hello, world!").add(bold()));
proc styledText.dim() : styledText
proc styledText.italic() : styledText
proc styledText.underline() : styledText
proc styledText.invert()
proc styledText.hidden()
proc styledText.strikethrough()
proc styledText.finish() : string

Returns the final styled string with all ANSI escape codes applied. This is called automatically when a styledText is passed to an output statement like writeln or write.

For example, the following will print bold, red text to the terminal:

writeln(red("Hello, world!").bold());

If you need to manually get the styled string (e.g., to concatenate it with other strings), you can call this method directly:

var styled = red("Hello, world!").bold().finish();
writeln("Styled message: " + styled);
proc reset() : string

Returns a string that resets the terminal styling back to the default. This only needs to be used when manually constructing ANSI escape codes, when using the styledText type and its associated factory functions it is unnecessary.

proc bold() : modifiers

This family of functions return the standalone modifiers. These modifiers can be passed to the styledText.add method or used standalone.

For example, the following are all equivalent ways to create bold text:

writeln(bold() + "Hello, world!" + reset()); // this method
writeln(style("Hello, world!").add(bold())); // this method
writeln(style("Hello, world!").bold());
writeln(bold("Hello, world!"));
proc dim() : modifiers
proc italic() : modifiers
proc underline() : modifiers
proc invert() : modifiers
proc hidden() : modifiers
proc strikethrough() : modifiers
proc bold(text: string) : styledText

This family of functions applies specific modifiers to a string by creating a styledText with the given string and applying the appropriate modifier. These are shortcuts for common use cases where you just want to apply a single modifier.

For example, the following are all equivalent ways to create bold text:

writeln(bold() + "Hello, world!" + reset());
writeln(style("Hello, world!").add(bold()));
writeln(style("Hello, world!").bold());
writeln(bold("Hello, world!")); // this method
proc dim(text: string) : styledText
proc italic(text: string) : styledText
proc underline(text: string) : styledText
proc blink(text: string) : styledText
proc invert(text: string) : styledText
proc hidden(text: string) : styledText
proc strikethrough(text: string) : styledText
proc black() : color

This family of functions return the standalone colors. These can be passed to the styledText.fg or styledText.bg methods or used standalone.

When used standalone, it is assumed that the color is a foreground color.

For example, the following are all equivalent ways to create red text:

writeln(red() + "Hello, world!" + reset()); // this method
writeln(style("Hello, world!").fg(red())); // this method
writeln(red("Hello, world!"));
proc red() : color
proc green() : color
proc yellow() : color
proc blue() : color
proc magenta() : color
proc cyan() : color
proc white() : color
proc rgb256(n: int) : color
proc rgb24(r: int, g: int, b: int) : color
proc black(text: string) : styledText

This family of functions applies specific colors to a string by creating a styledText with the given string and applying the appropriate color. These are shortcuts for common use cases where you just want to apply a single color.

These functions assume you want to set the foreground color. If you want to set the background color, you can use the styledText.bg method with the standalone color functions.

For example, the following are all equivalent ways to create red text:

writeln(red() + "Hello, world!" + reset());
writeln(style("Hello, world!").fg(red()));
writeln(red("Hello, world!")); // this method
proc red(text: string) : styledText
proc green(text: string) : styledText
proc yellow(text: string) : styledText
proc blue(text: string) : styledText
proc magenta(text: string) : styledText
proc cyan(text: string) : styledText
proc white(text: string) : styledText
proc rgb256(n: int, text: string) : styledText
proc rgb24(r: int, g: int, b: int, text: string) : styledText