This module provides implementation of the basic colored text abstractions. Text is represented using sequence of colored unicode runes.

The module is designed to be easily reusable for quick formatting - most basic usage is "text" + fgRed - merge text with given formatting style.

In addition to the string construction basic modification options are added - indent, align left/right/center, split by lines, add indentation. This module is designed to /generate/ formatted text, so no find/replace and other search-based procedures are added. It is assumed that all necessary formatting is done beforehand.

..note:: If you implement string formatting functions that return: ColText (which is a recommended approach, since regular string embedded ansi escapes does not compose properly) you need to export stringification operator as well - export $, otherwise echo treeRepr() and similar operations become a little more annoying to use.

Imports

terminal, unicode, sequtils, strformat, strutils

Types

ColModifier = ForegroundColor | BackgroundColor | TermColorFg | TermColorBg | set[Style] | Style | ColStyle: Typeclass, contains all types that can be used for text styling Source Edit
ColRune = object rune*: Rune style*: ColStyle: Single unicode rune with applied coloring Source Edit
ColRuneGrid = seq[ColRuneLine]: Source Edit
ColRuneLine = seq[ColRune]: Source Edit
ColStyle = object fg*: TermColorFg ## Foreground color bg*: TermColorBg ## Background style*: set[Style] ## Other styling options (italic, underline, dim, ## bright etc.): Styling options Source Edit
ColText = object runes*: seq[ColRune]: Sequence of colored unicode runes Source Edit
TermColorBg = distinct uint8: Terminal background color. 16-colors are represented as the first 16 values (with 0 being the default), everything higher maps to 256 colors Source Edit
TermColorFg = distinct uint8: Terminal foreground color. Mapping is identical to the background version Source Edit

Procs

func `$`(colored: ColRune): string {....raises: [], tags: [].}

Convert to string with ansi escape sequences. To disable coloring use toString procedure instead. Source Edit

func `$`(colr: ColRuneGrid): string {....raises: [], tags: [].}

Convert to multiline string with ansi escape sequences. To disable coloring use toString procedure instead. Source Edit

func `$`(colr: ColRuneLine): string {....raises: [], tags: [].}

Convert to string with ansi escape sequences. To disable coloring use toString procedure instead. Source Edit

func `$`(text: ColText): string {....raises: [], tags: [].}

Convert to string with ansi escape sequences. To disable coloring use toString procedure instead. Source Edit

func `%`(format: string; interpolate: openArray[ColText]): ColText {.
    ...raises: [ValueError], tags: [].}

Shorthand for colored text interpolation Source Edit

func `&`(t1: sink ColText; t2: ColText): ColText {....raises: [], tags: [].}

Concatenate two colored text blocks Source Edit

func `&`(t1: sink ColText; t2: string): ColText {....raises: [], tags: [].}

Concatenate colored text and regular string (with default style) Source Edit

func `&`(t1: string; t2: ColText): ColText {....raises: [], tags: [].}

Concatenate colored text and regular string (with default style) Source Edit

func `+=`(s1: var ColStyle; s2: ColStyle) {....raises: [], tags: [].}

Merge two styling optons, overriding target if the source has non-default value for background or foreground colors Source Edit

func `+`(a: ColModifier; b: distinct ColModifier): ColStyle

Merge two color modifiers and generate color style (fgRed+{styleUnderline}) Source Edit

func `+`(ch: char; style: ColModifier): ColRune

Convert character to colored rune with given style Source Edit

func `+`(r: Rune; style: ColModifier): ColRune

Convert rune to colored one with given style modifier Source Edit

func `+`(s1, s2: ColStyle): ColStyle {....raises: [], tags: [].}

Merge two styles. Second one overrides colors if they are non-default. Source Edit

func `+`(text: sink ColText; style: ColModifier): ColText

Apply styling options to colored text Source Edit

func `+`(text: string; style: ColModifier): ColText

Convert text colored one using given style Source Edit

func `==`(a, b: TermColorBg | TermColorFg): bool

Color equality comparison Source Edit

func `==`(f1: TermColorBg; f2: BackgroundColor): bool {....raises: [], tags: [].}

Compare for equality with std/terminal color Source Edit

func `==`(f1: TermColorFg; f2: ForegroundColor): bool {....raises: [], tags: [].}

Compare for equality with std/terminal color Source Edit

func `==`(rune: ColRune; ch: char): bool {....raises: [], tags: [].}

Compare rune for equality with regular character Source Edit

func `==`(s1, s2: ColStyle): bool {....raises: [], tags: [].}

Compare styles for equality - foreground, background and style Source Edit

func `[]=`(buf: var ColRuneGrid; row, col: int; ch: char) {....raises: [], tags: [].}

Assign single character to the colored rune grid, using default style Source Edit

func `[]=`(buf: var ColRuneGrid; row, col: int; str: ColText) {....raises: [],
    tags: [].}

Assign colored text at specific point on the colored grid. Multiline text is assigned propery Source Edit

