color

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 12, 2026 License: MIT Imports: 4 Imported by: 0

README

governa-color

ANSI terminal color helpers for CLI output. Emits 256-color SGR sequences when the terminal advertises 256-color support (via COLORTERM or TERM containing 256color); falls back to basic ANSI codes (30–97) otherwise. Suppresses colors entirely when stdout is not a terminal or NO_COLOR is set (no-color.org).

Why

CLIs in the governa family share a small, opinionated set of color helpers — BoldW, Gra, Red, Yel, FormatUsage, etc. — that produce consistent terminal output across every tool a user touches in a governa-managed repo. Before extraction, every governa-family repo carried its own copy of this package and synced manually; that cost real coordination time and produced silent drift. The library exists to be the single source of truth: one set of helpers, semver-versioned, picked up via go get -u.

The package is leaf-clean — no governance coupling, no governa-internal types, no convention names. It works fine outside the governa family for any Go CLI that wants the same color heuristics (256-color preferred, basic ANSI fallback, NO_COLOR respected).

Install

go get github.com/queone/governa-color

Usage

import "github.com/queone/governa-color"

func main() {
    fmt.Println(color.Bold(color.Whi5("governa")))            // bold white
    fmt.Println(color.Gra5("dim helper text"))                // canonical gray
    fmt.Println(color.Red5("error: something went wrong"))    // canonical red
    fmt.Println(color.Heat0("worst") + " " + color.Heat10("best"))

    // Background helpers compose with foreground helpers:
    fmt.Println(color.BgGra2(color.Whi9("CAREER 2024-25")))   // light-gray text on dim-gray bg
}

Each hue exposes an 11-step ramp (Gra0..Gra10, Red0..Red10, …, Whi0..Whi10) with step 5 as the canonical shade; Heat0..Heat10 is a severity/quality ramp (red → yellow → green). Every foreground helper has a Bg<Hue><Step> twin emitting the same color as background (48;5;N SGR), composable with Bold, Reverse, and any foreground helper.

color.ShowPalette() prints a labeled swatch of every color function for terminal verification. color.ShowGrid(token, reverse, fgIndex) prints a bordered side-by-side grid of every ramp at every step (RedX..HeatX columns × 0..10* rows), each cell rendering token — useful for picking a label color or comparing close shades. Empty token defaults to "TOKEN". With reverse=true each cell is a solid background-color block (handy for label-background colors); fgIndex >= 0 then overrides the text color to that 256-color SGR index (e.g. 15 for bright white).

showgrid utility

cmd/showgrid is a stand-alone CLI exposing color.ShowGrid directly. Install:

go install github.com/queone/governa-color/cmd/showgrid@latest

Then run showgrid [token] for the default grid, showgrid -r for reverse-video cells (solid colored blocks), showgrid -r=N to override the text color to 256-color SGR index N, showgrid -v for the program version, or showgrid -h for full usage.

Versioning

This library follows the policy in governa/docs/library-policy.md. See CHANGELOG.md for version history and deprecations.

Documentation

Overview

Package color provides ANSI 256-color terminal helpers for CLI output.

v1.0 redesign: the API is built around 11-step intensity ramps per hue (step 0 = darkest, step 5 = canonical, step 10 = brightest) plus a red→yellow→green Heat ramp for severity / quality scales. Modifier wrappers (Bold, Reverse) compose with any color helper.

All color helpers emit 256-color SGR sequences (38;5;N). Terminals that don't support 256-color receive uncolored output. NO_COLOR=1 and TERM=dumb also suppress all escapes (https://no-color.org).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BgBlu0 added in v1.3.0

func BgBlu0(v any) string

BgBlu — blue background ramp.

func BgBlu1 added in v1.3.0

func BgBlu1(v any) string

func BgBlu2 added in v1.3.0

func BgBlu2(v any) string

func BgBlu3 added in v1.3.0

func BgBlu3(v any) string

func BgBlu4 added in v1.3.0

func BgBlu4(v any) string

func BgBlu5 added in v1.3.0

func BgBlu5(v any) string

func BgBlu6 added in v1.3.0

func BgBlu6(v any) string

func BgBlu7 added in v1.3.0

func BgBlu7(v any) string

func BgBlu8 added in v1.3.0

