render

Documentation

Overview

Package render turns a stream of record structs into one of the output formats the kit CLI supports: table, markdown, json, jsonl, csv, tsv, url, raw, and a Go text/template. It works off struct reflection and the `table:` and `json:` tags, so any record type renders without per-type code. It holds no domain knowledge and is reusable on its own.

The table and markdown formats are drawn with lipgloss. table is a rounded-border, color-aware grid meant for a terminal; markdown is a GitHub-flavored pipe table meant for pasting into docs, issues, and READMEs. Both buffer their rows and draw once on Flush so every column sizes to its widest cell.

The list format is the readable alternative to a grid: each record becomes a short section — a heading drawn from the first column, then the rest as a "- **key**: value" bullet list — and records stream as they arrive rather than buffering, so a slow command stays responsive. On a terminal (color on) the markdown markers give way to ANSI styling for a clean detail view; piped (color off) it emits literal GitHub-flavored markdown.

Tag grammar (on a struct field):

table:"name"            include in the table/csv view under column "name"
table:"name,truncate"   truncate long values to the terminal width
table:"name,time"       format a time.Time as 2006-01-02 15:04
table:"name,url"        mark the canonical URL column (used by the url format)
table:"-"               never show in table/csv (still present in json)
(no table tag)          fall back to the json tag name

Index

• type Format
• type Options
• type Record
• type Renderer
  • func New(o Options) (*Renderer, error)
  • func (r *Renderer) Emit(rec any) error
  • func (r *Renderer) Flush() error
  • func (r *Renderer) Format() Format
  • func (r *Renderer) Write(b []byte) (int, error)

Types

type Format

type Format string

Format is an output encoding.

const (
	Auto     Format = "auto"
	Table    Format = "table"
	Markdown Format = "markdown"
	List     Format = "list"
	JSON     Format = "json"
	JSONL    Format = "jsonl"
	CSV      Format = "csv"
	TSV      Format = "tsv"
	URL      Format = "url"
	Raw      Format = "raw"
	Template Format = "template"
)

type Options

type Options struct {
	Format   Format    // the encoding; Auto resolves to Table on a TTY else JSONL
	IsTTY    bool      // whether the writer is an interactive terminal (for Auto)
	Color    bool      // emit ANSI color (table/list accents, JSON highlighting); kit resolves --color
	Fields   []string  // projection: restrict/reorder columns by name
	NoHeader bool      // omit the header row in table/csv/markdown, and the heading in list
	Template string    // when set, format becomes Template
	Width    int       // truncation width for `truncate` columns (0 = no limit)
	Writer   io.Writer // destination
}

Options configure a Renderer.

type Record

type Record struct {
	Cols  []string
	Vals  []string
	Value any
}

Record is a row a command has already projected: an explicit ordered column set (Cols/Vals) for the table, csv, tsv, and url formats, plus the original Value rendered by json, jsonl, raw, and template. A command emits a Record when its table columns differ from its JSON shape, or when the row comes from a dynamic map that struct reflection cannot plan. Emit handles it like any record; when Value is nil it falls back to a map of the columns.

type Renderer

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

Renderer renders records incrementally; one instance handles a whole run so streaming formats write as records arrive. The grid formats (table, markdown) instead buffer their rows and draw once on Flush.

func New

func New(o Options) (*Renderer, error)

New builds a Renderer, resolving Auto and compiling any template.

func (*Renderer) Emit

func (r *Renderer) Emit(rec any) error

Emit renders one record. A record is either a struct (rendered by reflection and its `table:`/`json:` tags) or a Record with explicit columns.

func (*Renderer) Flush

func (r *Renderer) Flush() error

Flush finalizes buffered formats. Call once at the end of a run.

func (*Renderer) Format

func (r *Renderer) Format() Format

Format returns the resolved format.

func (*Renderer) Write

func (r *Renderer) Write(b []byte) (int, error)

Write sends raw bytes straight to the underlying writer, bypassing all formatting, so a Renderer doubles as the io.Writer for a command that emits an opaque blob (a page body, extracted text) alongside any structured rows.