render

Documentation

Overview

Package render turns a stream of record structs into one of the output formats the kit CLI supports: table, 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.

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"
	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)
	Fields   []string  // projection: restrict/reorder columns by name
	NoHeader bool      // omit the header row in table/csv
	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.

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.