func BgBlu8(v any) string

func BgBlu9 added in v1.3.0

func BgBlu9(v any) string

func BgBlu10 added in v1.3.0

func BgBlu10(v any) string

func BgCya0 added in v1.3.0

func BgCya0(v any) string

BgCya — cyan background ramp.

func BgCya1 added in v1.3.0

func BgCya1(v any) string

func BgCya2 added in v1.3.0

func BgCya2(v any) string

func BgCya3 added in v1.3.0

func BgCya3(v any) string

func BgCya4 added in v1.3.0

func BgCya4(v any) string

func BgCya5 added in v1.3.0

func BgCya5(v any) string

func BgCya6 added in v1.3.0

func BgCya6(v any) string

func BgCya7 added in v1.3.0

func BgCya7(v any) string

func BgCya8 added in v1.3.0

func BgCya8(v any) string

func BgCya9 added in v1.3.0

func BgCya9(v any) string

func BgCya10 added in v1.3.0

func BgCya10(v any) string

func BgGra0 added in v1.3.0

func BgGra0(v any) string

BgGra — gray background ramp.

func BgGra1 added in v1.3.0

func BgGra1(v any) string

func BgGra2 added in v1.3.0

func BgGra2(v any) string

func BgGra3 added in v1.3.0

func BgGra3(v any) string

func BgGra4 added in v1.3.0

func BgGra4(v any) string

func BgGra5 added in v1.3.0

func BgGra5(v any) string

func BgGra6 added in v1.3.0

func BgGra6(v any) string

func BgGra7 added in v1.3.0

func BgGra7(v any) string

func BgGra8 added in v1.3.0

func BgGra8(v any) string

func BgGra9 added in v1.3.0

func BgGra9(v any) string

func BgGra10 added in v1.3.0

func BgGra10(v any) string

func BgGrn0 added in v1.3.0

func BgGrn0(v any) string

BgGrn — green background ramp.

func BgGrn1 added in v1.3.0

func BgGrn1(v any) string

func BgGrn2 added in v1.3.0

func BgGrn2(v any) string

func BgGrn3 added in v1.3.0

func BgGrn3(v any) string

func BgGrn4 added in v1.3.0

func BgGrn4(v any) string

func BgGrn5 added in v1.3.0

func BgGrn5(v any) string

func BgGrn6 added in v1.3.0

func BgGrn6(v any) string

func BgGrn7 added in v1.3.0

func BgGrn7(v any) string

func BgGrn8 added in v1.3.0

func BgGrn8(v any) string

func BgGrn9 added in v1.3.0

func BgGrn9(v any) string

func BgGrn10 added in v1.3.0

func BgGrn10(v any) string

func BgHeat0 added in v1.3.0

func BgHeat0(v any) string

BgHeat — heat background ramp (red → yellow → green).

func BgHeat1 added in v1.3.0

func BgHeat1(v any) string

func BgHeat2 added in v1.3.0

func BgHeat2(v any) string

func BgHeat3 added in v1.3.0

func BgHeat3(v any) string

func BgHeat4 added in v1.3.0

func BgHeat4(v any) string

func BgHeat5 added in v1.3.0

func BgHeat5(v any) string

func BgHeat6 added in v1.3.0

func BgHeat6(v any) string

func BgHeat7 added in v1.3.0

func BgHeat7(v any) string

func BgHeat8 added in v1.3.0

func BgHeat8(v any) string

func BgHeat9 added in v1.3.0

func BgHeat9(v any) string

func BgHeat10 added in v1.3.0

func BgHeat10(v any) string

func BgMag0 added in v1.3.0

func BgMag0(v any) string

BgMag — magenta background ramp.

func BgMag1 added in v1.3.0

func BgMag1(v any) string

func BgMag2 added in v1.3.0

func BgMag2(v any) string

func BgMag3 added in v1.3.0

func BgMag3(v any) string

func BgMag4 added in v1.3.0

func BgMag4(v any) string

func BgMag5 added in v1.3.0

func BgMag5(v any) string

func BgMag6 added in v1.3.0

func BgMag6(v any) string

func BgMag7 added in v1.3.0

func BgMag7(v any) string

func BgMag8 added in v1.3.0

func BgMag8(v any) string

func BgMag9 added in v1.3.0