func `[]=`[R1, R2: openArray[int] | Slice[int] | int](buf: var ColRuneGrid;
    rowIdx: R1; colIdx: R2; ch: ColRune; fill: ColRune = clr(' '))

Assign rune to specific part of the colored rune grid, expanding it as needed to fill out missing parts. This procs provide a simplified resizeable 'canvas' that allows to draw colored text on it, without having to constantly check for out-of-bounds errors.

fill - colored rune used to fill in missing parts

Source Edit

func `|<<`(s: sink ColText; l: int): ColText {....raises: [], tags: [].}

Shorthand for left align of the colored text. Since library is mostly used for final message formatting it is a very common operation and it was implemented as an operator as well. Source Edit

func `|>>`(s: sink ColText; l: int): ColText {....raises: [], tags: [].}

Shorthand of the right align of the colored text. Source Edit

func add(colored: var ColText; ch: string | char) {.inline.}

Add string or character with default style to colored text, Source Edit

func add(colored: var ColText; other: ColRuneLine) {....raises: [], tags: [].}

Add colored rune line (sequence of runes) to colored text Source Edit

func add(colored: var ColText; other: ColText) {....raises: [], tags: [].}

Add one colored text block to another Source Edit

func add(colored: var ColText; rune: ColRune) {.inline, ...raises: [], tags: [].}

Add colored rune to the text Source Edit

func add(text: var ColText; rune: ColRune | seq[ColRune])

Append one or more colored runes to the text Source Edit

func addf(text: var ColText; formatstr: string;
          colored: varargs[ColText, toColText]) {....raises: [ValueError], tags: [].}

Interpolate formatstr using values from colored and add results to the text.

Iterpolation syntax is identical to the std/strutils.addf except $name is currently not supported, so only positional interpolation is available.

Source Edit

func addIndent(res: var ColText; level: int; sep: int = 2;
               prefix: ColRune = clr(' ')) {....raises: [], tags: [].}

Add indentation prefix to the colored text. Source Edit

func alignCenter(text: sink ColText; length: int; padding: ColRune = clr(' ')): ColText {.
    ...raises: [], tags: [].}

Center colored text, using padding rune to fill in missing elements Source Edit

func alignLeft(text: sink ColText; length: int; padding: ColRune = clr(' ')): ColText {.
    ...raises: [], tags: [].}

Align colored text left, using padding rune to fill in missing elements Source Edit

func alignRight(text: ColText; length: int; padding: ColRune = clr(' ')): ColText {.
    ...raises: [], tags: [].}

Align colored text right, using padding rune to fill in missing elements Source Edit

func clr(ch: char): ColRune {....raises: [], tags: [].}

Construct colored rune with default styling Source Edit

func clt(ch: char): ColText {....raises: [], tags: [].}

Shorthand to construct colored text with single character Source Edit

func clt(str: string): ColText {....raises: [], tags: [].}

Shorthand to construct colored text string with default value (clt"default") Source Edit

func colStyle(bg: BackgroundColor): ColStyle {....raises: [], tags: [].}

Convert to style with only background option set Source Edit

func colStyle(bg: TermColorBg): ColStyle {....raises: [], tags: [].}

Convert to style with only background color set Source Edit

func colStyle(fg: ForegroundColor): ColStyle {....raises: [], tags: [].}

Convert to style with only foreground option set Source Edit

func colStyle(fg: TermColorFg): ColStyle {....raises: [], tags: [].}

Convert to style with only foreground color set Source Edit

func colStyle(style: ColStyle): ColStyle {....raises: [], tags: [].}

Passthrough proc, used to simplify mapping of the ColModifier typeclass to the ColStyle object. Source Edit

func colStyle(style: set[Style]): ColStyle {....raises: [], tags: [].}

Convert to style with given set of styling options Source Edit

func colStyle(style: Style): ColStyle {....raises: [], tags: [].}

Convert to style with single styling option set Source Edit

func contains(ps: ColStyle; s: Style): bool {....raises: [], tags: [].}

Check if coloring contains specific style option Source Edit

func default(rune: typedesc[ColRune]): ColRune

Default value of the colored rune Source Edit

func default(style: typedesc[ColStyle]): ColStyle

Default value of the color style Source Edit

func grid(text: ColText): ColRuneGrid {....raises: [], tags: [].}

Convert colored text to grid Source Edit

func hasNewline(text: ColText): bool {....raises: [], tags: [].}

Check if colored text has any newlines Source Edit

func hasOnlyTailNewline(text: ColText): bool {....raises: [], tags: [].}

Check if colored text has only trailing newlines and no in-body ones Source Edit

proc indent(str: ColText; count: int; indentAfter: int = -1;
            indent: ColText = clt(" "); prefix: ColText = clt("")): ColText {.
    ...raises: [], tags: [].}

Indent colored text lines by count repetitions of the indent text. Add prefix before each line.

indentAfter - first line to start applying indentation after (defaults to -1, so indentation is applied to the whole text). Can be used to allow [header, line, line] text to be easily processed

Source Edit

