tablewriter

README

go-tablewriter

This module implements a writer for table data, which can be output as CSV or Text.

Example:

package main

import (
    tablewriter "github.com/djthorpe/go-tablewriter"

)

func main() {
  table := []TableData{
    {A: "hello", B: "world"},
  }
  writer := tablewriter.New(os.Stdout)
  writer.Write(table, tablewriter.OptHeader())
}

The Write function expects a single struct or a slice of structs as the first argument. Each struct represents a row in the table. The struct fields (including any which are embedded) are used as columns in the table.

Table Options

The following options can be used to customize the output:

• tablewriter.OptHeader(): Output the header row.
• tablewriter.OptTag("json"): Set the struct field tag which is used to set options, default is "json".
• tablewriter.OptFieldDelim('|'): Set the field delimiter, default is ',' for CSV and '|' for Text.
• tablewriter.OptOutputCSV(): Output as CSV.
• tablewriter.OptOutputText(): Output as Text.
• tablewriter.OptNull("<nil>"): Set how the nil value is represented in the output, defaults to <nil>.

Struct Tags

Tags on struct fields can determine how the field is output. The json tag is used by default.

• json:"-": Skip the field.
• json:"Name": Set the column header to "Name".
• json:",omitdefault": If all values in the table are zero-valued, skip output of the column (TODO)
• json:",wrap": Field is wrapped to the width of the column.
• json:",right": Field is right-aligned in the column.
• json:",width:20": Suggested column width is 20 characters

Customize Field Output

You can implement the following interface on any field to customize how it is output:

type Marshaller interface {
  Marshal() ([]byte, error)
}

By default, strings and time.Time types are output as-is and other values are marshalled using the encoding/json package.

Contribution and License

See the LICENSE file for license rights and limitations, currently Apache. Pull requests and issues are welcome.

Changelog

• v0.0.1 (May 2024) Initial version
• v0.0.2 (May 2024) Documentation updates
• v0.0.4 (May 2024) Added text wrapping for text output
• v0.0.5 (May 2024) Exposing options for customizing the output in the struct tags

Future versions will include more options for customizing the output:

• Setting the width of the table based on terminal width
• Estimating sizing the width of fields for the text package
• Omitting columns based on zero-value
• Adding JSON and SQL output
• Outputing fields with ANSI color codes
• Adding a separate tag for tablewriter options instead of using json

Documentation

Index

• type Iterator
  • func NewIterator(v any) (Iterator, error)
• type Marshaller
• type TableMeta
• type TableOpt
  • func OptFieldDelim(delim rune) TableOpt
  • func OptHeader() TableOpt
  • func OptNull(v string) TableOpt
  • func OptOutputCSV() TableOpt
  • func OptOutputText() TableOpt
  • func OptTag(tag string) TableOpt
  • func OptTimeLayout(v string) TableOpt
• type Writer
  • func New(w io.Writer, opts ...TableOpt) *Writer
  • func (writer *Writer) NewMeta(v any, opts ...TableOpt) (TableMeta, error)
  • func (w *Writer) Output() io.Writer
  • func (w *Writer) Write(v any, opts ...TableOpt) error

Types

type Iterator

type Iterator interface {
	// Return the number of elements
	Len() int

	// Return the next struct, or nil
	Next() any

	// Reset the iterator to the beginning
	Reset()
}

Iterator is an interface for iterating over a slice of struct values

func NewIterator

func NewIterator(v any) (Iterator, error)

NewIterator returns a new slice iterator object, from a single struct value or an array of one or more struct values which are of the same type

type Marshaller

type Marshaller interface {
	Marshal() ([]byte, error)
}

type TableMeta

type TableMeta interface {
	// Return the underlying type
	Type() reflect.Type

	// Return the number of output columns
	NumField() int

	// Return the field names
	Fields() []string
}

type TableOpt

type TableOpt func(*opts) error

TableOpt is a function which can be used to set options on a table

func OptFieldDelim

func OptFieldDelim(delim rune) TableOpt

Set the field delimiter, default is ',' for CSV and '|' for Text

func OptHeader

func OptHeader() TableOpt

Set the struct field tag which is used to set table options, default is "json"

func OptNull

func OptNull(v string) TableOpt

Set how the nil value is represented in the output, defaults to "<nil>"

func OptOutputCSV

func OptOutputCSV() TableOpt

Output as CSV

func OptOutputText

func OptOutputText() TableOpt

Output as Text

func OptTag

func OptTag(tag string) TableOpt

Set the struct field tag which is used to set table options, default is "json"

func OptTimeLayout

func OptTimeLayout(v string) TableOpt

Set how time values are formatted in the output

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

A writer object which can write table data to an io.Writer

func New

func New(w io.Writer, opts ...TableOpt) *Writer

New creates a new Writer object, with options for all subsequent writes

func (*Writer) NewMeta

func (writer *Writer) NewMeta(v any, opts ...TableOpt) (TableMeta, error)

Create a new table metadata object from a struct value and optional formatting options

func (*Writer) Output

func (w *Writer) Output() io.Writer

Output will return the underlying io.Writer object

func (*Writer) Write

func (w *Writer) Write(v any, opts ...TableOpt) error

Write the table to output, applying any options which override to the options passed to the New method