Documentation
¶
Overview ¶
Package render turns a slice of rows into a borderless table, a bordered one, or a flat JSON array. All three are built from the same column list, so a column cannot exist in one and be missing from the others.
Index ¶
- Constants
- func Bool(p *bool) string
- func Duration(p *int64) string
- func Headers[T any](cols []Column[T]) []string
- func IEC(p *uint64) string
- func Int[...](v T) string
- func IntPtr[...](p *T) string
- func JSON[T any](w io.Writer, rows []T) error
- func Join(items []string, sep string) string
- func Keys[T any](cols []Column[T]) []string
- func PrettyTable[T any](w io.Writer, cols []Column[T], rows []T) error
- func SecondsSince(now, t time.Time) *int64
- func Sort[T any](rows []T, cols []Column[T], key string, desc bool) error
- func SortValue[...](p *T) any
- func Str(s string) string
- func StrPtr(p *string) string
- func Table[T any](w io.Writer, cols []Column[T], rows []T) error
- func UnitPtr[...](p *T, unit string) string
- type Column
Constants ¶
const Absent = "-"
Absent is what a table cell shows where the controller reported nothing. The JSON form omits the key instead of writing this, so a consumer parsing the JSON never has to recognize a placeholder.
Variables ¶
This section is empty.
Functions ¶
func Bool ¶
Bool renders an optional boolean as Yes or No. A nil is Absent rather than No: the controller omits some of these leaves, and reading that as No states a fact the controller did not.
func Duration ¶
Duration renders a second count as the two largest non-zero units, which is what makes an uptime of weeks and an association of minutes both readable in one column. The JSON output carries the raw seconds.
func IEC ¶
IEC renders an octet count in binary units. The JSON output carries the raw count, so this affects the table alone.
func IntPtr ¶
func IntPtr[T ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64](p *T) string
IntPtr renders an optional integer, which is the shape to prefer: it separates "the controller said zero" from "the controller said nothing".
func JSON ¶
JSON writes the rows as a flat array with the field names --sort-by accepts. json/v2 marshals a nil slice to [] and escapes no HTML, and MarshalWrite adds no trailing newline, so one is appended here.
func PrettyTable ¶
PrettyTable writes the rows as a light-ruled, bordered table with a glyph in the columns that declare one. It is what --pretty selects, for reading on a terminal rather than for piping: the rules cost three columns per field, and three of the five glyphs are two columns wide.
func SecondsSince ¶
SecondsSince converts a controller timestamp into an age in seconds. A zero time and the Unix epoch both mean the controller reported no instant: this estate returns the epoch on several sibling timestamp leaves, and an age computed from it would read as fifty-six years.
func Sort ¶
Sort orders the rows by one column, named by its JSON field name, on the JSON value rather than the rendered text. An unreported cell sorts after every reported one in both directions, because reversing the order must not promote the rows that have no value.
func SortValue ¶
func SortValue[T ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64](p *T) any
SortValue converts an optional integer into the float64 a comparator takes, or nil for an unreported cell. A column's Sort yields one of nil, a string, a float64 or a bool.
func Str ¶
Str renders a string cell, mapping the empty string to Absent. Almost every string leaf on this SDK's read paths sits in a non-pointer struct, so an omitted container and an omitted leaf both arrive as "" and neither is a value.
func Table ¶
Table writes the rows as a borderless, space-aligned table for piping: a full border spends three columns per field on views that run to twenty fields. An empty row set still prints the heading line, which distinguishes an empty fleet from a read that produced nothing.
func UnitPtr ¶
func UnitPtr[T ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64]( p *T, unit string, ) string
UnitPtr renders an optional integer with its unit glued to the number, so the cell stays one whitespace-delimited field. An unreported value is Absent with no unit, because "-dBm" would read as a measurement rather than the lack of one.
Types ¶
type Column ¶
type Column[T any] struct { // Key is the JSON field name and the value --sort-by accepts. An invariant test // asserts it matches the row struct's json tag for the same position. Key string // Header is the table heading. Header string // Cell renders the table cell. It is also what Sort falls back to, so this and // not Pretty is the text an unsorted column is ordered by. Cell func(T) string // Pretty renders the cell for the bordered table only, and is nil on every column // whose two renderings are the same. It never feeds Sort or the JSON, so a glyph // here cannot reorder rows or reach a consumer parsing the output. Pretty func(T) string // Sort yields the value to order by, and is nil where the rendered text already orders // correctly: an octet count printed as "1.0KiB" and an age printed as "3d4h" do not. Sort func(T) any }
Column is one output column: its JSON field name, its table heading and the cell it derives from a row.
Source Files