Skip to content

Getting started

Install

go get gitlab.com/phpboyscout/go/output

The Renderer

Everything starts with a Renderer, built once from options and reused. It holds four things: a destination writer, an output format, a theme, and whether output is interactive.

import "gitlab.com/phpboyscout/go/output"

r := output.New(
    output.WithWriter(os.Stdout),      // default: os.Stderr
    output.WithFormat(output.FormatText), // default: text
    // output.WithTheme(myTheme),      // default: DefaultTheme()
    // output.WithInteractive(true),   // default: auto-detected
)

If you do not call WithInteractive, the renderer auto-detects: interactive when stdout is a TTY and CI is not set to true. Interactive renderers animate; non-interactive ones print plain lines — the same code path works in a terminal and under CI.

Writing data

Write is format-aware. You supply the data and a function that renders the human-readable form; the renderer decides which to use:

type Result struct {
    Name    string `json:"name"    table:"Name,sortable"`
    Version string `json:"version" table:"Version"`
}

r := output.New(output.WithWriter(os.Stdout), output.WithFormat(format))

_ = r.Write(res, func(w io.Writer) {
    fmt.Fprintf(w, "%s %s\n", res.Name, res.Version)
})
Configured format What Write does
text calls your textFunc
json / yaml marshals data directly
csv / tsv / markdown renders data as a table (needs a slice)

Formats

The supported set is text, json, yaml, csv, tsv, markdown.

output.Formats()                 // the canonical slice, stable order
f, ok := output.ParseFormat(s)   // case-exact; ok=false → falls back to FormatText

Formats() is exactly the value set a CLI's --output flag should accept — see the cobra guide, which wires it up for you.

Your first table

rows := []Result{
    {Name: "alpha", Version: "1.2.0"},
    {Name: "beta",  Version: "0.9.1"},
}

r := output.New(output.WithWriter(os.Stdout), output.WithFormat(output.FormatText))
_ = r.Table(rows, output.WithSortBy("Name"))

Columns come from the table:"Header,sortable" struct tags, or pass output.WithColumns(...) explicitly (required for []map[string]any). More in Render a table.

Next