gotermstyle

README

gotermstyle

A Go library that styles a command-line tool's output. It holds a fixed palette, a boxed section header, a help-screen grammar, and the rule for when any of it reaches the terminal. Its tuitheme package reads the theme file a terminal UI draws its colors from. Its purpose is a Go tool whose help screen looks the same as its Python and bash neighbors on PATH. Those neighbors are styled by pytermstyle and formatting.sh. The section on the other two says where each lives.

It renders and does nothing else. The caller keeps its command framework and its execution. The root package is called from inside the caller's help function; cobrahelp.Install replaces that function instead. Real layout belongs to lipgloss, which has tables, lists, layers and wide-rune width. None of those are here.

Something belongs in this package only if two tools would otherwise write it identically and a difference would show on screen. Domain logic and configuration stay in the tool. So does anything one tool could own alone.

The root package imports nothing outside the standard library, by its own choice. cobrahelp, the cobra frontend, is the one package that imports cobra and pflag, so a tool importing only the root compiles neither.

Install

go get github.com/datapointchris/gotermstyle@latest

Releases are git tags on the 0.x line. Under semantic versioning, a 0.x minor release may change the API.

The module's go line becomes the floor of every module that imports it. go get raises a lower go line to match. This prints the floor:

go list -m -f '{{.GoVersion}}' github.com/datapointchris/gotermstyle@latest

Starting from scratch

Save this as main.go in an empty directory:

package main

import (
    "os"

    "github.com/datapointchris/gotermstyle"
)

func main() {
    s := gotermstyle.New(os.Stdout)

    s.HelpHeader("hello", "Greet people from the terminal.")
    s.HelpUsage("hello <verb>")

    s.HelpSection("Commands")
    s.HelpRow("hello greet", "<name>", "Greet one person")
    s.HelpRow("hello list", "", "List everyone greeted")

    s.HelpEnd()
}

Then, from that directory:

go mod init example.com/hello    # a module to import it into
go mod tidy                      # resolves the import and records its checksums in go.sum
go run .                         # cyan rules and names, because stdout is a terminal
go run . | cat                   # the same screen uncolored, because a pipe is not a terminal
NO_COLOR=1 go run .              # uncolored, because the user's preference outranks everything
FORCE_COLOR=1 go run . | cat -v  # the escape codes made visible, proving they reached the bytes

Color is emitted only where something will render it. New resolves that once, against the writer it is given. FORCE_COLOR overrides the terminal detection for a caller who knows it is wrong. A CI log that renders escapes is one case. A pager run with -R is another. NO_COLOR still wins, because it is the user's preference and FORCE_COLOR only corrects the detection.

A writer that is not an *os.File, such as a bytes.Buffer, never gets color from New. A test that asserts on the codes builds its own palette: gotermstyle.NewWith(&buf, gotermstyle.NewPalette(true)).

go doc -all github.com/datapointchris/gotermstyle prints the whole API. Run it inside a module that requires the package.

Screen — rows buffer per section, so no call site passes a width or a color

In a cobra tool, the screen is drawn from the function given to SetHelpFunc, against cmd.OutOrStdout():

root.SetHelpFunc(func(cmd *cobra.Command, _ []string) {
    s := gotermstyle.New(cmd.OutOrStdout())

    s.HelpHeader("lab", "Small experiments worth revisiting.")
    s.HelpUsage("lab <verb>")

    s.HelpSection("Commands")
    s.HelpRow("lab list", "", "List every lab")
    s.HelpRow("lab show", "<id>", "Show one lab")
    s.HelpRow("", "", "An id comes from list") // continues the row above

    s.HelpEnd()
})

HelpRow buffers rather than writing. The next HelpSection, HelpText or HelpEnd flushes the buffer. The flush sizes the description column from the longest name and arguments in the section. A row with an empty name continues the row above it, with its description aligned and no color.

HelpText prints prose between rows. It flushes first, so pending rows land above the prose rather than under it. HelpEnd closes the screen and resets it for the next one.

The Usage: label belongs to the library, so every screen labels it the same. Extra usage lines align under the first. Header draws a boxed header over a command's own output, outside a help screen.

