aurora

Aurora is a Go library for producing ANSI-colored terminal output without giving up the standard library’s fmt verbs. Instead of wrapping strings in escape codes by hand, you wrap any value in a chainable colorizer — aurora.Red("x").Bold().BgMagenta() — and it implements fmt.Stringer and fmt.Formatter, so it drops directly into Printf, Sprintf, and every other fmt-based call while carrying its own width, precision, and verb flags through untouched.

Beyond the 16 standard/bright foreground and background colors, Aurora supports the 8-bit 256-color palette (Index/BgIndex), a 24-step grayscale ramp (Gray/BgGray), the full set of SGR text formats (bold, faint, italic, underline, blink, reverse, conceal, strikethrough, framed, encircled, overlined), and OSC 8 terminal hyperlinks via Hyperlink, which can be toggled off globally through a Config/Option pair so the same call sites degrade gracefully on terminals that don’t support links or colors at all.

The package has been stable for years — versioned import paths (/v3, /v4) keep old call sites compiling as the API grows — and is commonly reached for in Go CLIs, log formatters, and test output where colored terminal text needs to compose with existing fmt-based code rather than replace it.

What You Get

• Package-level color functions (aurora.Red, aurora.BgBlue, aurora.Bold, etc.) that return a Value usable anywhere fmt accepts an argument
• A chainable Value API so formats and colors combine fluently, e.g. aurora.Red("x").Bold().Underline()
• An instantiable *Aurora colorizer (aurora.New(opts...)) for cases where colors need to be enabled/disabled at runtime via Config/Option, including CLI flag wiring through Config.AddFlags
• 8-bit Index/BgIndex colors (256-color palette) and a dedicated Gray/BgGray grayscale ramp
• aurora.Sprintf, a format-aware Sprintf variant that lets a Value used as the format string propagate its own color to substituted arguments
• OSC 8 hyperlink support (Hyperlink, HyperlinkID, HyperlinkEscape) with graceful fallback to plain text targets when hyperlinks are disabled

Common Use Cases

• Coloring CLI tool output (success/error/warning messages) while keeping existing fmt.Printf call sites unchanged
• Building a toggle-able colorizer so --no-color/NO_COLOR-style flags can disable ANSI output at runtime without touching call sites
• Highlighting diffs, test results, or log levels in terminal-based developer tooling
• Emitting clickable OSC 8 hyperlinks (e.g. file paths, URLs) in terminal output for supporting terminal emulators
• Rendering 256-color or grayscale gradients for progress bars, palettes, or visual terminal demos

Under The Hood

Architecture The package centers on two types: Color, a uint bitmask packing an SGR format, foreground color, and background color into a single value (color.go), and Value (value.go), a struct pairing an arbitrary interface{} with a colorConfig (the Color bitmask plus two feature-enable bits for colors/hyperlinks) and an optional *hyperlink. Package-level functions in aurora.go and chainable methods on Value both funnel through the same bitwise OR composition (v.cc.color().Red() | v.cc.resetColor()), so a fluent call chain and a one-shot aurora.Red(x) call produce identical Value structs. Value.String() and Value.Format() implement fmt.Stringer/fmt.Formatter, intercepting the verb, width, and precision fmt passes in via fmt.State and re-emitting them wrapped in ANSI escape sequences (coloredFormat in value.go) — this is what lets a colored Value be substituted directly into a Printf call. An optional *Aurora instance (aurora.go) wraps the same primitives behind a Config/Option pair so colors and hyperlinks can be toggled per-instance at runtime, e.g. from a CLI flag, without touching call sites; nothing else in the core color/format logic depends on that instance.

Tech Stack Pure Go with zero runtime dependencies — go.mod declares only github.com/stretchr/testify as a test-only dependency (with go-spew, go-difflib, and yaml.v3 pulled in transitively as testify’s own indirect deps). The module targets Go 1.19 and is versioned via Go modules’ major-version-in-import-path convention (/v3, /v4), letting the API evolve without breaking callers still on older import paths. No build tooling beyond go build/go test; CI (GitHub Actions, self-hosted runner) runs go test -v -covermode=count plus a Coveralls upload, with a golangci-lint step present in the workflow but currently commented out.

Code Quality Test coverage is extensive relative to the implementation: nine _test.go files (color, config, value, wrap, sprintf, hyperlinks, plus a dedicated bench_test.go) exercise the bit-packing logic, fmt.Formatter verb/width/precision handling, and hyperlink escaping using the standard testing package with testify’s require/assert for structured comparisons — including bit-level assertions on the Color/colorConfig masks, which is the kind of testing an encoding-heavy package like this needs. Error handling is minimal by design since the package has almost no fallible operations (no I/O, no parsing of untrusted input); the one place it matters — malformed hyperlink targets — is handled by requiring callers to pre-escape values via HyperlinkEscape rather than validating internally, which is documented but not enforced by the type system. Naming is consistent throughout (Bg-prefixed background variants mirror every foreground function; Bright-prefixed variants mirror standard colors), and doc comments on every exported function cite the underlying SGR code number, which doubles as inline protocol documentation.

What Makes It Unique Aurora’s defining technical choice is implementing fmt.Formatter rather than exposing its own Sprint/Print API — most Go color libraries (e.g. simple ANSI wrappers) only offer string-building helpers and force callers to abandon fmt verbs like %+.2f or %-10s once a value needs color. By intercepting fmt.State inside Format(), Aurora preserves arbitrary verb/width/precision formatting on a colored value with no special-cased Sprintf variant needed for the common case, and its separate aurora.Sprintf variant extends that idea further by letting the format string itself be a colored Value that propagates its color to plain (non-Value) substituted arguments — a small but distinctive piece of format-string-aware color propagation not found in comparable packages.