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
  • func (s *Config) WithRenderer(r *lipgloss.Renderer) *Config
• type GradientMode
• type JSON
  • func DefaultJSON() *JSON
  • func (s *JSON) WithRenderer(r *lipgloss.Renderer) *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 {
	Renderer *lipgloss.Renderer
	// 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
	// Duration unit -> thresholds (evaluated high->low).
	DurationThresholds ThresholdMap
	// Duration unit -> style override (e.g. "s" -> yellow).
	DurationUnits Map
	// 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
	// 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 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.

func (*Config) WithRenderer

func (s *Config) WithRenderer(r *lipgloss.Renderer) *Config

WithRenderer rebinds all styles to the given renderer. This ensures styles render correctly when the logger's output differs from os.Stdout (e.g. logging to stderr while stdout is piped). It mutates and returns the receiver for fluent chaining.

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) WithRenderer

func (s *JSON) WithRenderer(r *lipgloss.Renderer) *JSON

WithRenderer rebinds all token styles to the given renderer. It mutates and returns the receiver for fluent chaining.

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.