Output Table Formatter Specification¶

// Column defines a single table column.
type Column struct {
    // Header is the display name shown in the table header row.
    Header    string
    // Field is the struct field name or map key to extract the value from.
    Field     string
    // Width is the fixed column width. Zero means auto-sized to content.
    Width     int
    // Sortable indicates this column can be used as a sort key.
    Sortable  bool
    // Formatter is an optional function to format the cell value.
    Formatter func(any) string
}

// TableWriter renders structured data as an aligned table or machine-readable format.
type TableWriter struct {
    // unexported fields
}

// TableOption configures the TableWriter.
type TableOption func(*tableConfig)

// NewTableWriter creates a TableWriter that writes to the given io.Writer.
func NewTableWriter(w io.Writer, format Format, opts ...TableOption) *TableWriter

// WithColumns explicitly defines the table columns. When not provided,
// columns are derived from struct tags on the row data type.
func WithColumns(cols ...Column) TableOption

// WithSortBy sets the column to sort rows by. The column must be marked Sortable.
func WithSortBy(field string) TableOption

// WithSortDescending reverses the sort order.
func WithSortDescending() TableOption

// WithNoHeader suppresses the header row in text table output.
func WithNoHeader() TableOption

// WithNoTruncation disables terminal-width truncation.
// Useful when output is piped to a file or another process.
func WithNoTruncation() TableOption

// WithMaxWidth overrides automatic terminal width detection.
func WithMaxWidth(width int) TableOption

// WriteRows renders the provided slice as a table.
// T must be a struct type (for tag-based columns) or []map[string]any.
// For JSON/YAML formats, the raw data is marshalled directly.
// For CSV format, columns are used as the header row.
// For text format, an aligned table with padding is produced.
func (t *TableWriter) WriteRows(rows any) error

const (
    FormatText Format = "text"   // existing
    FormatJSON Format = "json"   // existing
    FormatYAML Format = "yaml"   // NEW
    FormatCSV  Format = "csv"    // NEW
)

type ServiceStatus struct {
    Name   string `json:"name"   table:"NAME,sortable"`
    Status string `json:"status" table:"STATUS"`
    Port   int    `json:"port"   table:"PORT,sortable"`
    Uptime string `json:"uptime" table:"UPTIME"`
}

services := []ServiceStatus{
    {Name: "api", Status: "running", Port: 8080, Uptime: "3d2h"},
    {Name: "worker", Status: "stopped", Port: 0, Uptime: "0s"},
}

format := output.Format(cmd.Flag("output").Value.String())
tw := output.NewTableWriter(cmd.OutOrStdout(), format,
    output.WithSortBy("NAME"),
)

if err := tw.WriteRows(services); err != nil {
    return err
}

// Text output:
// NAME     STATUS    PORT   UPTIME
// api      running   8080   3d2h
// worker   stopped   0      0s

// JSON output: [{"name":"api","status":"running","port":8080,"uptime":"3d2h"}, ...]
// CSV output:  NAME,STATUS,PORT,UPTIME\napi,running,8080,3d2h\n...

func (t *TableWriter) renderText(columns []Column, rows [][]string) error {
    // Calculate column widths (max of header and all cell values)
    widths := calculateWidths(columns, rows)

    // Apply terminal width truncation
    if !t.cfg.noTruncation {
        termWidth := t.detectTerminalWidth()
        widths = truncateWidths(widths, termWidth)
    }

    // Render header
    if !t.cfg.noHeader {
        t.renderRow(columns, widths, headerStyle)
    }

    // Render data rows
    for _, row := range rows {
        t.renderRow(row, widths, dataStyle)
    }

    return nil
}

func columnsFromStruct(v any) ([]Column, error) {
    t := reflect.TypeOf(v)
    if t.Kind() == reflect.Slice {
        t = t.Elem()
    }
    if t.Kind() == reflect.Ptr {
        t = t.Elem()
    }
    if t.Kind() != reflect.Struct {
        return nil, errors.New("WriteRows requires a slice of structs")
    }

    var cols []Column
    for i := range t.NumField() {
        tag := t.Field(i).Tag.Get("table")
        if tag == "" || tag == "-" {
            continue
        }
        parts := strings.Split(tag, ",")
        col := Column{
            Header:   parts[0],
            Field:    t.Field(i).Name,
            Sortable: slices.Contains(parts[1:], "sortable"),
        }
        cols = append(cols, col)
    }
    return cols, nil
}

func sortRows(rows [][]string, colIdx int, descending bool) {
    sort.SliceStable(rows, func(i, j int) bool {
        // Attempt numeric comparison first, fall back to string
        if descending {
            return rows[i][colIdx] > rows[j][colIdx]
        }
        return rows[i][colIdx] < rows[j][colIdx]
    })
}