theme

Documentation

Overview

Package theme — filter.go: byte-level ANSI SGR rewriter.

Kept dependency-free (no regexp) so the per-write overhead stays tiny — the filter sits on the hot path of every Printf in the codebase.

Package theme — install.go: optional os.Stdout / os.Stderr interception that pipes every write through Filter for the active mode. Skipped entirely for ModeBright so the default code path stays a true zero-cost passthrough.

Package theme resolves the active terminal color palette and installs an ANSI rewrite filter on stdout / stderr so every existing Print / Printf call adapts to the user's --theme choice without per-site changes.

Three modes:

• bright (default): passthrough — the bright + bold ANSI palette baked into constants.Color* is what the user sees.
• standard: downgrade bright codes to plain 3X codes (the pre-v5.13 look) for users on light themes or older terminals where bright-bold is too loud.
• monochrome / mono: strip every SGR escape so output stays readable when piped into tools that don't grok ANSI (diff, less without -R, log scrapers).

Resolution order (first wins):

1. `--theme=<mode>` / `--theme <mode>` on the command line (stripped from os.Args by cmd.stripThemeFlag before subcommand dispatch).
2. GITMAP_THEME env var (also exported by the flag stripper so subprocesses inherit the choice).
3. constants.ThemeDefault.

Index

• func Drain()
• func Filter(p []byte, mode Mode) []byte
• func Install()
• func IsStderrTTY() bool
• func IsStdoutTTY() bool
• func IsValidLabel(label string) bool
• type Mode
  • func Active() Mode
  • func Parse(label string) Mode
  • func Resolve() Mode
  • func (m Mode) String() string

Functions

func Drain

func Drain()

Drain closes every installed pipe writer and waits for the matching forwarder goroutine to flush its buffered bytes to the underlying destination fd. MUST be called before os.Exit when output integrity matters (e.g. cliexit.Fail) — otherwise the last failure message can vanish on Windows.

func Filter

func Filter(p []byte, mode Mode) []byte

Filter applies the active mode's transformation to p. Bright mode is a passthrough; other modes scan for SGR escape sequences (ESC `[` ... `m`) and rewrite or drop them.

func Install

func Install()

Install resolves the active mode from the environment and, if it is not ModeBright, replaces os.Stdout and os.Stderr with pipe-backed writers whose reader-side goroutines apply Filter before forwarding bytes to the original fds. Safe to call multiple times — runs at most once per process.

func IsStderrTTY

func IsStderrTTY() bool

IsStderrTTY is the stderr counterpart of IsStdoutTTY.

func IsStdoutTTY

func IsStdoutTTY() bool

IsStdoutTTY reports whether the *original* stdout (before any theme pipe interception) is a real terminal. Callers in gitmap/render gate ANSI pretty-rendering on this so the monochrome / standard pipe wrappers don't break TTY detection.

func IsValidLabel

func IsValidLabel(label string) bool

IsValidLabel reports whether label names a known theme. Used by the flag stripper to reject typos with a clear error instead of silently falling back.

Types

type Mode

type Mode int

Mode is the resolved palette selection.

const (
	// ModeBright is the loud bright+bold palette (default).
	ModeBright Mode = iota
	// ModeStandard is the muted pre-v5.13 plain palette.
	ModeStandard
	// ModeMono strips all ANSI SGR codes.
	ModeMono
)

func Active

func Active() Mode

Active returns the mode chosen at Install time. Defaults to ModeBright when Install has not yet been called.

func Parse

func Parse(label string) Mode

Parse maps a user-supplied label to a Mode. Unknown labels (and the empty string) fall back to ModeBright so a typo never crashes a CLI run — they just render in the default palette.

func Resolve

func Resolve() Mode

Resolve picks the active mode from env (set by the flag stripper or the user's shell). Called once at startup by Install.

func (Mode) String

func (m Mode) String() string

String returns the canonical lowercase label for the mode.