func BgMag9(v any) string

func BgMag10 added in v1.3.0

func BgMag10(v any) string

func BgOrg0 added in v1.3.0

func BgOrg0(v any) string

BgOrg — orange background ramp.

func BgOrg1 added in v1.3.0

func BgOrg1(v any) string

func BgOrg2 added in v1.3.0

func BgOrg2(v any) string

func BgOrg3 added in v1.3.0

func BgOrg3(v any) string

func BgOrg4 added in v1.3.0

func BgOrg4(v any) string

func BgOrg5 added in v1.3.0

func BgOrg5(v any) string

func BgOrg6 added in v1.3.0

func BgOrg6(v any) string

func BgOrg7 added in v1.3.0

func BgOrg7(v any) string

func BgOrg8 added in v1.3.0

func BgOrg8(v any) string

func BgOrg9 added in v1.3.0

func BgOrg9(v any) string

func BgOrg10 added in v1.3.0

func BgOrg10(v any) string

func BgPur0 added in v1.3.0

func BgPur0(v any) string

BgPur — purple background ramp.

func BgPur1 added in v1.3.0

func BgPur1(v any) string

func BgPur2 added in v1.3.0

func BgPur2(v any) string

func BgPur3 added in v1.3.0

func BgPur3(v any) string

func BgPur4 added in v1.3.0

func BgPur4(v any) string

func BgPur5 added in v1.3.0

func BgPur5(v any) string

func BgPur6 added in v1.3.0

func BgPur6(v any) string

func BgPur7 added in v1.3.0

func BgPur7(v any) string

func BgPur8 added in v1.3.0

func BgPur8(v any) string

func BgPur9 added in v1.3.0

func BgPur9(v any) string

func BgPur10 added in v1.3.0

func BgPur10(v any) string

func BgRed0 added in v1.3.0

func BgRed0(v any) string

BgRed — red background ramp.

func BgRed1 added in v1.3.0

func BgRed1(v any) string

func BgRed2 added in v1.3.0

func BgRed2(v any) string

func BgRed3 added in v1.3.0

func BgRed3(v any) string

func BgRed4 added in v1.3.0

func BgRed4(v any) string

func BgRed5 added in v1.3.0

func BgRed5(v any) string

func BgRed6 added in v1.3.0

func BgRed6(v any) string

func BgRed7 added in v1.3.0

func BgRed7(v any) string

func BgRed8 added in v1.3.0

func BgRed8(v any) string

func BgRed9 added in v1.3.0

func BgRed9(v any) string

func BgRed10 added in v1.3.0

func BgRed10(v any) string

func BgWhi0 added in v1.3.0

func BgWhi0(v any) string

BgWhi — white background ramp.

func BgWhi1 added in v1.3.0

func BgWhi1(v any) string

func BgWhi2 added in v1.3.0

func BgWhi2(v any) string

func BgWhi3 added in v1.3.0

func BgWhi3(v any) string

func BgWhi4 added in v1.3.0

func BgWhi4(v any) string

func BgWhi5 added in v1.3.0

func BgWhi5(v any) string

func BgWhi6 added in v1.3.0

func BgWhi6(v any) string

func BgWhi7 added in v1.3.0

func BgWhi7(v any) string

func BgWhi8 added in v1.3.0

func BgWhi8(v any) string

func BgWhi9 added in v1.3.0

func BgWhi9(v any) string

func BgWhi10 added in v1.3.0

func BgWhi10(v any) string

func BgYel0 added in v1.3.0

func BgYel0(v any) string

BgYel — yellow background ramp.

func BgYel1 added in v1.3.0

func BgYel1(v any) string

func BgYel2 added in v1.3.0

func BgYel2(v any) string

func BgYel3 added in v1.3.0

func BgYel3(v any) string

func BgYel4 added in v1.3.0

func BgYel4(v any) string

func BgYel5 added in v1.3.0

func BgYel5(v any) string

func BgYel6 added in v1.3.0

func BgYel6(v any) string

func BgYel7 added in v1.3.0

func BgYel7(v any) string

func BgYel8 added in v1.3.0

func BgYel8(v any) string

func BgYel9 added in v1.3.0

func BgYel9(v any) string

func BgYel10 added in v1.3.0

