render

README

render is a small library providing helpers for writing structured output (table, JSON, YAML) to io.Writer. Written by ygrebnov.

---

render provides functions for rendering Go structs and other data types as tables, JSON, or YAML. It also includes utilities for formatting and outputting this data to io.Writer.

Installation

go get github.com/ygrebnov/render

Quick start

td := render.TableData{
   Headers: []string{"NAME", "AGE"},
   Rows:    [][]string{{"Alice", "300"}, {"Bob", "250"}},
}

if err := render.Render(os.Stdout, td, render.FormatTable); err != nil {
    return err
}

outputs:

NAME   AGE
-----  ---
Alice  300
Bob    250

An example of rendering a slice of structs as a table:

type BasicRenderable struct {
   ID      string `json:"id" yaml:"id" table:"ID"`
   Name    string `json:"name" yaml:"name" table:"NAME"`
   Version string `json:"version" yaml:"version" table:"VERSION"`
}

func (b BasicRenderable) TableHeaders() []string {
    return []string{"ID", "NAME", "VERSION"}
}

func (b BasicRenderable) TableRows() [][]string {
    return [][]string{{b.ID, b.Name, b.Version}}
}

b := []BasicRenderable{
   {
      ID:      "id1",
      Name:    "base1",
      Version: "1.0.111",
   },
   {
      ID:      "id2",
      Name:    "base2",
      Version: "1.0.222",
   },
}

if err := render.Render(os.Stdout, b, render.FormatTable); err != nil {
    return err
}

outputs:

ID   NAME   VERSION
---  -----  -------
id1  base1  1.0.111
id2  base2  1.0.222

Runnable examples

See examples/examples_test.go for more examples.

License

Distributed under the BSD 3-Clause License. See LICENSE.

Documentation

Overview

Package render provides helpers for writing structured output (table, JSON, YAML) to io.Writer. The preferred path for tabular output is the TableRenderable interface; a convenience container TableData is provided for ad-hoc multi-row tables. Unknown value types fall back to YAML.

Index

• Variables
• func Render(w io.Writer, obj any, format Format, opts ...Option) error
• type Format
• type Option
  • func WithNoHeaders() Option
• type TableData
  • func (td TableData) TableHeaders() []string
  • func (td TableData) TableRows() [][]string
• type TableRenderable

Variables

var (
	ErrNilWriter         = errors.New("render.Writer is nil")
	ErrNilObject         = errors.New("render.Object is nil")
	ErrUnsupportedFormat = errors.New("unsupported format")
)

Functions

func Render

func Render(w io.Writer, obj any, format Format, opts ...Option) error

Render serialises obj in the requested format and writes it to the provided io.Writer.

Table-format rules:

• If obj implements TableRenderable, its methods drive the output.
• If obj is a plain struct (or pointer to one) it is rendered as FIELD/VALUE rows.
• Anything else falls back to YAML.

Types

type Format

type Format string

Format names the output serialisation format.

const (
	// FormatTable renders output as a plain-text aligned table.
	FormatTable Format = "table"
	// FormatJSON renders output as indented JSON.
	FormatJSON Format = "json"
	// FormatYAML renders output as YAML.
	FormatYAML Format = "yaml"
)

type Option

type Option func(*options)

Option is a functional option for Render.

func WithNoHeaders

func WithNoHeaders() Option

WithNoHeaders suppresses column headers when rendering in table format.

type TableData

type TableData struct {
	// Headers is the ordered list of column names.
	Headers []string
	// Rows is the ordered list of data rows; each row must align with Headers.
	Rows [][]string
}

TableData is a concrete, self-contained table that implements TableRenderable. Use it when you have pre-built header/row data and do not need a custom type.

Example:

td := render.TableData{
    Headers: []string{"NAME", "AGE"},
    Rows:    [][]string{{"Alice", "30"}, {"Bob", "25"}},
}
render.Render(ctx, td, render.FormatTable)

func (TableData) TableHeaders

func (td TableData) TableHeaders() []string

TableHeaders implements TableRenderable.

func (TableData) TableRows

func (td TableData) TableRows() [][]string

TableRows implements TableRenderable.

type TableRenderable

type TableRenderable interface {
	// TableHeaders returns the ordered column names for the table header row.
	TableHeaders() []string
	// TableRows returns the ordered data rows; each inner slice must align with
	// the slice returned by TableHeaders.
	TableRows() [][]string
}

TableRenderable is the explicit public interface for custom tabular rendering. Implement TableHeaders and TableRows on your domain or view type to control exactly how it appears in table output.

For ad-hoc multi-row tables without a custom type, use TableData.