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 in palette order, repeating only after the palette is exhausted. Assignments are remembered, so a key always resolves to the same color for the Assigner's lifetime. Assign keys in a stable order, such as sorted order, to reproduce the same mapping 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 next palette color for a new key. The choice is remembered, so a key always resolves to the same color thereafter. Colors repeat in palette order after the palette is exhausted. 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:
50
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 the first 50 colors of Colorcet's glasbey_light palette (https://colorcet.holoviz.org/user_guide/Categorical.html), the standard Glasbey palette for dark backgrounds. Glasbey orders colors so each addition is maximally distinct from the preceding colors. Each call returns a fresh palette the caller owns.
func TrueColorLight
func TrueColorLight() Palette
TrueColorLight returns the first 50 colors of Colorcet's glasbey_dark, the standard Glasbey palette for light backgrounds. 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 in palette order, repeating only after the palette is exhausted. Assignments are remembered, so a key always resolves to the same color for the Assigner's lifetime. Assign keys in a stable order, such as sorted order, to reproduce the same mapping 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: 50
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 the first 50 colors of Colorcet's glasbey_light palette (https://colorcet.holoviz.org/user_guide/Categorical.html), the standard Glasbey palette for dark backgrounds. Glasbey orders colors so each addition is maximally distinct from the preceding colors. Each call returns a fresh palette the caller owns.
func TrueColorLight ¶
func TrueColorLight() Palette
TrueColorLight returns the first 50 colors of Colorcet's glasbey_dark, the standard Glasbey palette for light backgrounds. 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