func initColStyle(fg: ForegroundColor = fgDefault;
                  bg: BackgroundColor = bgDefault; style: set[Style] = {}): ColStyle {.
    ...raises: [], tags: [].}

Initialize color style with given options Source Edit

func isDefault(col: TermColorFg | TermColorBg): bool

Check if foreground or background color have default value Source Edit

func isNewline(rune: ColRune): bool {....raises: [], tags: [].}

Check if rune is a newline rune Source Edit

func join(text: seq[ColText]; sep: ColText): ColText {....raises: [], tags: [].}

Source Edit

func len(text: ColText): int {....raises: [], tags: [].}

Number of runes in text Source Edit

func lispRepr(rune: ColRune): string {....raises: [ValueError], tags: [].}

Source Edit

func lispRepr(rune: ColText): string {....raises: [ValueError], tags: [].}

Source Edit

func newline(text: var ColText) {....raises: [], tags: [].}

Append newline to the colored text Source Edit

func setStyle(text: var ColText; new: ColStyle; override: bool = true) {.
    ...raises: [], tags: [].}

Set style for all runes in text, optionally overriding non-defaulted values (or resetting them completely) Source Edit

func stripLines(text: ColText; leading: bool = false; trails: bool = true;
                chars: set[char] = {' '}): ColText {....raises: [], tags: [].}

Strip character from each line in text Source Edit

func termBg(gray: range[0 .. 23]): TermColorBg {....raises: [], tags: [].}

Create 256-color with given grey background value (from 0 to 23, for total 24 shades). Source Edit

func termBg(r, g, b: range[0 .. 5]): TermColorBg {....raises: [], tags: [].}

256-color for background. Maps to 216-element color cube. Source Edit

func termColor(bg: BackgroundColor): TermColorBg {....raises: [], tags: [].}

Convert std/terminal.BackgroundColor to terminal background color Source Edit

func termColor(bg: ForegroundColor): TermColorFg {....raises: [], tags: [].}

Convert std/terminal.ForegroundColor to terminal foreground color Source Edit

func termFg(gray: range[0 .. 23]): TermColorFg {....raises: [], tags: [].}

Grey foreground value Source Edit

func termFg(r, g, b: range[0 .. 5]): TermColorFg {....raises: [], tags: [].}

Create 256-terminal color with given red, green and blue coloring. Colors are mapped to 216-element color cube. Source Edit

func toColRune(rune: Rune; style: ColStyle): ColRune {....raises: [], tags: [].}

Convert colered rune to styled one with style Source Edit

func toColText(rune: ColRune): ColText {....raises: [], tags: [].}

Convert single rune to colored text Source Edit

func toColText(text: ColText): ColText {....raises: [], tags: [].}

Passthrough implementation of converter to colored text Source Edit

func toColText(text: string; style: ColStyle = default(ColStyle)): ColText {.
    ...raises: [], tags: [].}

Convert text colored one using given style Source Edit

func toLower(text: sink ColText): ColText {....raises: [], tags: [].}

Convert colored text to lowercase Source Edit

func toString(rune: ColRune; color: bool = true): string {....raises: [], tags: [].}

Convert colored rune to regular string, with ansi escape sequences. color controls whether styling is going to be applied or not. Source Edit

func toString(runes: seq[ColRune]; color: bool = true): string {....raises: [],
    tags: [].}

Convert sequence of colored runes to the string, with ansi escape sequences in. color controls whether styling is going to be applied or not. Source Edit

func toString(text: ColText; color: bool = true): string {....raises: [], tags: [].}

Convert colored text to string with ansi escape sequences Source Edit

func toUpper(text: sink ColText): ColText {....raises: [], tags: [].}

Convert colored text to uppercase Source Edit

func uc(s: static[string]): Rune

Create single unicode rune from string literal - uc"⮰" Source Edit

func width(text: ColText): int {....raises: [], tags: [].}

Get maximum width (line length) of the colored text Source Edit

Iterators

iterator items(text: ColText): ColRune {....raises: [], tags: [].}: Iterate over all runes left to right Source Edit
iterator lines(text: ColText): ColRuneLine {....raises: [], tags: [].}: Iterate over lines of the colored text Source Edit
iterator ritems(text: ColText): ColRune {....raises: [], tags: [].}: Iterate over all runes right to left Source Edit

Templates

template coloredResult(indentationStep: int = 2): untyped: Inject helper templates for construction of the colored text in recursive procedure. Adds one-argument procedures and templates that append text to the main procedure result. Injected indentation procs use indentationStep of whitespaces per level.
proc treeRepr(node: SomeNode): ColText = coloredResult() # Inject `add`, `addIndent` procs proc aux(node: SomeNode, level: int) = addIndent(level) add $node.kind # Add text to the `result` of the main proc for sub in node: aux(sub, level + 1) aux(node)
Injected routines

addf(string, varargs)

add(string), add(string, string)

addIndent(int), addi(int, string)

Source Edit

Exports

ForegroundColor, BackgroundColor, Style

experimental/colortext

Imports

Types

Procs

Iterators

Templates

Exports