style

Documentation

Overview

Package style provides styling types, color stops, and defaults for clog.

Index

• func InterpolateGradient(t float64, stops []ColorStop) colorful.Color
• func StepGradient(t float64, stops []ColorStop) colorful.Color
• type ColorStop
  • func DefaultElapsedGradient() []ColorStop
  • func DefaultPercentGradient() []ColorStop
• type Config
  • func Default() *Config
• type GradientMode
• type JSON
  • func DefaultJSON() *JSON
  • func (s *JSON) WithSpacing(spacing JSONSpacing) *JSON
• type JSONMode
• type JSONSpacing
• type LevelMap
  • func DefaultMessages() LevelMap
• type Map
• type Threshold
• type ThresholdMap
• type ThresholdStyle
• type Thresholds
• type ValueMap
  • func DefaultValues() ValueMap

Functions

func InterpolateGradient

func InterpolateGradient(t float64, stops []ColorStop) colorful.Color

InterpolateGradient computes the color at position t (0.0-1.0) along the given gradient stops using CIE-LCh blending for perceptually uniform transitions. Edge cases: empty -> white, single stop -> that color, t outside range -> clamp to nearest stop.

func StepGradient

func StepGradient(t float64, stops []ColorStop) colorful.Color

StepGradient returns the color of the last stop whose position is <= t. Edge cases: empty -> white, single stop -> that color, t before first stop -> first stop's color.

Types

type ColorStop

type ColorStop = gradient.ColorStop

ColorStop defines a color at a specific position along a gradient. Position is in the range 0.0-1.0.

func DefaultElapsedGradient

func DefaultElapsedGradient() []ColorStop

DefaultElapsedGradient returns the default green -> yellow -> red gradient used for Config.ElapsedGradient.

func DefaultPercentGradient

func DefaultPercentGradient() []ColorStop

DefaultPercentGradient returns the default red -> yellow -> green gradient used for Config.PercentGradient.

type Config

type Config struct {
	// Style for divider line characters (see [clog.DividerBuilder]) [nil = plain text]
	DividerLine *lipgloss.Style
	// Style for divider title text [nil = plain text]
	DividerTitle *lipgloss.Style
	// Gradient stops for Duration fields (default: green -> yellow -> red).
	// Active only when [duration.GradientMax] > 0; overrides FieldDurationNumber/FieldDurationUnit.
	DurationGradient []ColorStop
	// How duration gradient colors transition: [GradientFade] (smooth) or [GradientStep] (discrete).
	DurationGradientMode GradientMode
	// Duration unit -> thresholds (evaluated high->low).
	DurationThresholds ThresholdMap
	// Duration unit -> style override (e.g. "s" -> yellow).
	DurationUnits Map
	// Gradient stops for Elapsed fields (default: green -> yellow -> red).
	// Active only when [elapsed.GradientMax] > 0; overrides FieldElapsedNumber/FieldElapsedUnit.
	ElapsedGradient []ColorStop
	// How elapsed gradient colors transition: [GradientFade] (smooth) or [GradientStep] (discrete).
	ElapsedGradientMode GradientMode
	// Style for the numeric segments of duration values (e.g. "1" in "1m30s") [nil = plain text]
	FieldDurationNumber *lipgloss.Style
	// Style for the unit segments of duration values (e.g. "m" in "1m30s") [nil = plain text]
	FieldDurationUnit *lipgloss.Style
	// Style for the numeric segments of elapsed-time values [nil = falls back to FieldDurationNumber]
	FieldElapsedNumber *lipgloss.Style
	// Style for the unit segments of elapsed-time values [nil = falls back to FieldDurationUnit]
	FieldElapsedUnit *lipgloss.Style
	// Style for error field values [nil = plain text]
	FieldError *lipgloss.Style
	// Per-token styles for JSON syntax highlighting.
	// nil disables JSON highlighting; use [DefaultJSON] to enable.
	FieldJSON *JSON
	// Style for int/float field values [nil = plain text]
	FieldNumber *lipgloss.Style
	// Base style for Percent fields (foreground overridden by gradient). nil = gradient color only.
	FieldPercent *lipgloss.Style
	// Style for the numeric part of quantity values (e.g. "5" in "5km") [nil = plain text]
	FieldQuantityNumber *lipgloss.Style
	// Style for the unit part of quantity values (e.g. "km" in "5km") [nil = plain text]
	FieldQuantityUnit *lipgloss.Style
	// Style for string field values [nil = plain text]
	FieldString *lipgloss.Style
	// Style for time.Time field values [nil = plain text]
	FieldTime *lipgloss.Style
	// Style for field key names without a per-key override.
	KeyDefault *lipgloss.Style
	// Field key name -> value style (e.g. "path" -> blue).
	Keys Map
	// Level label style (e.g. "INF", "ERR").
	Levels LevelMap
	// Message text style per level.
	Messages LevelMap
	// Gradient stops for Percent fields (default: red -> yellow -> green).
	PercentGradient []ColorStop
	// Quantity unit -> thresholds (evaluated high->low).
	QuantityThresholds ThresholdMap
	// Unit string -> style override (e.g. "km" -> green).
	QuantityUnits Map
	// Style for key/value separator.
	Separator *lipgloss.Style
	// Symbol text style per level (e.g. make "warning" bold yellow).
	// nil entries render the symbol unstyled.
	Symbols LevelMap
	// Style for the timestamp prefix.
	Timestamp *lipgloss.Style
	// Values maps typed values to styles. Keys use Go equality.
	// Allows differentiating between e.g. `true` (bool) and "true" (string).
	Values ValueMap
}

