tuitheme

Overview ¶

Package tuitheme reads the TUI theme file: the colors and styles a terminal program draws its interface, markdown and code in, keyed by role. A theme generator writes one per theme, and every program on this package reads the same file, so one theme change recolors them all.

The format is JSON with three groups, ui, markdown and syntax. A value is "#rrggbb", a terminal palette slot from "0" to "15", or a style object of fg, bg, bold, italic, underline, strikethrough and dim. The schema published beside this package documents every key:

https://raw.githubusercontent.com/datapointchris/gotermstyle/main/tuitheme/schema/v1.json

A role is a group and a key, such as "ui.selection" or "syntax.keyword.return". A key the file leaves out falls back along its dots, then to the built-in default. The default is written in palette slots, so a program with no theme file draws in the terminal's own 16 colors.

Every program finds the same file through DefaultPath. TUI_THEME_FILE points them all at another one, such as a theme under test.

Load a theme once, paint each role through a gotermstyle.Palette, and load it again when Notify relays a reload. Load always returns a theme to draw. On an error it is the built-in default, and a program reloading keeps its own:

path, err := tuitheme.DefaultPath()
if err != nil {
	return err
}
theme, err := tuitheme.Load(path)
if err != nil {
	log.Print(err) // theme is the built-in default
}
fmt.Println(pal.Paint(theme.Code("ui.selection"), row))

reloads := make(chan os.Signal, 1)
tuitheme.Notify(reloads)
for range reloads {
	if next, err := tuitheme.Load(path); err == nil {
		theme = next
	}
}

A Theme never changes once loaded, so it is safe to share between goroutines.