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 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 Print() or 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.Columns

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.Col("pct", "%CPU", 7)
	tab["pct"].RightJustified = true
}

// Sample data-set
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 Environments and Clusters
	format := tab.Print("env", "cls")
	for _, x := range data {
		fmt.Printf(format, x.e, x.c)
	}

	// Print Environments, Clusters and Services
	format = tab.Print("env", "cls", "svc")
	for _, x := range data {
		fmt.Printf(format, x.e, x.c, x.s)
	}

	// Print Everything
	format = tab.Print("cls", "svc", "hst", "pct")
	for _, x := range data {
		fmt.Printf(format, x.c, x.s, x.d, x.v)
	}

	// Print Everything to a custom destination such as a log
	table := tab.Parse("cls", "svc", "hst", "pct")
	log.Println(table.Header)
	log.Println(table.SubHeader)
	for _, x := range data {
		log.Printf(table.Format, 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
-------------- ---------- ---------------
production     cluster-1  service-a
production     cluster-1  service-b
production     cluster-2  service-a
production     cluster-2  service-b

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

2018/04/26 10:17:27 Cluster    Service         Database Host           %CPU
2018/04/26 10:17:27 ---------- --------------- -------------------- -------
2018/04/26 10:17:27 cluster-1  service-a       database-host-1        70.01
2018/04/26 10:17:27 cluster-1  service-b       database-host-2        99.51
2018/04/26 10:17:27 cluster-2  service-a       database-host-1        70.01
2018/04/26 10:17:27 cluster-2  service-b       database-host-2        99.51

Documentation

Index

• type Column
• type Columns
  • func New() Columns
  • func (cl Columns) Col(shortName, fullName string, columnLength int)
  • func (cl Columns) Parse(cols ...string) Table
  • func (cl Columns) Print(cols ...string) string
• type 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 Columns

type Columns map[string]*Column

Columns - maps short names of columns to their structure defining:

full name, length and whether it's right justified

For Example:

"env": Column{Name: "Environment", Length: 14},
"cls": Column{Name: "Cluster",     Length: 40},
"srv": Column{Name: "Service",     Length: 35},
"hst": Column{Name: "Host",        Length: 45},
"pct": Column{Name: "%CPU",        Length: 7, RightJustified: true},

func New

func New() Columns

New - Creates a map of tabular Columns

func (Columns) Col

func (cl Columns) Col(shortName, fullName string, columnLength int)

Col - adds a new column to existing tabular Format

func (Columns) Parse

func (cl Columns) Parse(cols ...string) Table

Parse - builds a Table 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 (Columns) Print

func (cl Columns) 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

type Table

type Table struct {
	Header    string
	SubHeader string
	Format    string
}

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