README
¶
tstable
Go package for tables with a simple API
The Go package tstable provides a simple interface for generating customizable ASCII tables. Initialize a table using New with a slice of header strings, and append data using AddRow. The visual output can be configured by modifying padding (SetPadding) and borders (SetGrid) using either built-in presets or a custom Grid configuration. Tables are automatically sorted alphabetically by the first column by default, which can be overridden via SortBy. The final text representation is generated using Print or String().
- Simple: Without configuration, just function calls
- Easy to use: Just define the header of a table and add rows
- Tested: Unit tests with high code coverage.
- Dependencies: Only depends on the Go Standard Library, tserr and tsfio
┌─────────────────────┬────────────────────────────────┬────────────────┐
│ Fellowship member │ Title │ Weapon │
├─────────────────────┼────────────────────────────────┼────────────────┤
│ Aragorn │ King of Gondor │ Sword │
│ Boromir │ Captain of the White Tower │ Sword │
│ Gandalf │ The Grey │ Wizard staff │
│ Gimli │ Lord of the Glittering Caves │ Axe │
│ Legolas │ Prince of the Woodland Realm │ Bow │
└─────────────────────┴────────────────────────────────┴────────────────┘
Usage
The package is installed with
go get github.com/thorsphere/tstable
In the Go app, the package is imported with
import "github.com/thorsphere/tstable"
Table grid
A table grid has an outside border. The header row is separated from the table rows by a horizontal grid line. Table rows do not have a grid line between the rows. Columns are divided by an inside grid line. The package provides a set of grids for table string representation. A grid can be used by providing its reference to SetGrid, for example:
tbl.SetGrid(&tstable.DoubleBorderGrid)
See all included grids
DoubleBorderGrid
╔═════════════════════╤════════════════════════════════╤════════════════╗
║ Fellowship member │ Title │ Weapon ║
╟─────────────────────┼────────────────────────────────┼────────────────╢
║ Aragorn │ King of Gondor │ Sword ║
║ Boromir │ Captain of the White Tower │ Sword ║
║ Gandalf │ The Grey │ Wizard staff ║
║ Gimli │ Lord of the Glittering Caves │ Axe ║
║ Legolas │ Prince of the Woodland Realm │ Bow ║
╚═════════════════════╧════════════════════════════════╧════════════════╝
DoubleHorizontalGrid
╒═════════════════════╤════════════════════════════════╤════════════════╕
│ Fellowship member │ Title │ Weapon │
╞═════════════════════╪════════════════════════════════╪════════════════╡
│ Aragorn │ King of Gondor │ Sword │
│ Boromir │ Captain of the White Tower │ Sword │
│ Gandalf │ The Grey │ Wizard staff │
│ Gimli │ Lord of the Glittering Caves │ Axe │
│ Legolas │ Prince of the Woodland Realm │ Bow │
╘═════════════════════╧════════════════════════════════╧════════════════╛
DoubleGrid
╔═════════════════════╦════════════════════════════════╦════════════════╗
║ Fellowship member ║ Title ║ Weapon ║
╠═════════════════════╬════════════════════════════════╬════════════════╣
║ Aragorn ║ King of Gondor ║ Sword ║
║ Boromir ║ Captain of the White Tower ║ Sword ║
║ Gandalf ║ The Grey ║ Wizard staff ║
║ Gimli ║ Lord of the Glittering Caves ║ Axe ║
║ Legolas ║ Prince of the Woodland Realm ║ Bow ║
╚═════════════════════╩════════════════════════════════╩════════════════╝
RoundGrid
╭─────────────────────┬────────────────────────────────┬────────────────╮
│ Fellowship member │ Title │ Weapon │
├─────────────────────┼────────────────────────────────┼────────────────┤
│ Aragorn │ King of Gondor │ Sword │
│ Boromir │ Captain of the White Tower │ Sword │
│ Gandalf │ The Grey │ Wizard staff │
│ Gimli │ Lord of the Glittering Caves │ Axe │
│ Legolas │ Prince of the Woodland Realm │ Bow │
╰─────────────────────┴────────────────────────────────┴────────────────╯
SimpleGrid
┌─────────────────────┬────────────────────────────────┬────────────────┐
│ Fellowship member │ Title │ Weapon │
├─────────────────────┼────────────────────────────────┼────────────────┤
│ Aragorn │ King of Gondor │ Sword │
│ Boromir │ Captain of the White Tower │ Sword │
│ Gandalf │ The Grey │ Wizard staff │
│ Gimli │ Lord of the Glittering Caves │ Axe │
│ Legolas │ Prince of the Woodland Realm │ Bow │
└─────────────────────┴────────────────────────────────┴────────────────┘
BoldGrid
┏━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┓
┃ Fellowship member │ Title │ Weapon ┃
┠─────────────────────┼────────────────────────────────┼────────────────┨
┃ Aragorn │ King of Gondor │ Sword ┃
┃ Boromir │ Captain of the White Tower │ Sword ┃
┃ Gandalf │ The Grey │ Wizard staff ┃
┃ Gimli │ Lord of the Glittering Caves │ Axe ┃
┃ Legolas │ Prince of the Woodland Realm │ Bow ┃
┗━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┛
EmptyGrid
Fellowship member Title Weapon
Aragorn King of Gondor Sword
Boromir Captain of the White Tower Sword
Gandalf The Grey Wizard staff
Gimli Lord of the Glittering Caves Axe
Legolas Prince of the Woodland Realm Bow
DoubleVerticalGrid
╓─────────────────────╥────────────────────────────────╥────────────────╖
║ Fellowship member ║ Title ║ Weapon ║
╟─────────────────────╫────────────────────────────────╫────────────────╢
║ Aragorn ║ King of Gondor ║ Sword ║
║ Boromir ║ Captain of the White Tower ║ Sword ║
║ Gandalf ║ The Grey ║ Wizard staff ║
║ Gimli ║ Lord of the Glittering Caves ║ Axe ║
║ Legolas ║ Prince of the Woodland Realm ║ Bow ║
╙─────────────────────╨────────────────────────────────╨────────────────╜
InterruptedGrid
┏╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┯╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┯╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┓
╏ Fellowship member ╎ Title ╎ Weapon ╏
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┨
╏ Aragorn ╎ King of Gondor ╎ Sword ╏
╏ Boromir ╎ Captain of the White Tower ╎ Sword ╏
╏ Gandalf ╎ The Grey ╎ Wizard staff ╏
╏ Gimli ╎ Lord of the Glittering Caves ╎ Axe ╏
╏ Legolas ╎ Prince of the Woodland Realm ╎ Bow ╏
┗╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┷╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┷╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┛
DashedGrid
┏┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┯┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┯┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┓
┇ Fellowship member ┆ Title ┆ Weapon ┇
┠┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┨
┇ Aragorn ┆ King of Gondor ┆ Sword ┇
┇ Boromir ┆ Captain of the White Tower ┆ Sword ┇
┇ Gandalf ┆ The Grey ┆ Wizard staff ┇
┇ Gimli ┆ Lord of the Glittering Caves ┆ Axe ┇
┇ Legolas ┆ Prince of the Woodland Realm ┆ Bow ┇
┗┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┷┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┷┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┛
DottedGrid
┏┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┯┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┯┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┓
┋ Fellowship member ┊ Title ┊ Weapon ┋
┠┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┼┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┼┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┨
┋ Aragorn ┊ King of Gondor ┊ Sword ┋
┋ Boromir ┊ Captain of the White Tower ┊ Sword ┋
┋ Gandalf ┊ The Grey ┊ Wizard staff ┋
┋ Gimli ┊ Lord of the Glittering Caves ┊ Axe ┋
┋ Legolas ┊ Prince of the Woodland Realm ┊ Bow ┋
┗┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┷┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┷┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┉┛
A custom grid can also be provided to SetGrid. A custom grid is defined with the Grid struct type. The Grid struct type contains the runes to define the grid format of a table. A table grid is defined by thirteen runes. A rune is allowed to be empty.
type Grid struct {
Hi, Hb, Vi, Vb, Hvi, Hvl, Hvr, Hvt, Hvb, Hvtl, Hvbl, Hvtr, Hvbr rune
}
// Hi: horizontal inside, separation between header and the rest of the table rows
// Hb: horizontal border, at the top and bottom of the table
// Vi: vertical inside, separation between table columns
// Vb: vertical border, at the left and right side of the table
// Hvi: horizontal vertical inside
// Hvl: horizontal vertical left
// Hvr: horizontal vertical right
// Hvt: horizontal vertical top
// Hvb: horizontal vertical bottom
// Hvtl: horizontal vertical top left
// Hvbl: horizontal vertical bottom left
// Hvtr: horizontal vertcial top right
// Hvbr: horizontal vertcial bottom right
Hvtl |
Hb |
Hvt |
Hb |
Hvtr |
|---|---|---|---|---|
Vb |
header_1 | Vi |
header_2 | Vb |
Hvl |
Hi |
Hvi |
Hi |
Hvr |
Vb |
cell_11 | Vi |
cell_12 | Vb |
Vb |
cell_21 | Vi |
cell_22 | Vb |
Hvbl |
Hb |
Hvb |
Hb |
Hvbr |
An example with a custom table grid is included in example/example.go
Example
package main
import (
"fmt"
"github.com/thorsphere/tstable"
)
var (
header = []string{"Fellowship member", "Title", "Weapon"}
rows = [][]string{
{"Gandalf", "The Grey", "Wizard staff"},
{"Aragorn", "King of Gondor", "Sword"},
{"Legolas", "Prince of the Woodland Realm", "Bow"},
{"Gimli", "Lord of the Glittering Caves", "Axe"},
{"Boromir", "Captain of the White Tower", "Sword"},
}
sortby = "Weapon"
)
func main() {
tbl, _ := tstable.New(header)
for _, r := range rows {
tbl.AddRow(r)
}
tbl.SortBy(sortby)
for n, g := range tstable.AllGrids {
tbl.SetGrid(g)
fmt.Println(n)
fmt.Print(tbl)
}
}
Links
Documentation
¶
Overview ¶
Package tstable provides a simple interface for generating customizable ASCII tables. Initialize a table using New with a slice of header strings, and append data using AddRow. The visual output can be configured by modifying padding (SetPadding) and borders (SetGrid) using either built-in presets or a custom Grid configuration. Tables are automatically sorted alphabetically by the first column by default, which can be overridden via SortBy. The final text representation is generated using Print or String.
Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.
Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.
Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.
Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.
Copyright (c) 2023-2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // The EmptyGrid defines an empty table grid. A table with the EmptyGrid does not have a grid. EmptyGrid = Grid{} // The DoubleBorderGrid has a double-lined border. DoubleBorderGrid = Grid{ Hi: '\u2500', Hb: '\u2550', Vi: '\u2502', Vb: '\u2551', Hvi: '\u253C', Hvl: '\u255F', Hvr: '\u2562', Hvt: '\u2564', Hvb: '\u2567', Hvtl: '\u2554', Hvbl: '\u255A', Hvtr: '\u2557', Hvbr: '\u255D', } // The DoubleHorizontalGrid has double-lined horizontal lines. DoubleHorizontalGrid = Grid{ Hi: '\u2550', Hb: '\u2550', Vi: '\u2502', Vb: '\u2502', Hvi: '\u256A', Hvl: '\u255E', Hvr: '\u2561', Hvt: '\u2564', Hvb: '\u2567', Hvtl: '\u2552', Hvbl: '\u2558', Hvtr: '\u2555', Hvbr: '\u255B', } // The DoubleVerticalGrid has double-lined vertical lines. DoubleVerticalGrid = Grid{ Hi: '\u2500', Hb: '\u2500', Vi: '\u2551', Vb: '\u2551', Hvi: '\u256B', Hvl: '\u255F', Hvr: '\u2562', Hvt: '\u2565', Hvb: '\u2568', Hvtl: '\u2553', Hvbl: '\u2559', Hvtr: '\u2556', Hvbr: '\u255C', } // The DoubleGrid has a double-lined grid. DoubleGrid = Grid{ Hi: '\u2550', Hb: '\u2550', Vi: '\u2551', Vb: '\u2551', Hvi: '\u256C', Hvl: '\u2560', Hvr: '\u2563', Hvt: '\u2566', Hvb: '\u2569', Hvtl: '\u2554', Hvbl: '\u255A', Hvtr: '\u2557', Hvbr: '\u255D', } // The RoundGrid has rounded corners. RoundGrid = Grid{ Hi: '\u2500', Hb: '\u2500', Vi: '\u2502', Vb: '\u2502', Hvi: '\u253C', Hvl: '\u251C', Hvr: '\u2524', Hvt: '\u252C', Hvb: '\u2534', Hvtl: '\u256D', Hvbl: '\u2570', Hvtr: '\u256E', Hvbr: '\u256F', } // The SimpleGrid has single grid lines SimpleGrid = Grid{ Hi: '\u2500', Hb: '\u2500', Vi: '\u2502', Vb: '\u2502', Hvi: '\u253C', Hvl: '\u251C', Hvr: '\u2524', Hvt: '\u252C', Hvb: '\u2534', Hvtl: '\u250C', Hvbl: '\u2514', Hvtr: '\u2510', Hvbr: '\u2518', } // The BoldGrid has bold border lines. BoldGrid = Grid{ Hi: '\u2500', Hb: '\u2501', Vi: '\u2502', Vb: '\u2503', Hvi: '\u253C', Hvl: '\u2520', Hvr: '\u2528', Hvt: '\u252F', Hvb: '\u2537', Hvtl: '\u250F', Hvbl: '\u2517', Hvtr: '\u2513', Hvbr: '\u251B', } // The InterruptedGrid has interrupted grid lines. InterruptedGrid = Grid{ Hi: '\u254C', Hb: '\u254D', Vi: '\u254E', Vb: '\u254F', Hvi: '\u253C', Hvl: '\u2520', Hvr: '\u2528', Hvt: '\u252F', Hvb: '\u2537', Hvtl: '\u250F', Hvbl: '\u2517', Hvtr: '\u2513', Hvbr: '\u251B', } // The DashedGrid has dashed grid lines. DashedGrid = Grid{ Hi: '\u2504', Hb: '\u2505', Vi: '\u2506', Vb: '\u2507', Hvi: '\u253C', Hvl: '\u2520', Hvr: '\u2528', Hvt: '\u252F', Hvb: '\u2537', Hvtl: '\u250F', Hvbl: '\u2517', Hvtr: '\u2513', Hvbr: '\u251B', } // The DottedGrid has dotted grid lines. DottedGrid = Grid{ Hi: '\u2508', Hb: '\u2509', Vi: '\u250A', Vb: '\u250B', Hvi: '\u253C', Hvl: '\u2520', Hvr: '\u2528', Hvt: '\u252F', Hvb: '\u2537', Hvtl: '\u250F', Hvbl: '\u2517', Hvtr: '\u2513', Hvbr: '\u251B', } // AllGrids is a map which contains all Grids of the package. The map returns the *Grid when using the name of the Grid as key. AllGrids = map[string]*Grid{ "EmptyGrid": &EmptyGrid, "DoubleBorderGrid": &DoubleBorderGrid, "DoubleHorizontalGrid": &DoubleHorizontalGrid, "DoubleVerticalGrid": &DoubleVerticalGrid, "DoubleGrid": &DoubleGrid, "RoundGrid": &RoundGrid, "SimpleGrid": &SimpleGrid, "BoldGrid": &BoldGrid, "InterruptedGrid": &InterruptedGrid, "DashedGrid": &DashedGrid, "DottedGrid": &DottedGrid, } )
Functions ¶
This section is empty.
Types ¶
type Grid ¶
type Grid struct {
Hi, Hb, Vi, Vb, Hvi, Hvl, Hvr, Hvt, Hvb, Hvtl, Hvbl, Hvtr, Hvbr rune
}
A Grid contains the runes to define the grid format of a table. A table grid is defined by thirteen runes. A rune is allowed to be empty.
Hi: horizontal inside, separation between header and the rest of the table rows Hb: horizontal border, at the top and bottom of the table Vi: vertical inside, separation between table columns Vb: vertical border, at the left and right side of the table Hvi: horizontal vertical inside Hvl: horizontal vertical left Hvr: horizontal vertical right Hvt: horizontal vertical top Hvb: horizontal vertical bottom Hvtl: horizontal vertical top left Hvbl: horizontal vertical bottom left Hvtr: horizontal vertical top right Hvbr: horizontal vertical bottom right
A table grid has an outside border. The header row is separated from the table rows by a horizontal grid line. Table rows do not have a grid line between the rows. Columns are divided by an inside grid line.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table holds the header of the table and all rows of the table. It also contains information on the width of each column, the row index for sorting, padding and the table grid. Per default, a table has padding 2, a simple grid and is sorted by its first row.
func New ¶
New returns a pointer to a new Table. It expects the header of the table h as a slice of strings. It returns nil and an error, if h is nil, has zero length or contains non-printable runes. The order of the header is fixed.
func (*Table) AddRow ¶
AddRow appends a row r at the end of the rows of table t. The row r is provided by a slice of strings. Row r must contain the same number of elements as the table header. The order of elements must match the order of columns defined by the table header. It returns an error if t is nil, r is nil or empty or if the number of elements in r does not equal the number of elements in the table header or if r contains non-printable runes.
func (*Table) Print ¶
Print returns the contents of table t in a string representation. The formatting of the table can be altered by changing the padding with SetPadding or setting a different grid with SetGrid. The rows are sorted in alphabetical order according to the selected column with SortBy. Per default, it is sorted by the first column.
func (*Table) SetGrid ¶
SetGrid sets the grid for table t when printed. Per default, a new table has a simple grid enabled.
func (*Table) SetPadding ¶
SetPadding sets the table padding to p. The default padding of a new table is 2. Padding p defines the number of spaces between the cell grid edges and the cell content. It returns an error if p is negative.
Source Files
Directories