func BgYel10(v any) string

func Blu0 added in v1.0.0

func Blu0(v any) string

Blu — blue ramp.

func Blu1 added in v1.0.0

func Blu1(v any) string

func Blu2 added in v1.0.0

func Blu2(v any) string

func Blu3 added in v1.0.0

func Blu3(v any) string

func Blu4 added in v1.0.0

func Blu4(v any) string

func Blu5 added in v1.0.0

func Blu5(v any) string

func Blu6 added in v1.0.0

func Blu6(v any) string

func Blu7 added in v1.0.0

func Blu7(v any) string

func Blu8 added in v1.0.0

func Blu8(v any) string

func Blu9 added in v1.0.0

func Blu9(v any) string

func Blu10 added in v1.0.0

func Blu10(v any) string

func Bold added in v1.0.0

func Bold(s string) string

Bold wraps s with the ANSI bold attribute. Composable with hue / heat helpers: color.Bold(color.Grn5("text")) renders bold-green. Internal resets inside s are rewritten so the bold attribute survives across multiple colored segments — color.Bold(color.Grn5("a")+color.Red5("b")) renders both segments bold.

func ClearCode added in v0.2.0

func ClearCode(s string) string

ClearCode strips ANSI/SGR escape sequences from s. Useful for stripping color/formatting from previously-rendered strings or from piped/file input before further processing.

func Cya0 added in v1.0.0

func Cya0(v any) string

Cya — cyan ramp.

func Cya1 added in v1.0.0

func Cya1(v any) string

func Cya2 added in v1.0.0

func Cya2(v any) string

func Cya3 added in v1.0.0

func Cya3(v any) string

func Cya4 added in v1.0.0

func Cya4(v any) string

func Cya5 added in v1.0.0

func Cya5(v any) string

func Cya6 added in v1.0.0

func Cya6(v any) string

func Cya7 added in v1.0.0

func Cya7(v any) string

func Cya8 added in v1.0.0

func Cya8(v any) string

func Cya9 added in v1.0.0

func Cya9(v any) string

func Cya10 added in v1.0.0

func Cya10(v any) string

func FormatUsage

func FormatUsage(heading string, lines []UsageLine, footer string) string

FormatUsage builds a formatted help string with a heading, flag table, and optional footer.

func Gra0 added in v1.0.0

func Gra0(v any) string

Gra — gray ramp.

func Gra1 added in v1.0.0

func Gra1(v any) string

func Gra2 added in v1.0.0

func Gra2(v any) string

func Gra3 added in v1.0.0

func Gra3(v any) string

func Gra4 added in v1.0.0

func Gra4(v any) string

func Gra5 added in v1.0.0

func Gra5(v any) string

func Gra6 added in v1.0.0

func Gra6(v any) string

func Gra7 added in v1.0.0

func Gra7(v any) string

func Gra8 added in v1.0.0

func Gra8(v any) string

func Gra9 added in v1.0.0

func Gra9(v any) string

func Gra10 added in v1.0.0

func Gra10(v any) string

func Grn0 added in v1.0.0

func Grn0(v any) string

Grn — green ramp.

func Grn1 added in v1.0.0

func Grn1(v any) string

func Grn2 added in v1.0.0

func Grn2(v any) string

func Grn3 added in v1.0.0

func Grn3(v any) string

func Grn4 added in v1.0.0

func Grn4(v any) string

func Grn5 added in v1.0.0

func Grn5(v any) string

func Grn6 added in v1.0.0

func Grn6(v any) string

func Grn7 added in v1.0.0

func Grn7(v any) string

func Grn8 added in v1.0.0

func Grn8(v any) string

func Grn9 added in v1.0.0

func Grn9(v any) string

func Grn10 added in v1.0.0

func Grn10(v any) string

func Heat0 added in v1.0.0

func Heat0(v any) string

func Heat1 added in v1.0.0

func Heat1(v any) string

func Heat2 added in v1.0.0

func Heat2(v any) string

func Heat3 added in v1.0.0

func Heat3(v any) string

func Heat4 added in v1.0.0

func Heat4(v any) string

func Heat5 added in v1.0.0

func Heat5(v any) string

func Heat6 added in v1.0.0

func Heat6(v any) string

func Heat7 added in v1.0.0

