README
¶
palette
import "github.com/gechr/x/palette"
Package palette provides stable, hash-based color selection from ordered color palettes, plus curated palettes tuned for light and dark terminal backgrounds.
The mapping from string to color is deterministic: the same text always resolves to the same color for a given palette, across processes and platforms. This makes it suitable for colorizing entities such as environments, hostnames, or identifiers so they stay visually consistent.
Index
type Assigner
Assigner hands out colors from a Palette so distinct keys receive distinct colors. Each key is placed at its hash-derived color - the same slot Palette.Color would choose - and if that color is already taken, the Assigner probes forward to the next free color. Assignments are remembered, so a key always resolves to the same color for the Assigner's lifetime.
This blends the two extremes: like Palette.Color a key tends to land on its stable hash color across runs, but unlike it distinct keys never share a color until the palette is exhausted (after which colors repeat). A key only moves off its hash color when an earlier-seen key collided into that slot, so with few keys relative to the palette size, most keys stay stable across runs.
An Assigner is safe for concurrent use.
type Assigner struct {
// contains filtered or unexported fields
}
func NewAssigner
func NewAssigner(colors ...color.Color) *Assigner
NewAssigner returns an Assigner that draws from the given colors. When no colors are given, it defaults to Auto, selecting a palette that matches the terminal background and true-color support. Pass an explicit palette by spreading it, e.g. NewAssigner(TrueColorDark()...).
Example
// An Assigner gives distinct keys distinct colors (no duplicates until the
// palette is exhausted) while keeping each key stable. With no colors it
// defaults to Auto for the current terminal.
a := palette.NewAssigner()
fmt.Println(a.Assign("web") == a.Assign("web"))
Output:
true
func (*Assigner) Assign
func (a *Assigner) Assign(key string) color.Color
Assign returns the color for key: its hash-derived color when free, otherwise the next free color. The choice is remembered, so a key always resolves to the same color thereafter. It returns nil when the palette is empty.
func (*Assigner) Palette
func (a *Assigner) Palette() Palette
Palette returns the underlying palette the Assigner draws from.
type Option
Option configures Auto.
type Option func(*config)
func WithTrueColor
func WithTrueColor() Option
WithTrueColor forces Auto to return the true-color Glasbey palette, overriding its automatic terminal-capability detection. The caller is responsible for ensuring the terminal supports true color.
type Palette
Palette is an ordered list of colors from which a stable color is chosen for a given string.
type Palette []color.Color
func Auto
func Auto(opts ...Option) Palette
Auto returns a palette matching the terminal, defaulting to the dark palette when background detection is unavailable. By default it selects the Glasbey palette when the terminal supports true color and the ANSI-256 palette otherwise; pass WithTrueColor to force the Glasbey palette.
Example
// Auto detects the terminal background and true-color support, then colors
// entities so identical strings share a stable color.
p := palette.Auto()
for _, entity := range []string{"alpha", "beta", "alpha"} {
_ = p.Color(entity)
}
// Force the true-color Glasbey palette regardless of detection.
p = palette.Auto(palette.WithTrueColor())
fmt.Println(len(p))
Output:
36
func DefaultDark
func DefaultDark() Palette
DefaultDark returns the default ANSI-256 palette tuned for dark backgrounds.
func DefaultLight
func DefaultLight() Palette
DefaultLight returns the default palette tuned for light backgrounds: the DefaultDark palette darkened for contrast against a light background.
func TrueColorDark
func TrueColorDark() Palette
TrueColorDark returns a vivid 36-color Glasbey palette curated for dark backgrounds. It was generated with glasbey using lightness bounds of 50-90 and chroma bounds of 40-100, then optimized as a complete set for perceptual separation. Each color has a contrast ratio of at least 4.5:1 against black. Each call returns a fresh palette the caller owns.
func TrueColorLight
func TrueColorLight() Palette
TrueColorLight returns a vivid 36-color Glasbey palette curated for light backgrounds. It was generated with glasbey using lightness bounds of 10-35 and chroma bounds of 40-100, then optimized as a complete set for perceptual separation. Each color has a contrast ratio of at least 4.5:1 against white. See TrueColorDark.
func (Palette) Color
func (p Palette) Color(text string) color.Color
Color returns a stable color for text, or nil when the palette is empty. The same text always yields the same color for a given palette.
Example
p := palette.DefaultDark()
// The same entity always resolves to the same color.
fmt.Println(p.Color("alpha") == p.Color("alpha"))
Output:
true
Example (Empty)
// An empty palette resolves every input to nil, leaving text uncolored.
fmt.Println(palette.Palette(nil).Color("alpha"))
Output:
<nil>
Documentation
¶
Overview ¶
Package palette provides stable, hash-based color selection from ordered color palettes, plus curated palettes tuned for light and dark terminal backgrounds.
The mapping from string to color is deterministic: the same text always resolves to the same color for a given palette, across processes and platforms. This makes it suitable for colorizing entities such as environments, hostnames, or identifiers so they stay visually consistent.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Assigner ¶ added in v0.5.1
type Assigner struct {
// contains filtered or unexported fields
}
Assigner hands out colors from a Palette so distinct keys receive distinct colors. Each key is placed at its hash-derived color - the same slot Palette.Color would choose - and if that color is already taken, the Assigner probes forward to the next free color. Assignments are remembered, so a key always resolves to the same color for the Assigner's lifetime.
This blends the two extremes: like Palette.Color a key tends to land on its stable hash color across runs, but unlike it distinct keys never share a color until the palette is exhausted (after which colors repeat). A key only moves off its hash color when an earlier-seen key collided into that slot, so with few keys relative to the palette size, most keys stay stable across runs.
An Assigner is safe for concurrent use.
func NewAssigner ¶ added in v0.5.1
NewAssigner returns an Assigner that draws from the given colors. When no colors are given, it defaults to Auto, selecting a palette that matches the terminal background and true-color support. Pass an explicit palette by spreading it, e.g. NewAssigner(TrueColorDark()...).
Example ¶
package main
import (
"fmt"
"github.com/gechr/x/palette"
)
func main() {
// An Assigner gives distinct keys distinct colors (no duplicates until the
// palette is exhausted) while keeping each key stable. With no colors it
// defaults to Auto for the current terminal.
a := palette.NewAssigner()
fmt.Println(a.Assign("web") == a.Assign("web"))
}
Output: true
type Option ¶
type Option func(*config)
Option configures Auto.
func WithTrueColor ¶
func WithTrueColor() Option
WithTrueColor forces Auto to return the true-color Glasbey palette, overriding its automatic terminal-capability detection. The caller is responsible for ensuring the terminal supports true color.
type Palette ¶
Palette is an ordered list of colors from which a stable color is chosen for a given string.
func Auto ¶
Auto returns a palette matching the terminal, defaulting to the dark palette when background detection is unavailable. By default it selects the Glasbey palette when the terminal supports true color and the ANSI-256 palette otherwise; pass WithTrueColor to force the Glasbey palette.
Example ¶
package main
import (
"fmt"
"github.com/gechr/x/palette"
)
func main() {
// Auto detects the terminal background and true-color support, then colors
// entities so identical strings share a stable color.
p := palette.Auto()
for _, entity := range []string{"alpha", "beta", "alpha"} {
_ = p.Color(entity)
}
// Force the true-color Glasbey palette regardless of detection.
p = palette.Auto(palette.WithTrueColor())
fmt.Println(len(p))
}
Output: 36
func DefaultDark ¶
func DefaultDark() Palette
DefaultDark returns the default ANSI-256 palette tuned for dark backgrounds.
func DefaultLight ¶
func DefaultLight() Palette
DefaultLight returns the default palette tuned for light backgrounds: the DefaultDark palette darkened for contrast against a light background.
func TrueColorDark ¶
func TrueColorDark() Palette
TrueColorDark returns a vivid 36-color Glasbey palette curated for dark backgrounds. It was generated with glasbey using lightness bounds of 50-90 and chroma bounds of 40-100, then optimized as a complete set for perceptual separation. Each color has a contrast ratio of at least 4.5:1 against black. Each call returns a fresh palette the caller owns.
func TrueColorLight ¶
func TrueColorLight() Palette
TrueColorLight returns a vivid 36-color Glasbey palette curated for light backgrounds. It was generated with glasbey using lightness bounds of 10-35 and chroma bounds of 40-100, then optimized as a complete set for perceptual separation. Each color has a contrast ratio of at least 4.5:1 against white. See TrueColorDark.
func (Palette) Color ¶
Color returns a stable color for text, or nil when the palette is empty. The same text always yields the same color for a given palette.
Example ¶
package main
import (
"fmt"
"github.com/gechr/x/palette"
)
func main() {
p := palette.DefaultDark()
// The same entity always resolves to the same color.
fmt.Println(p.Color("alpha") == p.Color("alpha"))
}
Output: true
Example (Empty) ¶
package main
import (
"fmt"
"github.com/gechr/x/palette"
)
func main() {
// An empty palette resolves every input to nil, leaving text uncolored.
fmt.Println(palette.Palette(nil).Color("alpha"))
}
Output: <nil>
Source Files