A section's underline takes its color from the heading's name first and its position second. The headings most tools share keep one color everywhere, because a color is learnable across tools only if it never shifts. Commands is cyan, Options is magenta, and Examples is yellow. fixedSections in color.go holds the full mapping. A heading the tool invents rotates through green, blue and white by position, so neighbors differ. Rows under Examples render in the command color, because an example is a command you would type.

Palette — color is decided once per stream, never at a call site

p := gotermstyle.PaletteFor(os.Stdout)     // decide once, against the stream
fmt.Println(p.Cyan(name), p.Command(path)) // paint with the decision

Re-deciding at each call site is how one screen ends up half colored. Resolve the palette once and pass it around. Inside a help screen, s.Palette() is the screen's own.

The gate runs in a fixed order. NO_COLOR turns color off. FORCE_COLOR turns it on. TERM=dumb turns it off. Otherwise color is on only when the writer is an *os.File on a character device. That check is os.Stat plus os.ModeCharDevice, so it needs no golang.org/x/term.

The codes are terminal-palette codes rather than RGB. A 16-color terminal renders them in its theme's colors, so nothing degrades a color profile. The command color is the one non-bright code, so a command you would type reads differently from a name in a listing. Code returns a code or the empty string for a caller building a string by interpolation. On reports whether the palette emits color.

There is no dim. Its contrast is whatever the terminal theme makes it, and on many themes it is unreadable.

Clip and alignment — widths are counted in runes, on the uncolored text

rest := gotermstyle.Clip(path, utf8.RuneCountInString(prefix)) // measure plain text
fmt.Println(prefix + p.Command(rest))                          // color after clipping

Clip(text, used) shortens text to fit the terminal beside used other columns. Pass the width of the uncolored surrounding text and color the result afterwards. A clip then cannot land inside an escape sequence. With fewer than two columns of room, Clip returns the text whole. An overflowing row says more than a bare ellipsis.

Columns reads $COLUMNS first, then the terminal on stdout, then DefaultColumns. That is the order Python's shutil.get_terminal_size uses. The terminal query is a TIOCGWINSZ ioctl through the standard library's syscall. It runs on Linux, macOS and the BSDs, Android and iOS included. Everywhere else $COLUMNS or the default answers.

Pad a colored column by hand. text/tabwriter counts an escape sequence as visible width, so one colored cell shifts every column after it. A padded fmt verb has the same fault:

fmt.Fprintf(w, "%-*s  %s\n", width, p.Cyan(name), address) // wrong: the width counts the escape

gap := strings.Repeat(" ", width-utf8.RuneCountInString(name))
fmt.Fprintf(w, "%s%s  %s\n", p.Cyan(name), gap, address)

Widths are runes, the unit Python's len counts on a str. A multibyte name aligns the same here as in pytermstyle. Both assume a wide rune or a grapheme cluster is one column, so CJK and emoji misalign. That is the one thing lipgloss would buy, and this package accepts the gap deliberately.

cobrahelp — one call renders every screen of a cobra tree

import "github.com/datapointchris/gotermstyle/cobrahelp"

cobrahelp.Install(root)

Every screen then says what the command is, and lists every leaf command beneath it. A command with children gets no row of its own, even one that runs. Each row is spelled from the screen's own command down to the leaf, arguments included, so a command three levels down is on the root rather than three screens away. The examples and flags follow. A section is a group the command declares with AddGroup, and commands keep the order the tree adds them, so Install turns off cobra's alphabetical sorting for every command tree in the process. A command no group claims sits under "Other commands". Descriptions wrap at 80 columns, and a command line wider than 40 sits alone with its description beneath.

It replaces cobra's help and usage templates outright rather than patching their rows. Cobra's template gives a namespace a Usage: <cmd> [command] block, which a first-time reader takes for the answer, and puts the examples above the commands.

tuitheme — every terminal UI reads its colors from one theme file

import "github.com/datapointchris/gotermstyle/tuitheme"

