tabular

README

tabular

Tabular simplifies printing ASCII tables from command line utilities without the need to pass large sets of data to it's API.

Simply define the table columns and tabular will parse the right format specifier that you can use in your calls to fmt.Printf() or any other function that supports it.

Table columns can be defined once and then reused over and over again making it easy to modify column length and heading in one place. And a subset of columns can be specified during tabular.Print() or tabular.Parse() calls to modify the table's title without redefining it.

Example (also available in example/example.go):

package main

import (
	"fmt"
	"log"

	"github.com/InVisionApp/tabular"
)

var tab tabular.Table

func init() {
	tab = tabular.New()
	tab.Col("env", "Environment", 14)
	tab.Col("cls", "Cluster", 10)
	tab.Col("svc", "Service", 15)
	tab.Col("hst", "Database Host", 20)
	tab.ColRJ("pct", "%CPU", 7)
}

var data = []struct {
	e, c, s, d string
	v          float64
}{
	{
		e: "production",
		c: "cluster-1",
		s: "service-a",
		d: "database-host-1",
		v: 70.01,
	},
	{
		e: "production",
		c: "cluster-1",
		s: "service-b",
		d: "database-host-2",
		v: 99.51,
	},
	{
		e: "production",
		c: "cluster-2",
		s: "service-a",
		d: "database-host-1",
		v: 70.01,
	},
	{
		e: "production",
		c: "cluster-2",
		s: "service-b",
		d: "database-host-2",
		v: 99.51,
	},
}

func main() {
	// Print a subset of columns (Environments and Clusters)
	format := tab.Print("env", "cls")
	for _, x := range data {
		fmt.Printf(format, x.e, x.c)
	}

	// Print All Columns
	format = tab.Print("*")
	for _, x := range data {
		fmt.Printf(format, x.e, x.c, x.s, x.d, x.v)
	}

	// Print All Columns to a custom destination such as a log
	table := tab.Parse("*")
	log.Println(table.Header)
	log.Println(table.SubHeader)
	for _, x := range data {
		log.Printf(table.Format, x.e, x.c, x.s, x.d, x.v)
	}
}

Produces:

Environment    Cluster
-------------- ----------
production     cluster-1
production     cluster-1
production     cluster-2
production     cluster-2

Environment    Cluster    Service         Database Host           %CPU
-------------- ---------- --------------- -------------------- -------
production     cluster-1  service-a       database-host-1        70.01
production     cluster-1  service-b       database-host-2        99.51
production     cluster-2  service-a       database-host-1        70.01
production     cluster-2  service-b       database-host-2        99.51

2018/05/14 11:19:41 Environment    Cluster    Service         Database Host           %CPU
2018/05/14 11:19:41 -------------- ---------- --------------- -------------------- -------
2018/05/14 11:19:41 production     cluster-1  service-a       database-host-1        70.01
2018/05/14 11:19:41 production     cluster-1  service-b       database-host-2        99.51
2018/05/14 11:19:41 production     cluster-2  service-a       database-host-1        70.01
2018/05/14 11:19:41 production     cluster-2  service-b       database-host-2        99.51

Documentation

Index

• Constants
• type Column
• type Output
• type Table
  • func New() Table
  • func (tbl Table) Col(shortName, fullName string, columnLength int)
  • func (tbl Table) ColRJ(shortName, fullName string, columnLength int)
  • func (tbl Table) Parse(cols ...string) Output
  • func (tbl Table) Print(cols ...string) string

Constants

const All = "*"

All - pass this to Print() or Parse() to print or parse all columns of a table

Types

type Column

type Column struct {
	Name           string
	Length         int
	RightJustified bool
}

Column - defines column's name, length and if it's right justified

type Output

type Output struct {
	Header    string
	SubHeader string
	Format    string
}

Output - parsed table's header, subheader and format specifier

type Table

type Table struct {
	Columns map[string]*Column
	// contains filtered or unexported fields
}

Table - maps and orders short names of columns to their structure defining: full name, length and whether it's right justified

func New

func New() Table

New - Creates a new table

func (Table) Col

func (tbl Table) Col(shortName, fullName string, columnLength int)

Col - adds a new column to an existing table

func (Table) ColRJ

func (tbl Table) ColRJ(shortName, fullName string, columnLength int)

ColRJ - adds a new Right Justified column to an existing table

func (Table) Parse

func (tbl Table) Parse(cols ...string) Output

Parse - constructs Table's Output structure containing it's header, sub-header and format modifier out of a given list of columns.

To simply print the table's title call Print() instead.

Parse() is usefull when you need to control where to output the title, for example to a log or a trace file.

func (Table) Print

func (tbl Table) Print(cols ...string) string

Print - does the following:

1) prints a table style heading for a given list of columns, for example, if Columns are defined as:

"env": Column{Name: "Environment", Length: 14},
"cls": Column{Name: "Cluster",     Length: 40},
"srv": Column{Name: "Service",     Length: 35},

It'll produce:

Environment    Cluster                                  Service
-------------- ---------------------------------------- -----------------------------------

2) Returns an fmt style format specifier string that you can use to output values under the above heading via Printf(format,...):

%-14v %-40v %-35v