func Heat7(v any) string

func Heat8 added in v1.0.0

func Heat8(v any) string

func Heat9 added in v1.0.0

func Heat9(v any) string

func Heat10 added in v1.0.0

func Heat10(v any) string

func Mag0 added in v1.0.0

func Mag0(v any) string

Mag — magenta ramp.

func Mag1 added in v1.0.0

func Mag1(v any) string

func Mag2 added in v1.0.0

func Mag2(v any) string

func Mag3 added in v1.0.0

func Mag3(v any) string

func Mag4 added in v1.0.0

func Mag4(v any) string

func Mag5 added in v1.0.0

func Mag5(v any) string

func Mag6 added in v1.0.0

func Mag6(v any) string

func Mag7 added in v1.0.0

func Mag7(v any) string

func Mag8 added in v1.0.0

func Mag8(v any) string

func Mag9 added in v1.0.0

func Mag9(v any) string

func Mag10 added in v1.0.0

func Mag10(v any) string

func Org0 added in v1.0.0

func Org0(v any) string

Org — orange ramp.

func Org1 added in v1.0.0

func Org1(v any) string

func Org2 added in v1.0.0

func Org2(v any) string

func Org3 added in v1.0.0

func Org3(v any) string

func Org4 added in v1.0.0

func Org4(v any) string

func Org5 added in v1.0.0

func Org5(v any) string

func Org6 added in v1.0.0

func Org6(v any) string

func Org7 added in v1.0.0

func Org7(v any) string

func Org8 added in v1.0.0

func Org8(v any) string

func Org9 added in v1.0.0

func Org9(v any) string

func Org10 added in v1.0.0

func Org10(v any) string

func Pur0 added in v1.0.0

func Pur0(v any) string

Pur — purple ramp.

func Pur1 added in v1.0.0

func Pur1(v any) string

func Pur2 added in v1.0.0

func Pur2(v any) string

func Pur3 added in v1.0.0

func Pur3(v any) string

func Pur4 added in v1.0.0

func Pur4(v any) string

func Pur5 added in v1.0.0

func Pur5(v any) string

func Pur6 added in v1.0.0

func Pur6(v any) string

func Pur7 added in v1.0.0

func Pur7(v any) string

func Pur8 added in v1.0.0

func Pur8(v any) string

func Pur9 added in v1.0.0

func Pur9(v any) string

func Pur10 added in v1.0.0

func Pur10(v any) string

func Red0 added in v1.0.0

func Red0(v any) string

Red — red ramp.

func Red1 added in v1.0.0

func Red1(v any) string

func Red2 added in v1.0.0

func Red2(v any) string

func Red3 added in v1.0.0

func Red3(v any) string

func Red4 added in v1.0.0

func Red4(v any) string

func Red5 added in v1.0.0

func Red5(v any) string

func Red6 added in v1.0.0

func Red6(v any) string

func Red7 added in v1.0.0

func Red7(v any) string

func Red8 added in v1.0.0

func Red8(v any) string

func Red9 added in v1.0.0

func Red9(v any) string

func Red10 added in v1.0.0

func Red10(v any) string

func Reverse added in v1.0.0

func Reverse(s string) string

Reverse wraps s with the ANSI reverse-video attribute (foreground and background swapped). Composable with hue / heat helpers; same internal- reset rewrite as Bold.

func SetEnabled

func SetEnabled(b bool) func()

SetEnabled is a test helper that mutates package-level color-enablement state. It is NOT safe for concurrent use — tests calling this must NOT call t.Parallel(). The returned closure restores the prior enabled value and is intended for deferred invocation.

func ShowBgRamps added in v1.4.0

func ShowBgRamps(token string, fgIndex int)

ShowBgRamps prints one row per Bg<Hue> family (10 hues + Heat = 11 rows), each showing the family label followed by 11 step swatches (steps 0..10) as solid background-colored blocks with token rendered inside. Distinct from ShowGrid(token, true, fgIndex), which is a dense bordered ramp×step matrix; ShowBgRamps is a per-family strip optimized for picking a Bg<Hue><Step> at a glance, with always-readable labels.