path, err := tuitheme.DefaultPath()
if err != nil {
    return err
}
theme, err := tuitheme.Load(path) // a missing file is the built-in default, with no error
if err != nil {
    log.Print(err) // theme is the built-in default, so the screen still draws
}
fmt.Println(pal.Paint(theme.Code("ui.selection"), row)) // pal is a gotermstyle.Palette

reloads := make(chan os.Signal, 1)
tuitheme.Notify(reloads) // SIGUSR2 asks for the file again
for range reloads {
    if next, err := tuitheme.Load(path); err == nil {
        theme = next // on an error, keep drawing the theme on screen
    }
}

The 16 terminal colors hold no shade near the background, so a selected row drawn in them is a reversed slab. A theme file gives a program the theme's own selection, panel and accent colors. A theme generator writes one file per theme, and every program on this package reads the same one.

The file is JSON in three groups. ui holds the interface's roles, markdown holds Neovim's @markup captures, and syntax holds tree-sitter captures. A value is "#rrggbb", a palette slot from "0" to "15", or a style object of fg, bg, bold, italic, underline, strikethrough and dim:

{
  "$schema": "https://raw.githubusercontent.com/datapointchris/gotermstyle/main/tuitheme/schema/v1.json",
  "ui": { "accent": "#4eb6fe", "selection": { "fg": "#c5c8c6", "bg": "#373b41" } },
  "markdown": { "heading": { "fg": "#4eb6fe", "bold": true } },
  "syntax": { "keyword": "#b294bb", "keyword.return": { "fg": "#b294bb", "bold": true } }
}

tuitheme/schema/v1.json describes every key. An editor validates and completes a file against it through $schema.

• Every key is optional. A missing key falls back along its dots, so markdown.heading.2 takes markdown.heading. Then it takes the built-in default, tuitheme/default.json.
• The built-in default is written in palette slots. A program with no theme file draws in the terminal's own 16 colors.
• A group, key or style field the reader does not know is ignored, so a newer file never breaks an older program. A value of neither form fails the load, and the error names its key. null and "" are neither form.
• The format only grows. A new value form arrives as a new key or style field, never in place of an old one. A change no older program could read is a new file beside current.json, with a schema of its own. A generator writes both, so a program built for v1 keeps its colors.
• DefaultPath is $TUI_THEME_FILE when set, else $XDG_CONFIG_HOME/tui-theme/current.json, else ~/.config/tui-theme/current.json. TUI_THEME_FILE points every program at another file at once, such as a theme under test.
• Load always returns a theme to draw. On an error it is the built-in default, so a program starting up draws the terminal's 16 colors and reports the error. A program reloading keeps the theme it has.
• Code is one SGR sequence opening with a reset, as the house palette's codes do. An exact color is 24-bit, which most terminals and tmux with its RGB feature render.
• Color.BackgroundCode sets a background alone, with no reset, so a program can lay a selection's background under cells that keep their own colors.
• dim is drawn when a file asks for it. The built-in default never does.

Notify relays SIGUSR2 on unix and nothing elsewhere. The program loads the file again when it arrives, which re-resolves a current.json symlink. A Go program that never called Notify catches SIGUSR2 and ignores it. So a generator can signal every process of a reader's name, CLI runs included.

Why this exists — cobra renders help with no notion of style

A Go tool on cobra prints its help monochrome. A Python tool on Typer and Rich prints its help in color. So does a bash script that sources formatting.sh.

The gap follows the stack rather than the tool, so it wants one answer per stack. Typer renders help through Rich, and color arrives with it. Cobra renders help through text/template. A template emits plain strings and has no notion of a style it could apply or strip, so nothing arrives for free.

Why not a third-party library — none matches the neighbors at zero cost

Good libraries exist. lipgloss is the Go peer of Rich. Its tables, lists, layers and ANSI-aware width do more than this package does.

The value bought here is narrower. It is a Go screen that looks the same as its Python and bash neighbors on PATH, from a root package that imports only the standard library. Three alternatives were weighed against that:

• charmbracelet/fang owns command execution. fang.Execute wraps the root command's ExecuteContext, which a tool with a self-update wrapper already owns. It installs its own help function, so a help template or help function the tool set is bypassed. Its theme is Charm's house style, in lipgloss colors that switch between light and dark variants. Fixed ANSI codes are a different model. Its README calls it experimental.
• ivanpirog/coloredcobra is the closest drop-in and loses the least. It rewrites cobra's usage template with regular expressions, and a tool may already patch that template. It does nothing for grouping or row width. Two things mutating one template that cobra is free to change is worse than one thing owned outright.
• lipgloss by hand gives the most control for the most code. Its value here would be wide-rune width alone.

Typer is the counter-example that settled it. Its Rich renderer styles help text, option defaults and panel borders dim. Dim therefore reaches every Typer help screen, and no source file in the tool asks for it. A framework that renders for you applies its opinions where no source grep will find them.

Relationship to the other two — the same screen, not the same bytes

Language	Library	Lives in
Go	gotermstyle	this repo
Python	pytermstyle	datapointchris/pytermstyle
bash	formatting.sh + colors.sh	configs/common/.local/shell/ in datapointchris/dotfiles

The three emit the same escape codes for the same roles. The Go tests assert each code as a literal, and no test reads the other two libraries. A change to the palette is a change to all three.

The bytes differ in two places. pytermstyle and formatting.sh open a help row's color before its two-space indent, and Go opens it after. They also write a reset on a continuation row, which opens no color, and Go writes none.

The API differs from the Python in one place. pytermstyle and formatting.sh keep the buffered rows and the section counter in globals, so pytermstyle's tests must reset them between screens. Go runs its tests in one process and its programs concurrently, so that state lives on a Screen here.

License

MIT.

Documentation

Overview

Package gotermstyle is the house terminal style for the Go command-line tools.

