table

README

table

Package table provides a convenient way to generate tabular output of any data, primarily useful for CLI tools.

Features

• Accepts all data types (string, int, interface{}, everything!) and will use the String() string method of a type if available.
• Can specify custom formatting for the header and first column cells for better readability.
• Columns are left-aligned and sized to fit the data, with customizable padding.
• The printed output can be sent to any io.Writer, defaulting to os.Stdout.
• Built to an interface, so you can roll your own Table implementation.
• Works well with ANSI colors (fatih/color in the example)!
• Can provide a custom WidthFunc to accomodate multi- and zero-width characters (such as runewidth)

Usage

Download the package:

go get -u github.com/rodaine/table

Example:

package main

import (
  "fmt"
  "strings"

  "github.com/fatih/color"
  "github.com/rodaine/table"
)

func main() {
  headerFmt := color.New(color.FgGreen, color.Underline).SprintfFunc()
  columnFmt := color.New(color.FgYellow).SprintfFunc()

  tbl := table.New("ID", "Name", "Score", "Added")
  tbl.WithHeaderFormatter(headerFmt).WithFirstColumnFormatter(columnFmt)

  for _, widget := range getWidgets() {
    tbl.AddRow(widget.ID, widget.Name, widget.Cost, widget.Added)
  }

  tbl.Print()
}

Consult the documentation for further examples and usage information

Contributing

Please feel free to submit an issue or PR to this repository for features or bugs. All submitted code must pass the scripts specified within .travis.yml and should include tests to back up the changes.

License

table is released under the MIT License (Expat). See the full license.

Documentation

Overview

Package table provides a convenient way to generate tabular output of any data, primarily useful for CLI tools.

Columns are left-aligned and padded to accomodate the largest cell in that column.

Source: https://github.com/rodaine/table

table.DefaultHeaderFormatter = func(format string, vals ...interface{}) string {
  return strings.ToUpper(fmt.Sprintf(format, vals...))
}

tbl := table.New("ID", "Name", "Cost ($)")

for _, widget := range Widgets {
  tbl.AddRow(widget.ID, widget.Name, widget.Cost)
}

tbl.Print()

// Output:
// ID  NAME      COST ($)
// 1   Foobar    1.23
// 2   Fizzbuzz  4.56
// 3   Gizmo     78.90

Index

• Variables
• type Formatter
• type Table
  • func New(columnHeaders ...interface{}) Table
• type WidthFunc

Variables

var (
	// DefaultPadding specifies the number of spaces between columns in a table.
	DefaultPadding = 2

	// DefaultWriter specifies the output io.Writer for the Table.Print method.
	DefaultWriter io.Writer = os.Stdout

	// DefaultHeaderFormatter specifies the default Formatter for the table header.
	DefaultHeaderFormatter Formatter

	// DefaultFirstColumnFormatter specifies the default Formatter for the first column cells.
	DefaultFirstColumnFormatter Formatter

	// DefaultWidthFunc specifies the default WidthFunc for calculating column widths
	DefaultWidthFunc WidthFunc = utf8.RuneCountInString
)

These are the default properties for all Tables created from this package and can be modified.

Types

type Formatter

type Formatter func(string, ...interface{}) string

Formatter functions expose a fmt.Sprintf signature that can be used to modify the display of the text in either the header or first column of a Table. The formatter should not change the width of original text as printed since column widths are calculated pre-formatting (though this issue can be mitigated with increased padding).

tbl.WithHeaderFormatter(func(format string, vals ...interface{}) string {
  return strings.ToUpper(fmt.Sprintf(format, vals...))
})

A good use case for formatters is to use ANSI escape codes to color the cells for a nicer interface. The package color (https://github.com/fatih/color) makes it easy to generate these automatically: http://godoc.org/github.com/fatih/color#Color.SprintfFunc

type Table

type Table interface {
	WithHeaderFormatter(f Formatter) Table
	WithFirstColumnFormatter(f Formatter) Table
	WithPadding(p int) Table
	WithWriter(w io.Writer) Table
	WithWidthFunc(f WidthFunc) Table

	AddRow(vals ...interface{}) Table
	Print()
}

Table describes the interface for building up a tabular representation of data. It exposes fluent/chainable methods for convenient table building.

WithHeaderFormatter and WithFirstColumnFormatter sets the Formatter for the header and first column, respectively. If nil is passed in (the default), no formatting will be applied.

New("foo", "bar").WithFirstColumnFormatter(func(f string, v ...interface{}) string {
  return strings.ToUpper(fmt.Sprintf(f, v...))
})

WithPadding specifies the minimum padding between cells in a row and defaults to DefaultPadding. Padding values less than or equal to zero apply no extra padding between the columns.

New("foo", "bar").WithPadding(3)

WithWriter modifies the writer which Print outputs to, defaulting to DefaultWriter when instantiated. If nil is passed, os.Stdout will be used.

New("foo", "bar").WithWriter(os.Stderr)

WithWidthFunc sets the function used to calculate the width of the string in a column. By default, the number of utf8 runes in the string is used.

AddRow adds another row of data to the table. Any values can be passed in and will be output as its string representation as described in the fmt standard package. Rows can have less cells than the total number of columns in the table; subsequent cells will be rendered empty. Rows with more cells than the total number of columns will be truncated. References to the data are not held, so the passed in values can be modified without affecting the table's output.

New("foo", "bar").AddRow("fizz", "buzz").AddRow(time.Now()).AddRow(1, 2, 3).Print()
// Output:
// foo                              bar
// fizz                             buzz
// 2006-01-02 15:04:05.0 -0700 MST
// 1                                2

Print writes the string representation of the table to the provided writer. Print can be called multiple times, even after subsequent mutations of the provided data. The output is always preceded and followed by a new line.

func New

func New(columnHeaders ...interface{}) Table

New creates a Table instance with the specified header(s) provided. The number of columns is fixed at this point to len(columnHeaders) and the defined defaults are set on the instance.

type WidthFunc

type WidthFunc func(string) int

A WidthFunc calculates the width of a string. By default, the number of runes is used but this may not be appropriate for certain character sets. The package runewidth (https://github.com/mattn/go-runewidth) could be used to accomodate multi-cell characters (such as emoji or CJK characters).