Documentation
¶
Overview ¶
Package theme is the visual vocabulary shared by every CLI renderer: color and status glyphs.
The theme layer resolves how output looks against the environment and user preference, independent of what is being rendered:
- Palette — a semantic color set (success/error/warn/info/dim/bold) that honors the NO_COLOR standard and TTY detection.
- Glyphs — a semantic symbol set (✓ ✗ ⚠ ℹ • → …) with a pure-ASCII fallback for terminals without UTF-8 support.
- Style — the palette and glyphs bundled together, so renderers thread one value instead of a separate palette/glyphs pair.
- Theme — bold headings and right-aligned, Cargo-like action lines keyed by a semantic Tone, rendered on a resolved Palette.
Both resolve from a single boolean so callers render identically regardless of terminal capability, and both expose an environment-free constructor (NewPalette, NewGlyphs) for deterministic tests alongside the environment-driven resolvers (ResolveColor, GlyphsFromEnv).
Index ¶
- Constants
- func NoColorEnvSet() bool
- func ResolveColor(choice ColorChoice, isTerminal bool) bool
- func ResolveColorWith(choice ColorChoice, noColor, isTerminal bool) bool
- func UnicodeEnvEnabled() bool
- type ColorChoice
- type Glyphs
- func (g Glyphs) Answer() string
- func (g Glyphs) Arrow() string
- func (g Glyphs) ArrowDown() string
- func (g Glyphs) ArrowUp() string
- func (g Glyphs) Bullet() string
- func (g Glyphs) Ellipsis() string
- func (g Glyphs) Error() string
- func (g Glyphs) Info() string
- func (g Glyphs) Pointer() string
- func (g Glyphs) RadioOff() string
- func (g Glyphs) RadioOn() string
- func (g Glyphs) Success() string
- func (g Glyphs) Unicode() bool
- func (g Glyphs) Warning() string
- type Palette
- type Style
- type Theme
- type Tone
Constants ¶
const DefaultActionWidth = 12
DefaultActionWidth is the default width, in terminal columns, of the right-aligned action-label column produced by Theme.Action.
const NoColorEnv = "NO_COLOR"
NoColorEnv is the environment variable that, when present (regardless of value), disables color regardless of any explicit choice. See the NO_COLOR standard: https://no-color.org.
Variables ¶
This section is empty.
Functions ¶
func NoColorEnvSet ¶
func NoColorEnvSet() bool
NoColorEnvSet reports whether the NO_COLOR environment variable is present.
Per the NO_COLOR standard (https://no-color.org) any presence disables color, so an empty value (NO_COLOR=) still counts.
func ResolveColor ¶
func ResolveColor(choice ColorChoice, isTerminal bool) bool
ResolveColor resolves a ColorChoice into an effective on/off decision.
Resolution order (the NO_COLOR standard takes precedence over an explicit request): if NO_COLOR is set the result is off; otherwise ColorAlways is on, ColorNever is off, and ColorAuto follows isTerminal. It reads the process environment for NO_COLOR; use ResolveColorWith for a fully injected, environment-free decision.
func ResolveColorWith ¶
func ResolveColorWith(choice ColorChoice, noColor, isTerminal bool) bool
ResolveColorWith is the pure resolver core: it folds an explicit NO_COLOR presence and TTY detection into an effective on/off decision, so it is environment-free and unit-testable.
NO_COLOR wins over every choice; otherwise ColorAlways/ColorNever are absolute and ColorAuto follows isTerminal.
func UnicodeEnvEnabled ¶
func UnicodeEnvEnabled() bool
UnicodeEnvEnabled reports whether the process locale advertises a UTF-8 encoding.
It consults LC_ALL, LC_CTYPE, then LANG in order and reports true when any is set to a value naming UTF-8 (case-insensitive, "utf-8" or "utf8"). When none is set the result is false, so the ASCII fallback is the safe default.
Types ¶
type ColorChoice ¶
type ColorChoice int
ColorChoice is a user's requested color policy, before environment/TTY resolution.
const ( // ColorAuto enables color only when writing to a terminal and NO_COLOR is unset. // It is the zero value, so an unset choice defaults to auto. ColorAuto ColorChoice = iota // ColorAlways forces color on (still overridden by NO_COLOR). ColorAlways // ColorNever forces color off. ColorNever )
func ParseColorChoice ¶
func ParseColorChoice(name string) (ColorChoice, bool)
ParseColorChoice parses a choice from its lowercase name (auto/always/never).
The second return value is false for any other value, so the caller can raise its own typed usage error naming the accepted values.
func (ColorChoice) String ¶
func (c ColorChoice) String() string
String returns the canonical lowercase name of the choice.
type Glyphs ¶
type Glyphs struct {
// contains filtered or unexported fields
}
Glyphs is a resolved set of semantic status glyphs.
When Unicode is disabled every accessor returns its ASCII fallback, so the same rendering code stays byte-clean on terminals that cannot display the Unicode symbols. Construct it from a resolved boolean via NewGlyphs, or from the process locale via GlyphsFromEnv.
func GlyphsFromEnv ¶
func GlyphsFromEnv() Glyphs
GlyphsFromEnv resolves a glyph set from the process locale via UnicodeEnvEnabled.
type Palette ¶
type Palette struct {
// contains filtered or unexported fields
}
Palette is a resolved, semantic color palette.
When disabled every style is the identity function, so callers render the same way regardless of terminal capability. Construct it from a resolved boolean via NewPalette, or resolve a ColorChoice against a stream's TTY status via PaletteForStream.
func NewPalette ¶
NewPalette returns a palette with color explicitly enabled or disabled.
func PaletteForStream ¶
func PaletteForStream(choice ColorChoice, isTerminal bool) Palette
PaletteForStream resolves a palette for a specific output stream by folding NO_COLOR, the choice, and the stream's TTY status via ResolveColor.
type Style ¶
type Style struct {
// contains filtered or unexported fields
}
Style bundles a color Palette and a Glyphs set — the two visual capabilities a terminal renderer resolves from NO_COLOR and UTF-8 support — into one value, so renderers thread a single style rather than a separate palette/glyphs pair.
type Theme ¶
type Theme struct {
// contains filtered or unexported fields
}
Theme renders bold headings and right-aligned, Cargo-like action lines keyed by a semantic Tone, on a resolved Palette. It is the semantic styling layer above the raw palette: callers describe intent (a heading, or a toned action) rather than picking colors.
Labels are right-aligned by Unicode scalar count, which matches terminal columns for the ASCII/Latin action verbs it is built for ("Checking", "Compiling"). Column-exact alignment of wide (CJK/emoji) labels is intentionally left to heavier kits.
func (Theme) Action ¶
Action renders a right-aligned, bold semantic action label followed by unstyled detail — the " Checking pkg" form familiar from Cargo. The label is right-aligned to the configured action width; a label wider than that column is emitted whole without padding rather than truncated.
func (Theme) WithActionWidth ¶
WithActionWidth returns a copy of the theme with the right-aligned action-label width (in columns) set; the receiver is unchanged.
Source Files