When fgIndex < 0, the text color is auto-contrasted per step from the bg luminance (white on dark steps, black on light steps) so the token is legible at every step. When fgIndex >= 0 (0..255), that fixed 256-color SGR index is used as the text color across all swatches. If token is empty, "TOKEN" is used.

func ShowGrid added in v1.1.0

func ShowGrid(token string, reverse bool, fgIndex int)

ShowGrid prints a bordered side-by-side grid: every ramp as a column (hue ramps then Heat), every step (0..10) as a row. Column headers use the function-name pattern with "X" as the step placeholder (e.g. RedX, BluX, HeatX); row labels are the X value, with row 5 suffixed "*" to mark the canonical step. Each cell renders token in that ramp/step combo, padded to fill the cell so adjacent close shades separate cleanly along the borders. If token is empty, "TOKEN" is used.

When reverse is true, cells use background-color SGR (48;5;N) instead of foreground (38;5;N), turning each cell into a solid colored rectangle — useful for evaluating shades as label backgrounds. fgIndex then selects the text color rendered atop those colored cells: pass any 256-color SGR index (0..255), or a negative value to keep the terminal's default foreground. fgIndex is ignored when reverse is false.

Useful for picking a label color or debugging ramp choices in any consumer of governa-color.

func ShowPalette

func ShowPalette()

ShowPalette prints a labeled inspection of the v1.0 palette: standard 16-color, 256-color cube, grayscale ramp, the 10 per-hue ramps, and the heat ramp. Useful for verifying terminal rendering and tuning ramp indices. Run from a real terminal so the SGR escapes render.

func Whi0 added in v1.0.0

func Whi0(v any) string

Whi — white ramp.

func Whi1 added in v1.0.0

func Whi1(v any) string

func Whi2

func Whi2(v any) string

func Whi3 added in v1.0.0

func Whi3(v any) string

func Whi4 added in v1.0.0

func Whi4(v any) string

func Whi5 added in v1.0.0

func Whi5(v any) string

func Whi6 added in v1.0.0

func Whi6(v any) string

func Whi7 added in v1.0.0

func Whi7(v any) string

func Whi8 added in v1.0.0

func Whi8(v any) string

func Whi9 added in v1.0.0

func Whi9(v any) string

func Whi10 added in v1.0.0

func Whi10(v any) string

func Yel0 added in v1.0.0

func Yel0(v any) string

Yel — yellow ramp.

func Yel1 added in v1.0.0

func Yel1(v any) string

func Yel2 added in v1.0.0

func Yel2(v any) string

func Yel3 added in v1.0.0

func Yel3(v any) string

func Yel4 added in v1.0.0

func Yel4(v any) string

func Yel5 added in v1.0.0

func Yel5(v any) string

func Yel6 added in v1.0.0

func Yel6(v any) string

func Yel7 added in v1.0.0

func Yel7(v any) string

func Yel8 added in v1.0.0

func Yel8(v any) string

func Yel9 added in v1.0.0

func Yel9(v any) string

func Yel10 added in v1.0.0

func Yel10(v any) string

Types

type UsageLine

type UsageLine struct {
	Flag string
	Desc string
}

UsageLine is a single flag+description pair for FormatUsage.

Directories

Path Synopsis
cmd
build command
build is based on an original build.sh Bash script from the source project that inspired this template.
build is based on an original build.sh Bash script from the source project that inspired this template.
prep command
rel command
CODE-flavor library wrapper.
CODE-flavor library wrapper.
showgrid command
Command showgrid prints a bordered side-by-side grid of every governa-color ramp at every step, each cell rendering a sample token.
Command showgrid prints a bordered side-by-side grid of every governa-color ramp at every step, each cell rendering a sample token.
showpalette command
Command showpalette prints every governa-color helper plus a labeled dump of all 256-color SGR indices to stdout.
Command showpalette prints every governa-color helper plus a labeled dump of all 256-color SGR indices to stdout.
internal
preptool
Package preptool stages a release: bumps version constants, inserts a CHANGELOG row, deletes completed AC files, sweeps matching AC-pointer IE lines from plan.md, runs validation builds around the write phases, and prints the canonical release command.
Package preptool stages a release: bumps version constants, inserts a CHANGELOG row, deletes completed AC files, sweeps matching AC-pointer IE lines from plan.md, runs validation builds around the write phases, and prints the canonical release command.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL