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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterEncoder ¶ added in v0.4.1
func RegisterEncoder(f Format, factory EncoderFactory)
RegisterEncoder teaches kit a format it does not ship, by registering a RowEncoder factory for it. A CLI calls this from an init function (for example to add "parquet") so the encoding dependency lives in the CLI, not in kit. The factory is used only when a run resolves to that exact format.
Types ¶
type EncoderFactory ¶ added in v0.4.1
type EncoderFactory func(w io.Writer, o Options) (RowEncoder, error)
EncoderFactory builds a RowEncoder for a destination writer and the run's options.
type Format ¶
type Format string
Format is an output encoding.
func RegisteredFormats ¶ added in v0.4.1
func RegisteredFormats() []Format
RegisteredFormats returns the formats added through RegisterEncoder, sorted. The CLI surface uses it to list only the extra formats a binary actually supports in its --output help, rather than advertising every format kit could in principle carry.
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 ¶
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 (*Renderer) Emit ¶
Emit renders one record. A record is either a struct (rendered by reflection and its `table:`/`json:` tags) or a Record with explicit columns.
type RowEncoder ¶ added in v0.4.1
type RowEncoder interface {
// EmitRow writes one record's projected columns and values. The column set
// is stable across a run, so the first call defines the schema.
EmitRow(cols, vals []string) error
// Close flushes and finalizes the output. It is called once, from Flush.
Close() error
}
RowEncoder writes projected rows in a binary or otherwise non-streaming format that the core render package does not implement itself. A consumer supplies one (for example a Parquet writer) through RegisterEncoder, which keeps heavy encoding dependencies out of kit's core.
Source Files