Config holds lipgloss styles for the logger's pretty output. Pointer fields can be set to nil to disable that style entirely.

func Default

func Default() *Config

Default returns the default color styles.

type GradientMode

type GradientMode int

GradientMode controls how gradient colors transition between stops.

const (
	// GradientFade smoothly interpolates between color stops.
	GradientFade GradientMode = iota
	// GradientStep uses discrete color jumps at stop boundaries.
	GradientStep
)

type JSON

type JSON struct {
	// Mode controls rendering behaviour.
	// JSONModeJSON (default) preserves standard JSON quoting.
	// JSONModeHuman strips quotes from identifier-like keys and simple string values.
	// JSONModeFlat flattens nested object keys with dot notation; arrays are kept intact.
	Mode JSONMode
	// OmitCommas omits the comma between items. JSONSpacingAfterComma still
	// applies and can be used to keep a space separator: {"a":1 "b":2}.
	OmitCommas bool
	// Spacing controls where spaces are inserted. Zero (default) means no spaces.
	// Use JSONSpacingAll for {"key": "value", "n": 1} style output.
	Spacing JSONSpacing

	BoolFalse      *lipgloss.Style // false
	BoolTrue       *lipgloss.Style // true
	Key            *lipgloss.Style // Object keys
	Null           *lipgloss.Style // null
	Number         *lipgloss.Style // Numeric values - base fallback for all number sub-styles
	NumberFloat    *lipgloss.Style // Floating-point values; falls back to Number
	NumberInteger  *lipgloss.Style // Integer values; falls back to Number
	NumberNegative *lipgloss.Style // Negative numbers; falls back to Number
	NumberPositive *lipgloss.Style // Positive numbers (with or without explicit sign); falls back to Number
	NumberZero     *lipgloss.Style // Zero; falls back to NumberPositive, then Number
	String         *lipgloss.Style // String values

	Brace       *lipgloss.Style // { } (nested)
	BraceRoot   *lipgloss.Style // { } (outermost object; falls back to Brace if nil)
	Bracket     *lipgloss.Style // [ ] (nested)
	BracketRoot *lipgloss.Style // [ ] (outermost array; falls back to Bracket if nil)
	Colon       *lipgloss.Style // :
	Comma       *lipgloss.Style // ,
}

