ansistyles

README

ansistyles

ANSI escape codes for styling strings in the terminal

This is a port of Sindre Sorhus and Josh Junon's library ansi-styles (part of chalk) from JavaScript to Golang. This port is up-to-date as of ansi-styles@v5.1.0.

This library just generates ANSI escape codes - it does nothing to decide whether the current terminal is capable of showing the generated codes. You probably want a higher-level module for styling your strings.

There are quite a few popular libraries for doing ANSI escape codes in go, but many will not work on Windows, even though Windows 10 has supported ANSI out-of-the-box since 2016 in CMD.EXE, in Powershell since v5.1, and in Windows Terminal since it was created. This library is meant to be a building block for bulding something cross-platform.

Install

$ go get github.com/jwalton/gchalk/pkg/ansistyles

Usage

package main

import (
    "fmt"

    "github.com/jwalton/gchalk/pkg/ansistyles"
)

func main() {
    fmt.Println(ansistyles.Green.Open + "Hello world!" + ansistyles.Green.Close)

    // Color conversion between 16/256/truecolor
    // NOTE: If conversion goes to 16 colors or 256 colors, the original color
    //       may be degraded to fit that color palette. This means terminals
    //       that do not support 16 million colors will best-match the
    //       original color.
    fmt.Println(ansistyles.Ansi256(ansistyles.RGBToAnsi256(199, 20, 250)) + "Hello World" + ansistyles.Close)
    fmt.Println(ansistyles.Ansi16m(ansistyles.HexToRGB("#abcdef")) + "Hello World" + ansistyles.Close)
}

API

Each style has an Open and Close property.

Styles

Modifiers

• Reset
• Bold
• Dim
• Italic (Not widely supported)
• Underline
• Overline Supported on VTE-based terminals, the GNOME terminal, mintty, and Git Bash.
• Inverse
• Hidden
• Strikethrough (Not widely supported)

Colors

• Black
• Red
• Green
• Yellow
• Blue
• Magenta
• Cyan
• White
• BrightBlack (alias: Gray, Grey)
• BrightRed
• BrightGreen
• BrightYellow
• BrightBlue
• BrightMagenta
• BrightCyan
• BrightWhite

Background colors

• BgBlack
• BgRed
• BgGreen
• BgYellow
• BgBlue
• BgMagenta
• BgCyan
• BgWhite
• BgBrightBlack (alias: BgGray, BgGrey)
• BgBrightRed
• BgBrightGreen
• BgBrightYellow
• BgBrightBlue
• BgBrightMagenta
• BgBrightCyan
• BgBrightWhite

Advanced usage

Styles are available directly as values (e.g. ansistyles.Blue), via a lookup map using string names (e.g. ansistyles.Styles["blue"]), and also by grouped maps (e.g. ansistyles.BgColor["bgBlue"]):

• ansistyles.Modifier
• ansistyles.Color
• ansistyles.BgColor

Example:

fmt.Println(ansistyles.Color["green"].open);

