README
¶
tabulate
Tabulate is an utility library for making simple data visualizations. Tabulate works on tabular data. The data tables can be constructed explicity by calling the row and column functions, or with reflection from Go values.
Programmatic table construction
In the programmatic table construction, you first create a new table and define the headers with optional layout attributes:
tab := tabulate.New(tabulate.Unicode)
tab.Header("Year").SetAlign(tabulate.MR)
tab.Header("Income").SetAlign(tabulate.MR)
After that, you add data rows:
row := tab.Row()
row.Column("2018")
row.Column("100")
row = tab.Row()
row.Column("2019")
row.Column("110")
row = tab.Row()
row.Column("2020")
row.Column("200")
Finally, you print the table:
tab.Print(os.Stdout)
This outputs the table to the selected writer:
┏━━━━━━┳━━━━━━━━┓
┃ Year ┃ Income ┃
┡━━━━━━╇━━━━━━━━┩
│ 2018 │ 100 │
│ 2019 │ 110 │
│ 2020 │ 200 │
└──────┴────────┘
Reflection
The reflection mode allows you to easily tabulate Go data structures. The resulting table will always have two columns: key and value. But the value columns can contain nested tables.
type Person struct {
Name string
}
type Book struct {
Title string
Author []Person
Publisher string
Published int
}
tab := tabulate.New(tabulate.ASCII)
tab.Header("Key").SetAlign(tabulate.ML)
tab.Header("Value")
err := tabulate.Reflect(tab, 0, nil, &Book{
Title: "Structure and Interpretation of Computer Programs",
Author: []Person{
Person{
Name: "Harold Abelson",
},
Person{
Name: "Gerald Jay Sussman",
},
Person{
Name: "Julie Sussman",
},
},
Publisher: "MIT Press",
Published: 1985,
})
if err != nil {
log.Fatal(err)
}
tab.Print(os.Stdout)
This example renders the following table:
+-----------+---------------------------------------------------+
| Key | Value |
+-----------+---------------------------------------------------+
| Title | Structure and Interpretation of Computer Programs |
| | +------+----------------+ |
| | | Key | Value | |
| | +------+----------------+ |
| | | Name | Harold Abelson | |
| | +------+----------------+ |
| | +------+--------------------+ |
| | | Key | Value | |
| Author | +------+--------------------+ |
| | | Name | Gerald Jay Sussman | |
| | +------+--------------------+ |
| | +------+---------------+ |
| | | Key | Value | |
| | +------+---------------+ |
| | | Name | Julie Sussman | |
| | +------+---------------+ |
| Publisher | MIT Press |
| Published | 1985 |
+-----------+---------------------------------------------------+
Formatting
Cell alignment
Column headers set the default alignment for all cells in the corresponding columns. The column default alignment is set when the headers are defined:
tab.Header("Year").SetAlign(tabulate.MR)
The alignment is defined with the Align constants. The first character of the constant name specifies the vertical alignment (Top, Middle, Bottom) and the second character specifies the horizointal alignment (Left, Center, Right).
| Alignment | Vertical | Horizontal |
|---|---|---|
| TL | Top | Left |
| TC | Top | Center |
| TR | Top | Right |
| ML | Middle | Left |
| MC | Middle | Center |
| MR | Middle | Right |
| BL | Bottom | Left |
| BC | Bottom | Center |
| BR | Bottom | Right |
| None | - | - |
The default alignment can be overridden by calling the SetAlign() for the data column:
row = tab.Row()
row.Column("Integer").SetAlign(tabulate.TL)
Output formats
Plain
The Plain format does not draw any table borders:
Year Income Expenses
2018 100 90
2019 110 85
2020 107 50
ASCII
The ASCII format creates a new tabulator that uses ASCII characters to render the table borders:
+------+--------+----------+
| Year | Income | Expenses |
+------+--------+----------+
| 2018 | 100 | 90 |
| 2019 | 110 | 85 |
| 2020 | 107 | 50 |
+------+--------+----------+
Unicode
The Unicode format creates a new tabulator that uses Unicode line drawing characters to render the table borders:
┏━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
┃ Year ┃ Income ┃ Expenses ┃
┡━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
│ 2018 │ 100 │ 90 │
│ 2019 │ 110 │ 85 │
│ 2020 │ 107 │ 50 │
└──────┴────────┴──────────┘
UnicodeLight
The UnicodeLight format creates a new tabulator that uses thin Unicode line drawing characters to render the table borders:
┌──────┬────────┬──────────┐
│ Year │ Income │ Expenses │
├──────┼────────┼──────────┤
│ 2018 │ 100 │ 90 │
│ 2019 │ 110 │ 85 │
│ 2020 │ 107 │ 50 │
└──────┴────────┴──────────┘
UnicodeBold
The UnicodeBold format creates a new tabulator that uses thick Unicode line drawing characters to render the table borders:
┏━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
┃ Year ┃ Income ┃ Expenses ┃
┣━━━━━━╋━━━━━━━━╋━━━━━━━━━━┫
┃ 2018 ┃ 100 ┃ 90 ┃
┃ 2019 ┃ 110 ┃ 85 ┃
┃ 2020 ┃ 107 ┃ 50 ┃
┗━━━━━━┻━━━━━━━━┻━━━━━━━━━━┛
Colon
The Colon format creates a new tabulator that uses colon (':') character to render vertical table borders:
Year : Income : Expenses
2018 : 100 : 90
2019 : 110 : 85
2020 : 107 : 50
Simple
The Simple format draws horizontal lines between header and body columns:
Year Income Expenses
---- ------ --------
2018 100 90
2019 110 85
2020 107 50
Github
The Github creates tables with the Github Markdown syntax:
| Year | Income | Expenses |
|------|--------|----------|
| 2018 | 100 | 90 |
| 2019 | 110 | 85 |
| 2020 | 107 | 50 |
Comma-Separated Values (CSV) output
The NewCSV() creates a new tabulator that outputs the data in CSV format. It uses empty borders and an escape function which handles ',' and '\n' characters inside cell values:
Year,Income,Source
2018,100,Salary
2019,110,"""Consultation"""
2020,120,"Lottery
et al"
JSON output
The NewJSON() creates a new tabulator that outputs the data in JSON format:
{"2018":["100","90"],"2019":["110","85"],"2020":["107","50"]}
Native JSON marshalling
The Tabulate object implements the MarshalJSON interface so you can marshal tabulated data directly into JSON.
tab := tabulate.New(tabulate.Unicode)
tab.Header("Key").SetAlign(tabulate.MR)
tab.Header("Value").SetAlign(tabulate.ML)
row := tab.Row()
row.Column("Boolean")
row.ColumnData(NewValue(false))
row = tab.Row()
row.Column("Integer")
row.ColumnData(NewValue(42))
data, err := json.Marshal(tab)
if err != nil {
log.Fatalf("JSON marshal failed: %s", err)
}
fmt.Println(string(data))
This example outputs the following JSON output:
{"Boolean":false,"Integer":42}
Documentation
¶
Index ¶
- Variables
- func MeasureRunes(column string) int
- func MeasureUnicode(column string) int
- func Reflect(tab *Tabulate, flags Flags, tags []string, v interface{}) error
- func StyleNames() []string
- type Align
- type Border
- type Borders
- type Column
- type Data
- type Escape
- type Flags
- type Format
- type Lines
- type Measure
- type Row
- type Slice
- type Style
- type Tabulate
- func (t *Tabulate) Clone() *Tabulate
- func (t *Tabulate) Content(row int) string
- func (t *Tabulate) Header(label string) *Column
- func (t *Tabulate) HeaderData(data Data) *Column
- func (t *Tabulate) Height() int
- func (t *Tabulate) MarshalJSON() ([]byte, error)
- func (t *Tabulate) Print(o io.Writer)
- func (t *Tabulate) Row() *Row
- func (t *Tabulate) SetDefaults(col int, align Align)
- func (t *Tabulate) String() string
- func (t *Tabulate) Width(m Measure) int
- type Value
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Styles = map[string]Style{ "plain": Plain, "ascii": ASCII, "uc": Unicode, "uclight": UnicodeLight, "ucbold": UnicodeBold, "compactuc": CompactUnicode, "compactuclight": CompactUnicodeLight, "compactucbold": CompactUnicodeBold, "colon": Colon, "simple": Simple, "simpleuc": SimpleUnicode, "simpleucbold": SimpleUnicodeBold, "github": Github, "csv": CSV, "json": JSON, }
Styles list all supported tabulation types.
Functions ¶
func MeasureRunes ¶
MeasureRunes measures the column width by counting its runes. This assumes that all runes have the same width consuming single output column cell.
func MeasureUnicode ¶
MeasureUnicode measures the column width by taking into consideration East Asian Wide characters. The function assumes that East Asian Wide characters consume two output column cells.
func Reflect ¶
Reflect tabulates the value into the tabulation object. The flags control how different values are handled. The tags lists element tags which are included in reflection. If the element does not have tabulation tag, then it is always included in tabulation.
Example ¶
type Person struct {
Name string
}
type Book struct {
Title string
Author []Person
Publisher string
Published int
}
tab := New(ASCII)
tab.Header("Key").SetAlign(ML)
tab.Header("Value")
err := Reflect(tab, InheritHeaders, nil, &Book{
Title: "Structure and Interpretation of Computer Programs",
Author: []Person{
{
Name: "Harold Abelson",
},
{
Name: "Gerald Jay Sussman",
},
{
Name: "Julie Sussman",
},
},
Publisher: "MIT Press",
Published: 1985,
})
if err != nil {
log.Fatal(err)
}
tab.Print(os.Stdout)
Output: +-----------+---------------------------------------------------+ | Key | Value | +-----------+---------------------------------------------------+ | Title | Structure and Interpretation of Computer Programs | | | +------+----------------+ | | | | Key | Value | | | | +------+----------------+ | | | | Name | Harold Abelson | | | | +------+----------------+ | | | +------+--------------------+ | | | | Key | Value | | | Author | +------+--------------------+ | | | | Name | Gerald Jay Sussman | | | | +------+--------------------+ | | | +------+---------------+ | | | | Key | Value | | | | +------+---------------+ | | | | Name | Julie Sussman | | | | +------+---------------+ | | Publisher | MIT Press | | Published | 1985 | +-----------+---------------------------------------------------+
func StyleNames ¶
func StyleNames() []string
StyleNames returns the tabulation style names as a sorted slice.
Types ¶
type Align ¶
type Align int
Align specifies cell alignment in horizontal and vertical directions.
Alignment constants. The first character specifies the vertical alignment (Top, Middle, Bottom) and the second character specifies the horizointal alignment (Left, Center, Right).
type Border ¶
type Border struct {
HT string
HM string
HB string
VL string
VM string
VR string
TL string
TM string
TR string
ML string
MM string
MR string
BL string
BM string
BR string
}
Border specifies the table border drawing elements.
type Column ¶
Column defines a table column data and its attributes.
func (*Column) Content ¶
Content returns the specified row from the column. If the column does not have that many row, the function returns an empty string.
type Format ¶
type Format int
Format specifies text formatting.
Format values specify various VT100 text formatting codes.
type Lines ¶
type Lines struct {
Lines []string
}
Lines implements the Data interface over an array of lines.
func NewLines ¶
NewLines creates a new Lines data from the argument string. The argument string is split into lines from the newline ('\n') character.
func NewLinesData ¶
NewLinesData creates a new Lines data from the array of strings.
type Measure ¶
Measure returns the column width in display units. This can be used to remove any non-printable formatting codes from the value.
type Row ¶
Row defines a data row in the tabulator.
func (*Row) ColumnData ¶
ColumnData adds a new data column to the row.
type Slice ¶
type Slice struct {
// contains filtered or unexported fields
}
Slice implements the Data interface for an array of Data elements.
type Style ¶
type Style int
Style specifies the table borders and rendering style.
Example (Csv) ¶
tabulateStyle(CSV).Print(os.Stdout)
Output:
type Tabulate ¶
type Tabulate struct {
Padding int
TrimColumns bool
Borders Borders
Measure Measure
Escape Escape
Output func(t *Tabulate, o io.Writer)
Defaults []Align
Headers []*Column
Rows []*Row
// contains filtered or unexported fields
}
Tabulate defined a tabulator instance.
func Array ¶
Array tabulates the argument v into rows and columns. If the tab defines header columns, those will be used. Otherwise the first row of v defines the header columns.
Example ¶
tab, err := Array(New(ASCII), [][]interface{}{
{"a", "b", "c"},
{"1", "2", "3"},
})
if err != nil {
log.Fatal(err)
}
tab.Print(os.Stdout)
Output: +---+---+---+ | a | b | c | +---+---+---+ | 1 | 2 | 3 | +---+---+---+
Example (Second) ¶
tab, err := Array(New(Unicode), [][]interface{}{
{"int", "float", "struct"},
{42, 3.14, struct {
ival int
strval string
}{
ival: 42,
strval: "Hello, world!",
}},
})
if err != nil {
log.Fatal(err)
}
tab.Print(os.Stdout)
Output: ┏━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ int ┃ float ┃ struct ┃ ┡━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ 42 │ 3.14 │ ┌────────┬───────────────┐ │ │ │ │ │ ival │ 42 │ │ │ │ │ │ strval │ Hello, world! │ │ │ │ │ └────────┴───────────────┘ │ └─────┴───────┴────────────────────────────┘
func New ¶
New creates a new tabulate object with the specified rendering style.
Example ¶
tab := New(Unicode)
lines := strings.Split(`Year,Income,Source
2018,100,Salary
2019,110,Consultation
2020,200,Lottery`, "\n")
// Table headers.
for _, hdr := range strings.Split(lines[0], ",") {
tab.Header(hdr)
}
// Table data rows.
for _, line := range lines[1:] {
row := tab.Row()
for _, col := range strings.Split(line, ",") {
row.Column(col)
}
}
tab.Print(os.Stdout)
Output: ┏━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━┓ ┃ Year ┃ Income ┃ Source ┃ ┡━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━┩ │ 2018 │ 100 │ Salary │ │ 2019 │ 110 │ Consultation │ │ 2020 │ 200 │ Lottery │ └──────┴────────┴──────────────┘
func (*Tabulate) Clone ¶
Clone creates a new tabulator sharing the headers and their attributes. The new tabulator does not share the data rows with the original tabulator.
func (*Tabulate) Header ¶
Header adds a new column to the table and specifies its header label.
Example ¶
tab := New(Unicode)
tab.Header("Year").SetAlign(MR)
tab.Header("Income").SetAlign(MR)
tab.Print(os.Stdout)
Output: ┏━━━━━━┳━━━━━━━━┓ ┃ Year ┃ Income ┃ ┗━━━━━━┻━━━━━━━━┛
func (*Tabulate) HeaderData ¶
HeaderData adds a new column to the table and specifies is header data.
func (*Tabulate) MarshalJSON ¶
MarshalJSON implements the JSON Marshaler interface.
Example ¶
tab := New(Unicode)
tab.Header("Key").SetAlign(MR)
tab.Header("Value").SetAlign(ML)
row := tab.Row()
row.Column("Boolean")
row.ColumnData(NewValue(false))
row = tab.Row()
row.Column("Integer")
row.ColumnData(NewValue(42))
data, err := json.Marshal(tab)
if err != nil {
log.Fatalf("JSON marshal failed: %s", err)
}
fmt.Println(string(data))
Output: {"Boolean":false,"Integer":42}
func (*Tabulate) Row ¶
Row adds a new data row to the table.
Example ¶
tab := New(Unicode)
tab.Header("Year").SetAlign(MR)
tab.Header("Income").SetAlign(MR)
row := tab.Row()
row.Column("2018")
row.Column("100")
row = tab.Row()
row.Column("2019")
row.Column("110")
row = tab.Row()
row.Column("2020")
row.Column("200")
tab.Print(os.Stdout)
Output: ┏━━━━━━┳━━━━━━━━┓ ┃ Year ┃ Income ┃ ┡━━━━━━╇━━━━━━━━┩ │ 2018 │ 100 │ │ 2019 │ 110 │ │ 2020 │ 200 │ └──────┴────────┘
func (*Tabulate) SetDefaults ¶
SetDefaults sets the column default attributes. These are used if the table does not have headers.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value implements the Data interface for single value, such as bool, integer, etc.
func NewValue ¶
func NewValue(v interface{}) *Value
NewValue creates a new Value for the argument value element.
Source Files