JSON configures per-token lipgloss styles for JSON syntax highlighting. nil fields render the corresponding token unstyled.

Use DefaultJSON as a starting point for customization.

func DefaultJSON

func DefaultJSON() *JSON

DefaultJSON returns dracula-inspired lipgloss styles for JSON tokens. True and False mirror the default value styles (green/red) for consistency.

func (*JSON) WithSpacing

func (s *JSON) WithSpacing(spacing JSONSpacing) *JSON

WithSpacing returns the receiver with the given spacing flags applied. It modifies and returns the same pointer for fluent chaining:

styles.FieldJSON = style.DefaultJSON().WithSpacing(style.JSONSpacingAll)

type JSONMode

type JSONMode int

JSONMode controls how JSON is rendered.

const (
	// JSONModeJSON renders standard JSON (default).
	JSONModeJSON JSONMode = iota
	// JSONModeHuman renders in HJSON style: keys and simple string values are
	// unquoted, making output more readable at a glance.
	JSONModeHuman
	// JSONModeFlat flattens nested object keys using dot notation and renders
	// scalar values without unnecessary quotes. Arrays are kept intact.
	// Example: {"user":{"name":"alice"},"tags":["a","b"]}
	//       →  {user.name:alice,tags:[a,b]}
	JSONModeFlat
)

type JSONSpacing

type JSONSpacing uint

JSONSpacing is a bitmask controlling where spaces are inserted in JSON output.

const (
	// JSONSpacingAfterColon inserts a space after each colon: {"key": "value"}.
	JSONSpacingAfterColon JSONSpacing = 1 << iota
	// JSONSpacingAfterComma inserts a space after each comma: {"a": 1, "b": 2}.
	JSONSpacingAfterComma
	// JSONSpacingBeforeObject inserts a space before a nested object value: {"key": {"n":1}}.
	JSONSpacingBeforeObject
	// JSONSpacingBeforeArray inserts a space before a nested array value: {"tags": ["a","b"]}.
	JSONSpacingBeforeArray
	// JSONSpacingAll enables all spacing options.
	JSONSpacingAll = JSONSpacingAfterColon | JSONSpacingAfterComma | JSONSpacingBeforeObject | JSONSpacingBeforeArray
)

type LevelMap

type LevelMap = map[level.Level]*lipgloss.Style

LevelMap maps log levels to lipgloss styles.

func DefaultMessages

func DefaultMessages() LevelMap

DefaultMessages returns the default per-level message styles (unstyled).

type Map

type Map = map[string]*lipgloss.Style

Map maps string keys to lipgloss styles (e.g. field key names or unit strings).

type Threshold

type Threshold struct {
	Value float64        // Minimum numeric value (inclusive) to trigger this style.
	Style ThresholdStyle // Style overrides for number and unit segments.
}

Threshold defines a style override when a quantity's numeric value meets or exceeds the given threshold. Thresholds are evaluated in descending order - the first match wins.

type ThresholdMap

type ThresholdMap = map[string]Thresholds

ThresholdMap maps unit strings to their thresholds (evaluated high -> low).

type ThresholdStyle

type ThresholdStyle struct {
	Number *lipgloss.Style // Override for the number segment (nil = keep default).
	Unit   *lipgloss.Style // Override for the unit segment (nil = keep default).
}

ThresholdStyle holds optional style overrides for the number and unit segments of a quantity or duration value. nil fields keep the default style.

type Thresholds

type Thresholds = []Threshold

Thresholds is a list of Threshold entries, evaluated high -> low (first match wins).

type ValueMap

type ValueMap = map[any]*lipgloss.Style

ValueMap maps typed values to lipgloss styles. Keys use Go equality (e.g. bool true != string "true").

func DefaultValues

func DefaultValues() ValueMap

DefaultValues returns sensible default styles for common value strings.