Raw escape codes (i.e. without the CSI escape prefix \u001B[ and render mode postfix m) are available under style.Codes, which returns a map with the open codes as keys and close codes as values.

Example:

fmt.Println(ansistyles.Codes[36]); //=> 39

256 / 16 million (TrueColor) support

ansistyles allows converting between various color formats and ANSI escapes, with support for 256 and 16 million colors. The following color spaces are supported:

• rgb
• hex
• ansi256

To use these, call the associated conversion function with the intended output, for example:

ansistyles.Ansi256(ansistyles.RGBToAnsi256(100, 200, 15)) // RGB to 256 color ansi foreground code
ansistyles.BgAnsi256(ansistyles.HexToAnsi256("#C0FFEE")) // HEX to 256 color ansi foreground code
ansistyles.Ansi(ansistyles.RGBToAnsi(100, 200, 15)) // RGB to 16 color ansi foreground code

ansistyles.Ansi16m(100, 200, 15); // RGB to 16 million color foreground code
ansistyles.BgAnsi16m(ansistyles.HexToRgb("#C0FFEE")); // Hex (RGB) to 16 million color foreground code
ansistyles.BgAnsi(ansistyles.RGBToAnsi(100, 200, 15)) // RGB to 16 color ansi background code

Documentation

Overview

Package ansistyles is a complete port of the "ansi-styles" node.js library.

This library just generates ANSI escape codes - it does nothing to decide whether the current terminal is capable of showing the generated codes. You probably want a higher-level module for styling your strings.

Basic usage:

fmt.Println(ansistyles.Green.Open + "Hello world!" + ansistyles.Green.Close)

Each "style" has an "Open" and "Close" property.

Modifiers:

- `Reset` - `Bold` - `Dim` - `Italic` _(Not widely supported)_ - `Underline` - `Overline` _Supported on VTE-based terminals, the GNOME terminal, mintty, and Git Bash._ - `Inverse` - `Hidden` - `Strikethrough` _(Not widely supported)_

Colors:

- `Black` - `Red` - `Green` - `Yellow` - `Blue` - `Magenta` - `Cyan` - `White` - `BrightBlack` (alias: `Gray`, `Grey`) - `BrightRed` - `BrightGreen` - `BrightYellow` - `BrightBlue` - `BrightMagenta` - `BrightCyan` - `BrightWhite`

Background colors:

- `BgBlack` - `BgRed` - `BgGreen` - `BgYellow` - `BgBlue` - `BgMagenta` - `BgCyan` - `BgWhite` - `BgBrightBlack` (alias: `BgGray`, `BgGrey`) - `BgBrightRed` - `BgBrightGreen` - `BgBrightYellow` - `BgBrightBlue` - `BgBrightMagenta` - `BgBrightCyan` - `BgBrightWhite`

Styles are available directly as values (e.g. `ansistyles.Blue`), via a lookup map using string names (e.g. `ansistyles.Styles["blue"]`), and also by grouped maps (e.g. `ansistyles.BgColor["bgBlue"]`):

- `ansistyles.Modifier` - `ansistyles.Color` - `ansistyles.BgColor`

Example:

fmt.Println(ansistyles.Color["green"].open);

Raw escape codes (i.e. without the CSI escape prefix `\u001B[` and render mode postfix `m`) are available under `style.Codes`, which returns a `map` with the open codes as keys and close codes as values:

fmt.Println(ansistyles.Codes[36]); //=> 39

`ansistyles` allows converting between various color formats and ANSI escapes, with support for 256 and 16 million colors. The following color spaces are supported:

- `rgb` - `hex` - `ansi256`

To use these, call the associated conversion function with the intended output, for example:

ansistyles.Ansi256(ansistyles.RGBToAnsi256(100, 200, 15)) // RGB to 256 color ansi foreground code
ansistyles.BgAnsi256(ansistyles.HexToAnsi256("#C0FFEE")) // HEX to 256 color ansi foreground code

ansistyles.Ansi16m(100, 200, 15); // RGB to 16 million color foreground code
ansistyles.BgAnsi16m(ansistyles.HexToRgb("#C0FFEE")); // Hex (RGB) to 16 million color foreground code

The node.js "ansi-styles" was originally written by Sindre Sorhus and Josh Junon, and is part of the popular node.js "chalk" library.

Index

• Constants
• Variables
• func Ansi(color uint8) string
• func Ansi16m(red uint8, green uint8, blue uint8) string
• func Ansi256(color uint8) string
• func Ansi256ToAnsi(code uint8) uint8
• func BgAnsi(color uint8) string
• func BgAnsi16m(red uint8, green uint8, blue uint8) string
• func BgAnsi256(color uint8) string
• func CloseCode(code uint8) uint8
• func HexToAnsi256(hex string) uint8
• func HexToRGB(hex string) (red uint8, green uint8, blue uint8)
• func RGBToAnsi(r uint8, g uint8, b uint8) uint8
• func RGBToAnsi256(red uint8, green uint8, blue uint8) uint8
• func WriteStringAnsi(out *strings.Builder, color uint8)
• func WriteStringAnsi16m(out *strings.Builder, red uint8, green uint8, blue uint8)
• func WriteStringAnsi256(out *strings.Builder, color uint8)
• func WriteStringBgAnsi(out *strings.Builder, color uint8)
• func WriteStringBgAnsi16m(out *strings.Builder, red uint8, green uint8, blue uint8)
• func WriteStringBgAnsi256(out *strings.Builder, color uint8)
• type CSPair

Constants

const BgClose = "\u001B[49m"

BgClose is the "close" code for 256 amd 16m ansi background color codes.

const Close = "\u001B[39m"

Close is the "close" code for 256 amd 16m ansi color codes.

Variables

var BgBlack = namedCSPair(40, 49)

BgBlack background color

var BgBlue = namedCSPair(44, 49)

BgBlue background color

var BgBrightBlack = namedCSPair(100, 49)

BgBrightBlack background color

var BgBrightBlue = namedCSPair(104, 49)

BgBrightBlue background color

var BgBrightCyan = namedCSPair(106, 49)

BgBrightCyan background color

var BgBrightGreen = namedCSPair(102, 49)

BgBrightGreen background color

var BgBrightMagenta = namedCSPair(105, 49)

BgBrightMagenta background color

var BgBrightRed = namedCSPair(101, 49)

BgBrightRed background color

var BgBrightWhite = namedCSPair(107, 49)

BgBrightWhite background color

var BgBrightYellow = namedCSPair(103, 49)

BgBrightYellow background color

var BgColor = map[string]CSPair{
	"bgBlack":         BgBlack,
	"bgRed":           BgRed,
	"bgGreen":         BgGreen,
	"bgYellow":        BgYellow,
	"bgBlue":          BgBlue,
	"bgMagenta":       BgMagenta,
	"bgCyan":          BgCyan,
	"bgWhite":         BgWhite,
	"bgBrightBlack":   BgBrightBlack,
	"bgBrightRed":     BgBrightRed,
	"bgBrightGreen":   BgBrightGreen,
	"bgBrightYellow":  BgBrightYellow,
	"bgBrightBlue":    BgBrightBlue,
	"bgBrightMagenta": BgBrightMagenta,
	"bgBrightCyan":    BgBrightCyan,
	"bgBrightWhite":   BgBrightWhite,
	"bgGrey":          BgBrightBlack,
	"bgGray":          BgBrightBlack,
}

BgColor is a map of background colors by name

var BgCyan = namedCSPair(46, 49)

BgCyan background color

var BgGray = BgBrightBlack

BgGray is an alias for BgBrightBlack

var BgGreen = namedCSPair(42, 49)

BgGreen background color

var BgGrey = BgBrightBlack

BgGrey is an alias for BgBrightBlack

var BgMagenta = namedCSPair(45, 49)

BgMagenta background color

var BgRed = namedCSPair(41, 49)

BgRed background color

var BgWhite = namedCSPair(47, 49)

BgWhite background color

var BgYellow = namedCSPair(43, 49)

BgYellow background color

var Black = namedCSPair(30, 39)

Black foreground color

var Blue = namedCSPair(34, 39)

Blue foreground color

var Bold = namedCSPair(1, 22)

Bold modifier 21 isn't widely supported and 22 does the same thing

var BrightBlack = namedCSPair(90, 39)

BrightBlack foreground color

var BrightBlue = namedCSPair(94, 39)

BrightBlue foreground color

var BrightCyan = namedCSPair(96, 39)

BrightCyan foreground color

var BrightGreen = namedCSPair(92, 39)

BrightGreen foreground color

var BrightMagenta = namedCSPair(95, 39)

BrightMagenta foreground color

var BrightRed = namedCSPair(91, 39)

BrightRed foreground color

var BrightWhite = namedCSPair(97, 39)

BrightWhite foreground color

var BrightYellow = namedCSPair(93, 39)

BrightYellow foreground color

var Color = map[string]CSPair{
	"black":         Black,
	"red":           Red,
	"green":         Green,
	"yellow":        Yellow,
	"blue":          Blue,
	"magenta":       Magenta,
	"cyan":          Cyan,
	"white":         White,
	"brightBlack":   BrightBlack,
	"brightRed":     BrightRed,
	"brightGreen":   BrightGreen,
	"brightYellow":  BrightYellow,
	"brightBlue":    BrightBlue,
	"brightMagenta": BrightMagenta,
	"brightCyan":    BrightCyan,
	"brightWhite":   BrightWhite,
	"grey":          BrightBlack,
	"gray":          BrightBlack,
}

Color is a map of colors by name

var Cyan = namedCSPair(36, 39)

Cyan foreground color

var Dim = namedCSPair(2, 22)

Dim modifier

var Gray = BrightBlack

Gray is an alias for BrightBlack

var Green = namedCSPair(32, 39)

Green foreground color

var Grey = BrightBlack

Grey is an alias for BrightBlack

var Hidden = namedCSPair(8, 28)

Hidden modifier

var Inverse = namedCSPair(7, 27)

Inverse modifier

var Italic = namedCSPair(3, 23)

Italic modifier

var Magenta = namedCSPair(35, 39)

Magenta foreground color

var Modifier = map[string]CSPair{
	"reset":         Reset,
	"bold":          Bold,
	"dim":           Dim,
	"italic":        Italic,
	"underline":     Underline,
	"overline":      Overline,
	"inverse":       Inverse,
	"hidden":        Hidden,
	"strikethrough": Strikethrough,
}

Modifier is a map of modifiers by name

var Overline = namedCSPair(53, 55)

Overline modifier

var Red = namedCSPair(31, 39)

Red foreground color

var Reset = namedCSPair(0, 0)

Reset colors

var Strikethrough = namedCSPair(9, 29)

Strikethrough modifier

var Styles = map[string]CSPair{
	"reset":           Reset,
	"bold":            Bold,
	"dim":             Dim,
	"italic":          Italic,
	"underline":       Underline,
	"overline":        Overline,
	"inverse":         Inverse,
	"hidden":          Hidden,
	"strikethrough":   Strikethrough,
	"black":           Black,
	"red":             Red,
	"green":           Green,
	"yellow":          Yellow,
	"blue":            Blue,
	"magenta":         Magenta,
	"cyan":            Cyan,
	"white":           White,
	"brightBlack":     BrightBlack,
	"brightRed":       BrightRed,
	"brightGreen":     BrightGreen,
	"brightYellow":    BrightYellow,
	"brightBlue":      BrightBlue,
	"brightMagenta":   BrightMagenta,
	"brightCyan":      BrightCyan,
	"brightWhite":     BrightWhite,
	"grey":            BrightBlack,
	"gray":            BrightBlack,
	"bgBlack":         BgBlack,
	"bgRed":           BgRed,
	"bgGreen":         BgGreen,
	"bgYellow":        BgYellow,
	"bgBlue":          BgBlue,
	"bgMagenta":       BgMagenta,
	"bgCyan":          BgCyan,
	"bgWhite":         BgWhite,
	"bgBrightBlack":   BgBrightBlack,
	"bgBrightRed":     BgBrightRed,
	"bgBrightGreen":   BgBrightGreen,
	"bgBrightYellow":  BgBrightYellow,
	"bgBrightBlue":    BgBrightBlue,
	"bgBrightMagenta": BgBrightMagenta,
	"bgBrightCyan":    BgBrightCyan,
	"bgBrightWhite":   BgBrightWhite,
	"bgGrey":          BgBrightBlack,
	"bgGray":          BgBrightBlack,
}

Styles is a map of colors and modifiers by name

var Underline = namedCSPair(4, 24)

Underline modifier

var White = namedCSPair(37, 39)

White foreground color

var Yellow = namedCSPair(33, 39)

Yellow foreground color

Functions

func Ansi

func Ansi(color uint8) string

Ansi returns the string used to set the foreground color, based on a basic 16-color Ansi code.

`color` should be a number between 30 and 37 or 90 and 97, inclusive.

func Ansi16m

func Ansi16m(red uint8, green uint8, blue uint8) string

Ansi16m returns the string used to set a 24bit foreground color.

func Ansi256

func Ansi256(color uint8) string

Ansi256 returns the string used to set the foreground color, based on Ansi 256 color lookup table.

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

func Ansi256ToAnsi

func Ansi256ToAnsi(code uint8) uint8

Ansi256ToAnsi converts from the ANSI 256 color space to the ANSI 16 color space.

func BgAnsi

func BgAnsi(color uint8) string

BgAnsi returns the string used to set the background color, based on a basic 16-color Ansi code.

`color` should be a number between 30 and 37 or 90 and 97, inclusive.

func BgAnsi16m

func BgAnsi16m(red uint8, green uint8, blue uint8) string

BgAnsi16m returns the string used to set a 24bit background color.

func BgAnsi256

func BgAnsi256(color uint8) string

BgAnsi256 returns the string used to set the background color, based on Ansi 256 color lookup table.

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

func CloseCode

func CloseCode(code uint8) uint8

CloseCode returns the raw close escape code (i.e. without the CSI escape prefix `\u001B[` and render mode postfix `m`), given a raw open code.

fmt.Println(ansistyles.CloseCode(36)); //=> 39

func HexToAnsi256

func HexToAnsi256(hex string) uint8

HexToAnsi256 converts from the RGB HEX color space to the ANSI 256 color space. hex should be a hexadecimal string containing RGB data.

func HexToRGB

func HexToRGB(hex string) (red uint8, green uint8, blue uint8)

HexToRGB converts from the RGB HEX color space to the RGB color space.

"hex" should be a hexadecimal string containing RGB data (e.g. "#2340ff" or "00f"). Note that the leading "#" is optional. If the hex code passed in is invalid, this will return 0, 0, 0 - it's up to you to validate the input if you want to detect invalid values.

func RGBToAnsi

func RGBToAnsi(r uint8, g uint8, b uint8) uint8

RGBToAnsi converts from the RGB color space to the ANSI 16 color space.

func RGBToAnsi256

func RGBToAnsi256(red uint8, green uint8, blue uint8) uint8

RGBToAnsi256 converts from the RGB color space to the ANSI 256 color space.

func WriteStringAnsi

func WriteStringAnsi(out *strings.Builder, color uint8)

WriteStringAnsi writes an ANSI escape code to the given strings.Builder.

func WriteStringAnsi16m

func WriteStringAnsi16m(out *strings.Builder, red uint8, green uint8, blue uint8)

WriteStringAnsi16m writes the string used to set a 24bit foreground color.

func WriteStringAnsi256

func WriteStringAnsi256(out *strings.Builder, color uint8)

WriteStringAnsi256 writes the string used to set the foreground color, based on Ansi 256 color lookup table.

func WriteStringBgAnsi

func WriteStringBgAnsi(out *strings.Builder, color uint8)

WriteStringBgAnsi writes an ANSI escape code to set the background color to the given strings.Builder.

func WriteStringBgAnsi16m

func WriteStringBgAnsi16m(out *strings.Builder, red uint8, green uint8, blue uint8)

WriteStringBgAnsi16m writes the string used to set a 24bit background color.

func WriteStringBgAnsi256

func WriteStringBgAnsi256(out *strings.Builder, color uint8)

WriteStringBgAnsi256 writes the string used to set the background color, based on Ansi 256 color lookup table.

Types

type CSPair

type CSPair struct {
	Open  string
	Close string
}

CSPair contains the ANSI color codes to open and close a given color.