It is the Go counterpart to two things that already exist: pytermstyle (https://github.com/datapointchris/pytermstyle) for the Python tools, and formatting.sh for the bash ones. The README says where each lives. The parallel is the point — a Go screen, a Python screen and a bash screen sitting next to each other on PATH should be indistinguishable, which is a property no third-party styling library can provide, because each brings its own aesthetic.

Scope

The palette, the section header, the help grammar, and the rules about when any of it is emitted at all. Beside them, tuitheme reads the colors every terminal UI on this module shares. Not domain logic, not a tool's own configuration, not anything a single tool could own instead.

The membership test: it belongs here only if two tools would otherwise write it identically *and* writing it differently would be visible on screen. Everything else stays in the tool. The package is named for the language rather than for a caller, because a style package named for one family of tools ends up holding the house style for all of them.

Dependencies

None in this package, and that is a constraint rather than a coincidence. Terminal detection is os.Stat plus os.ModeCharDevice, not golang.org/x/term, so a tool importing this package builds no other module. The subpackage cobrahelp is the cobra frontend, kept apart so cobra reaches only a tool that imports it. The module's go.mod names cobra for cobrahelp, so an importer's module graph lists cobra while its build compiles none of it. The subpackage tuitheme reads the theme file a terminal UI draws from, and imports only the standard library.

The go line in this module's go.mod does become the importer's floor, and go get raises a lower one to match. This prints it:

go list -m -f '{{.GoVersion}}' github.com/datapointchris/gotermstyle@latest

Using it

Resolve a Screen against the writer the output is going to, then render:

s := gotermstyle.New(cmd.OutOrStdout())
s.HelpHeader("lab", "Small experiments worth revisiting.")
s.HelpUsage("lab <verb>")

s.HelpSection("Commands")
s.HelpRow("lab list", "", "List every lab")
s.HelpRow("lab show", "<id>", "Show one lab")

s.HelpEnd()

HelpRow buffers rather than writing, so the flush sizes the description column from the longest row in the section. No call site passes a width or a color. Use HelpText rather than writing directly for prose between rows, so pending rows flush ahead of it.

For output that is not a help screen, Palette paints and Clip fits:

p := gotermstyle.PaletteFor(os.Stdout)
fmt.Println(p.Cyan(name), p.Command(path))

Where the state lives, and why it differs from the Python

pytermstyle and formatting.sh keep the buffered rows and the section counter in globals, which is affordable in a one-shot CLI and costs pytermstyle a reset helper its tests have to call. Go runs its tests in one process and its programs concurrently, so that state lives on a Screen here. The rendered screen is the same; only the state's owner differs.

The libraries that were considered and rejected, and why, are in the README.

Index

• Constants
• func Clip(text string, used int) string
• func Columns() int
• func Enabled(w io.Writer) bool
• func SectionColor(title string, index int) string
• type Palette
  • func NewPalette(enabled bool) Palette
  • func PaletteFor(w io.Writer) Palette
  • func (p Palette) Blue(text string) string
  • func (p Palette) Bold(text string) string
  • func (p Palette) Code(code string) string
  • func (p Palette) Command(text string) string
  • func (p Palette) Cyan(text string) string
  • func (p Palette) Green(text string) string
  • func (p Palette) Magenta(text string) string
  • func (p Palette) On() bool
  • func (p Palette) Paint(code, text string) string
  • func (p Palette) Red(text string) string
  • func (p Palette) White(text string) string
  • func (p Palette) Yellow(text string) string
• type Screen
  • func New(w io.Writer) *Screen
  • func NewWith(w io.Writer, p Palette) *Screen
  • func (s *Screen) Header(title string)
  • func (s *Screen) HelpEnd()
  • func (s *Screen) HelpHeader(name, tagline string)
  • func (s *Screen) HelpRow(name, args, description string)
  • func (s *Screen) HelpSection(title string)
  • func (s *Screen) HelpText(lines ...string)
  • func (s *Screen) HelpUsage(lines ...string)
  • func (s *Screen) Palette() Palette

Constants

const (
	CodeCyan    = "\033[0;96m"
	CodeYellow  = "\033[0;93m"
	CodeGreen   = "\033[0;92m"
	CodeRed     = "\033[0;91m"
	CodeBlue    = "\033[0;94m"
	CodeMagenta = "\033[0;95m"
	CodeWhite   = "\033[0;97m"
	// CodeCommand is the one non-bright entry. A command you would type reads
	// differently from a name in a listing, and that difference is the point.
	CodeCommand = "\033[0;36m"
	CodeBold    = "\033[1m"
	CodeReset   = "\033[0m"
)

The house palette, as the escape sequences themselves. These are the codes the bash library's colors.sh exports and pytermstyle interpolates, so a Go screen, a Python screen and a bash screen sitting next to each other on PATH are the same product.

They are terminal-palette codes rather than absolute RGB, which is why no color-profile degradation is needed: a 16-color terminal renders them correctly, and TERM=dumb is handled by the gate instead.

There is deliberately no dim. Its contrast is whatever the terminal theme makes it, and on many themes it is unreadable.

const Bar = "" /* 150-byte string literal not displayed */

Bar is the rule a header draws above and below its title.

const DefaultColumns = 80

DefaultColumns is the width assumed when nothing will say what it really is.

Functions

func Clip

func Clip(text string, used int) string

Clip shortens text to fit the terminal alongside used other columns.

Callers pass the length of the uncolored surrounding text and color the result afterwards, so a clip can never land inside an escape sequence and leak a raw code onto the screen.

With no room to say anything the text is returned whole: truncating to a bare ellipsis loses more than it saves, and a row that overflows is more use than a row that says nothing.

Every character this clips around is assumed one column wide. That holds for the ↳ · … this family is built for and does not hold for CJK or emoji, which is the one thing a wide-rune library would buy and is a deliberate acceptance rather than an oversight.

func Columns

func Columns() int

Columns is the terminal width. $COLUMNS is consulted first so a caller can override it and a test can set it, then the terminal itself, then DefaultColumns.

This is the order Python's shutil.get_terminal_size uses, which is what the counterpart library resolves through.

func Enabled

func Enabled(w io.Writer) bool

Enabled reports whether escape sequences written to w will reach something that can render them.

NO_COLOR is the user saying they do not want color (no-color.org), so it wins outright. FORCE_COLOR answers a different question — "is this a terminal" — for a caller that knows the detection is wrong: a CI log that renders escapes, a pager invoked with -R, a test that needs the codes in order to assert on them. Preference beats detection, so NO_COLOR is first.

The terminal check is os.Stat plus os.ModeCharDevice rather than golang.org/x/term, which would cost this package the zero-dependency guarantee it is built around.

func SectionColor

func SectionColor(title string, index int) string

SectionColor is the code a section heading renders in, by name first and by position second. Matching is case-insensitive because a heading is written for a reader rather than for this lookup.

Types

type Palette

type Palette struct {
	// contains filtered or unexported fields
}

Palette decides whether the codes above are emitted. Resolve it once, against the stream the output is going to, and pass it around — re-deciding per call site is how one screen ends up half-colored.

func NewPalette

func NewPalette(enabled bool) Palette

NewPalette returns a palette that emits color, or does not.

func PaletteFor

func PaletteFor(w io.Writer) Palette

PaletteFor resolves the gate against w. This is the constructor to reach for; NewPalette is for a caller that has already decided, and for tests.

func (Palette) Blue

func (p Palette) Blue(text string) string

func (Palette) Bold

func (p Palette) Bold(text string) string

func (Palette) Code

func (p Palette) Code(code string) string

Code returns the sequence when color is on and the empty string when it is not, so an interpolating caller can use the constants directly.

func (Palette) Command

func (p Palette) Command(text string) string

func (Palette) Cyan

func (p Palette) Cyan(text string) string

The named colors, for the call sites that read better without the constant.

func (Palette) Green

func (p Palette) Green(text string) string

func (Palette) Magenta

func (p Palette) Magenta(text string) string

func (Palette) On

func (p Palette) On() bool

On reports whether this palette emits color. A caller building a string by interpolation rather than through Paint needs to ask.

func (Palette) Paint

func (p Palette) Paint(code, text string) string

Paint wraps text in code and resets after it. An empty code returns the text untouched, which is what a continuation row wants.

func (Palette) Red

func (p Palette) Red(text string) string

func (Palette) White

func (p Palette) White(text string) string

func (Palette) Yellow

func (p Palette) Yellow(text string) string

type Screen

type Screen struct {
	// contains filtered or unexported fields
}

Screen renders one help screen to one writer.

It carries the buffered rows and the section counter that pytermstyle and formatting.sh both keep in globals. Go runs its tests in one process and its programs concurrently, so a value is the same code without the reset helper those two need, and makes concurrent use a non-question. It draws the screen those two draw; only where the state lives differs.

func New

func New(w io.Writer) *Screen

New returns a Screen writing to w, with color resolved once against w.

func NewWith

func NewWith(w io.Writer, p Palette) *Screen

NewWith returns a Screen using a palette the caller has already resolved. A tool that renders to several streams resolves once and shares it; a test asserts on the codes by passing NewPalette(true).

func (*Screen) Header

func (s *Screen) Header(title string)

Header draws a boxed section header: rule, title, rule, blank line. This is the standalone header a command prints over its own output, not the one that opens a help screen.

func (*Screen) HelpEnd

func (s *Screen) HelpEnd()

HelpEnd closes the screen and resets it for the next one.

func (*Screen) HelpHeader

func (s *Screen) HelpHeader(name, tagline string)

HelpHeader opens a help screen. The blank line leads rather than trails, which is what separates the screen from the command that asked for it.

func (*Screen) HelpRow

func (s *Screen) HelpRow(name, args, description string)

HelpRow buffers one row. Nothing is written until the section ends, because the description column is sized from the longest row in the section and no call site should have to pass a width.

A row with an empty name is a continuation of the one above it.

func (*Screen) HelpSection

func (s *Screen) HelpSection(title string)

HelpSection opens a section, flushing whatever rows the previous one buffered.

func (*Screen) HelpText

func (s *Screen) HelpText(lines ...string)

HelpText prints prose between rows. It flushes first, so a line written after a row cannot appear above it.

func (*Screen) HelpUsage

func (s *Screen) HelpUsage(lines ...string)

HelpUsage prints the invocation lines. The "Usage: " label belongs to this library rather than to the caller, so every screen it draws labels it identically. Extra lines align under the first.

func (*Screen) Palette

func (s *Screen) Palette() Palette

Palette is the resolved palette, for the parts of a screen this grammar does not render.