README
¶
Go package to print nicely aligned tables in the terminal.
Import at zgo.at/acidtab. Godoc: https://godocs.io/zgo.at/acidtab
You can view all these examples in your terminal with go test -v.
Basic usage
// Create a new table
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
// Add rows
t.Row("James Holden", "Montana", "Captain", "Tilting windmills", true)
t.Row("Amos Burton", "Baltimore", "Mechanic", "Specific people skills", true)
// And then print it:
t.Horizontal(os.Stdout)
Outputs:
Name │ Origin │ Job │ Speciality │ Alive
────────────────┼─────────────┼────────────┼──────────────────────────┼─────────
James Holden │ Montana │ Captain │ Tilting windmills │ true
Amos Burton │ Baltimore │ Mechanic │ Specific people skills │ true
Note: because GitHub adds a line-height there are little gaps between the vertical dividers. You don't have this in a terminal.
Options
There are a bunch of options you can set:
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
t.Borders(acidtab.BordersHeavy) // Set different borders.
t.Pad(" ") // Pad cells with one space.
t.Prefix(" ") // Prefix every line with a space.
t.Close(acidtab.CloseTop | acidtab.CloseBottom) // "Close" top and bottom.
t.Header(false) // Don't print the header.
t.Row("Naomi Nagata", "Pallas", "Mechanic", "Spicy red food", true)
t.Row("Alex Kamal", "Mars", "Pilot", "Cowboys", false)
t.Horizontal(os.Stdout)
Outputs:
━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━
Naomi Nagata ┃ Pallas ┃ Mechanic ┃ Spicy red food ┃ true
Alex Kamal ┃ Mars ┃ Pilot ┃ Cowboys ┃ false
━━━━━━━━━━━━━━┻━━━━━━━━┻━━━━━━━━━━┻━━━━━━━━━━━━━━━━┻━━━━━━━
-
The default for
Pad()is two spaces. -
The default for
Prefix()is an empty string. -
acidtab.CloseLeftand acidtab.CloseRightcan be used to add borders to the left and right too, oracidtab.CloseAll` to add borders to all sides. -
The default for
Bordersisacidtab.BordersHeavy; also see the otherBorders*variables, and you can define you own. Note you need to define all used characters, otherwise it will print the zero value (a NULL byte).
Column options
You can set options for columns:
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
t.Close(acidtab.CloseLeft | acidtab.CloseRight)
t.AlignCol(3, acidtab.Right) // Align column 3 and 4 (starts at 0)
t.AlignCol(4, acidtab.Center)
t.FormatCol(3, "%q") // Print column 3 as %q
// Callback for column 4
t.FormatColFunc(4, func(v interface{}) string {
if b, ok := v.(bool); ok {
return map[bool]string{true: "yes", false: "no"}[b]
}
// Return a NULL byte to fall back to regular formatting.
return "\x00"
})
t.Row("Joe Miller", "Ceres", "Cop", "Doors 'n corners", false)
t.Row("Chrisjen Avasarala", "Earth", "Politician", "Insults", true)
t.Horizontal(os.Stdout)
Outputs:
│ Name │ Origin │ Job │ Speciality │ Alive │
├──────────────────────┼──────────┼──────────────┼──────────────────────┼─────────┤
│ Joe Miller │ Ceres │ Cop │ "Doors 'n corners" │ no │
│ Chrisjen Avasarala │ Earth │ Politician │ "Insults" │ yes │
-
AlignCol()sets the column alignment; the default isAuto, which right-aligns numbers (int, float) and left-aligns everything else. -
FormatCol()sets how the value is printed withfmt.Sprintf. The default if%v. -
FormatColFunc()sets a callback to print the value instead, in this case to show something nicer than "true" or "false". Return a NULL byte to fall back tofmt.Sprintfformatting.acidtab.FormatAsNumcan be used to print numbers with thousands separators (only,at the moment, not locale-aware). e.g.FormatColFunc(1, acidtab.FormatAsNum()).
The column indexes start at zero. Note these are not checked: if you defined fewer headers then you will get a panic.
Vertical table
You can print a "vertical" table with Vertical():
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
t.Row("Prax Meng", "Ganymede", "Botanist", "Plant metaphors", true)
t.Row("Klaes Ashford", "The belt", "Pirate", "Singing", "😢")
t.Vertical(os.Stdout)
Outputs:
Name │ Prax Meng
Origin │ Ganymede
Job │ Botanist
Speciality │ Plant metaphors
Alive │ true
──────────────┼───────────────────
Name │ Klaes Ashford
Origin │ The belt
Job │ Pirate
Speciality │ Singing
Alive │ 😢
Most options for horizontal tables work for this as well, but disabling the header has no effect (it would be a bit pointless) and data is always left-aligned.
Chaining
All options can be chained:
acidtab.New("Name", "Origin", "Job", "Speciality", "Alive").
Close(acidtab.CloseTop|acidtab.CloseBottom).
Prefix(" ").
Pad(" ").
FormatCol(1, "%q").
Rows(
"Adolphus Murtry", "Earth", "Security", "General twattery", false,
"Fred Johnson", "Earth", "Colonol", "Beltalowda", false,
).
Vertical(os.Stdout)
Outputs:
────────────┬──────────────────
Name │ Adolphus Murtry
Origin │ "Earth"
Job │ Security
Speciality │ General twattery
Alive │ false
────────────┼──────────────────
Name │ Fred Johnson
Origin │ "Earth"
Job │ Colonol
Speciality │ Beltalowda
Alive │ false
────────────┴──────────────────
It's identical to the above examples; you don't need the return value. It's just a bit more convenient in some cases.
Also note the usage of Rows() to add multiple rows in the above example.
Formatting
You can use plain ol' escape sequences to format stuff. This won't interfere with alignment:
t := acidtab.New(bold("Name"), bold("Origin"), bold("Job"), bold("Speciality"), bold("Alive")).
Close(acidtab.CloseAll).
AlignCol(4, acidtab.Center).
FormatColFunc(4, func(v interface{}) string {
if b, ok := v.(bool); ok {
return map[bool]string{
true: "\x1b[32m ✔ \x1b[0m",
false: "\x1b[31m✘\x1b[0m",
}[b]
}
return "\x00"
})
t.Rows(
"James Holden", "Montana 🌎", "Captain 🚀", "Tilting windmills", true,
"Amos Burton", "Baltimore 🌎", "Mechanic 🔧", "Specific people skills", true,
"Naomi Nagata", "Pallas 🌌", "Mechanic 💻", "Spicy red food", true,
"Alex Kamal", "Mars 🔴", "Pilot 🎧", "Cowboys", false,
"Joe Miller", "Ceres 🌌", "Cop 👮", "Doors 'n corners", true,
"Chrisjen Avasarala", "Earth 🌏", "Politician 🖕", "Insults", true,
"Prax Meng", "Ganymede 🌌", "Botanist 🌻", "Plant metaphors", true,
"Klaes Ashford", "The belt 🌌", "Pirate 🕱", "Singing", "😢",
"Adolphus Murtry", "Earth 🌎", "Security 💂", "General twattery", false,
"Fred Johnson", "Earth 🌎", "Colonol 🎖", "Beltalowda", false)
t.Horizontal(os.Stdout)
Outputs (as screenshot as I can't get GitHub to render this correct):
Note that everything is aligned correctly, even though there are escape sequences, multi-codepoint emojis, and double-width emojis. As long as the terminal renders this type of thing correctly this should work for most of Unicode (including east-Asian characters). Unfortunately, many terminals render things like emojis inconsistently, so it's probably best to avoid them (but it looks cute in the demo).
Documentation
¶
Overview ¶
Package acidtab prints aligned tables.
Example (Basic) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
// Create a new table
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
// Add rows to it
t.Row("James Holden", "Montana", "Captain", "Tilting windmills", true)
t.Row("Amos Burton", "Baltimore", "Mechanic", "Specific people skills", true)
// And then print it:
t.Horizontal(os.Stdout)
}
Output: Name │ Origin │ Job │ Speciality │ Alive ────────────────┼─────────────┼────────────┼──────────────────────────┼───────── James Holden │ Montana │ Captain │ Tilting windmills │ true Amos Burton │ Baltimore │ Mechanic │ Specific people skills │ true
Example (Chain) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
acidtab.New("Name", "Origin", "Job", "Speciality", "Alive").
Close(acidtab.CloseTop|acidtab.CloseBottom).
Prefix(" ").
Pad(" ").
FormatCol(1, "%q").
Rows(
"Adolphus Murtry", "Earth", "Security", "General twattery", false,
"Fred Johnson", "Earth", "Colonol", "Beltalowda", false,
).
Vertical(os.Stdout)
}
Output: ────────────┬────────────────── Name │ Adolphus Murtry Origin │ "Earth" Job │ Security Speciality │ General twattery Alive │ false ────────────┼────────────────── Name │ Fred Johnson Origin │ "Earth" Job │ Colonol Speciality │ Beltalowda Alive │ false ────────────┴──────────────────
Example (Coloptions) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
t.Close(acidtab.CloseLeft | acidtab.CloseRight)
t.AlignCol(3, acidtab.Right) // Align column 3 and 4 (starts at 0)
t.AlignCol(4, acidtab.Center)
t.FormatCol(3, "%q") // Print column 3 as %q
// Callback for column 4
t.FormatColFunc(4, func(v interface{}) string {
if b, ok := v.(bool); ok {
return map[bool]string{true: "yes", false: "no"}[b]
}
// Return a NULL byte to fall back to regular formatting.
return "\x00"
})
t.Row("Joe Miller", "Ceres", "Cop", "Doors 'n corners", false)
t.Row("Chrisjen Avasarala", "Earth", "Politician", "Insults", true)
t.Horizontal(os.Stdout)
}
Output: │ Name │ Origin │ Job │ Speciality │ Alive │ ├──────────────────────┼──────────┼──────────────┼──────────────────────┼─────────┤ │ Joe Miller │ Ceres │ Cop │ "Doors 'n corners" │ no │ │ Chrisjen Avasarala │ Earth │ Politician │ "Insults" │ yes │
Example (Format) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
bold := func(s string) string { return "\x1b[1m" + s + "\x1b[0m" }
t := acidtab.New(bold("Name"), bold("Origin"), bold("Job"), bold("Speciality"), bold("Alive")).
Close(acidtab.CloseAll).
AlignCol(4, acidtab.Center).
FormatColFunc(4, func(v interface{}) string {
if b, ok := v.(bool); ok {
return map[bool]string{
true: "\x1b[32m ✔ \x1b[0m",
false: "\x1b[31m✘\x1b[0m",
}[b]
}
return "\x00"
})
t.Rows(
"James Holden", "Montana 🌎", "Captain 🚀", "Tilting windmills", true,
"Amos Burton", "Baltimore 🌎", "Mechanic 🔧", "Specific people skills", true,
"Naomi Nagata", "Pallas 🌌", "Mechanic 💻", "Spicy red food", true,
"Alex Kamal", "Mars 🔴", "Pilot 🎧", "Cowboys", false,
"Joe Miller", "Ceres 🌌", "Cop 👮", "Doors 'n corners", true,
"Chrisjen Avasarala", "Earth 🌏", "Politician 🖕", "Insults", true,
"Prax Meng", "Ganymede 🌌", "Botanist 🌻", "Plant metaphors", true,
"Klaes Ashford", "The belt 🌌", "Pirate 🕱", "Singing", "😢",
"Adolphus Murtry", "Earth 🌎", "Security 💂", "General twattery", false,
"Fred Johnson", "Earth 🌎", "Colonol 🎖", "Beltalowda", false)
t.Horizontal(os.Stdout)
}
Output: ┌──────────────────────┬────────────────┬─────────────────┬──────────────────────────┬─────────┐ │ �[1mName�[0m │ �[1mOrigin�[0m │ �[1mJob�[0m │ �[1mSpeciality�[0m │ �[1mAlive�[0m │ ├──────────────────────┼────────────────┼─────────────────┼──────────────────────────┼─────────┤ │ James Holden │ Montana 🌎 │ Captain 🚀 │ Tilting windmills │ �[32m ✔ �[0m │ │ Amos Burton │ Baltimore 🌎 │ Mechanic 🔧 │ Specific people skills │ �[32m ✔ �[0m │ │ Naomi Nagata │ Pallas 🌌 │ Mechanic 💻 │ Spicy red food │ �[32m ✔ �[0m │ │ Alex Kamal │ Mars 🔴 │ Pilot 🎧 │ Cowboys │ �[31m✘�[0m │ │ Joe Miller │ Ceres 🌌 │ Cop 👮 │ Doors 'n corners │ �[32m ✔ �[0m │ │ Chrisjen Avasarala │ Earth 🌏 │ Politician 🖕 │ Insults │ �[32m ✔ �[0m │ │ Prax Meng │ Ganymede 🌌 │ Botanist 🌻 │ Plant metaphors │ �[32m ✔ �[0m │ │ Klaes Ashford │ The belt 🌌 │ Pirate 🕱 │ Singing │ 😢 │ │ Adolphus Murtry │ Earth 🌎 │ Security 💂 │ General twattery │ �[31m✘�[0m │ │ Fred Johnson │ Earth 🌎 │ Colonol 🎖 │ Beltalowda │ �[31m✘�[0m │ └──────────────────────┴────────────────┴─────────────────┴──────────────────────────┴─────────┘
Example (Options) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
t.Borders(acidtab.BordersHeavy) // Set different borders.
t.Pad(" ") // Pad cells with one space.
t.Prefix(" ") // Prefix every line with a space.
t.Close(acidtab.CloseTop | acidtab.CloseBottom) // "Close" top and bottom.
t.Header(false) // Don't print the header.
t.Row("Naomi Nagata", "Pallas", "Mechanic", "Spicy red food", true)
t.Row("Alex Kamal", "Mars", "Pilot", "Cowboys", false)
t.Horizontal(os.Stdout)
}
Output: ━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━ Naomi Nagata ┃ Pallas ┃ Mechanic ┃ Spicy red food ┃ true Alex Kamal ┃ Mars ┃ Pilot ┃ Cowboys ┃ false ━━━━━━━━━━━━━━┻━━━━━━━━┻━━━━━━━━━━┻━━━━━━━━━━━━━━━━┻━━━━━━━
Example (StringRows) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
bold := func(s string) string { return "\x1b[1m" + s + "\x1b[0m" }
t := acidtab.New(bold("Name"), bold("Origin"), bold("Job"), bold("Speciality"), bold("Alive")).
Close(acidtab.CloseAll).
AlignCol(4, acidtab.Center).
FormatColFunc(4, func(v interface{}) string {
if b, ok := v.(bool); ok {
return map[bool]string{
true: "\x1b[32m ✔ \x1b[0m",
false: "\x1b[31m✘\x1b[0m",
}[b]
}
return "\x00"
})
t.RowsFromString("|", "\n", false, `
James Holden | Montana 🌎 | Captain 🚀 | Tilting windmills | true
Amos Burton | Baltimore 🌎 | Mechanic 🔧 | Specific people skills | true
Naomi Nagata | Pallas 🌌 | Mechanic 💻 | Spicy red food | true
Alex Kamal | Mars 🔴 | Pilot 🎧 | Cowboys | false
Joe Miller | Ceres 🌌 | Cop 👮 | Doors 'n corners | true
Chrisjen Avasarala | Earth 🌏 | Politician 🖕 | Insults | true
Prax Meng | Ganymede 🌌 | Botanist 🌻 | Plant metaphors | true
Klaes Ashford | The belt 🌌 | Pirate 🕱 | Singing | 😢
Adolphus Murtry | Earth 🌎 | Security 💂 | General twattery | false
Fred Johnson | Earth 🌎 | Colonol 🎖 | Beltalowda | false
`)
t.Horizontal(os.Stdout)
}
Output: ┌──────────────────────┬────────────────┬─────────────────┬──────────────────────────┬─────────┐ │ �[1mName�[0m │ �[1mOrigin�[0m │ �[1mJob�[0m │ �[1mSpeciality�[0m │ �[1mAlive�[0m │ ├──────────────────────┼────────────────┼─────────────────┼──────────────────────────┼─────────┤ │ James Holden │ Montana 🌎 │ Captain 🚀 │ Tilting windmills │ true │ │ Amos Burton │ Baltimore 🌎 │ Mechanic 🔧 │ Specific people skills │ true │ │ Naomi Nagata │ Pallas 🌌 │ Mechanic 💻 │ Spicy red food │ true │ │ Alex Kamal │ Mars 🔴 │ Pilot 🎧 │ Cowboys │ false │ │ Joe Miller │ Ceres 🌌 │ Cop 👮 │ Doors 'n corners │ true │ │ Chrisjen Avasarala │ Earth 🌏 │ Politician 🖕 │ Insults │ true │ │ Prax Meng │ Ganymede 🌌 │ Botanist 🌻 │ Plant metaphors │ true │ │ Klaes Ashford │ The belt 🌌 │ Pirate 🕱 │ Singing │ 😢 │ │ Adolphus Murtry │ Earth 🌎 │ Security 💂 │ General twattery │ false │ │ Fred Johnson │ Earth 🌎 │ Colonol 🎖 │ Beltalowda │ false │ └──────────────────────┴────────────────┴─────────────────┴──────────────────────────┴─────────┘
Example (Vertical) ¶
package main
import (
"os"
"zgo.at/acidtab"
)
func main() {
t := acidtab.New("Name", "Origin", "Job", "Speciality", "Alive")
t.Row("Prax Meng", "Ganymede", "Botanist", "Plant metaphors", true)
t.Row("Klaes Ashford", "The belt", "Pirate", "Singing", "😢")
t.Vertical(os.Stdout)
}
Output: Name │ Prax Meng Origin │ Ganymede Job │ Botanist Speciality │ Plant metaphors Alive │ true ──────────────┼─────────────────── Name │ Klaes Ashford Origin │ The belt Job │ Pirate Speciality │ Singing Alive │ 😢
Index ¶
- Variables
- type Align
- type Borders
- type Close
- type FormatAs
- type FormatAsFunc
- type Table
- func (t *Table) AlignCol(n int, a Align) *Table
- func (t *Table) Borders(borders Borders) *Table
- func (t *Table) Close(close Close) *Table
- func (t Table) Error() error
- func (t *Table) FormatCol(n int, p FormatAs) *Table
- func (t *Table) FormatColFunc(n int, p FormatAsFunc) *Table
- func (t *Table) Grow(n int)
- func (t *Table) Header(show bool, header ...string) *Table
- func (t Table) Horizontal(w io.Writer)
- func (t *Table) Pad(pad string) *Table
- func (t *Table) Prefix(prefix string) *Table
- func (t *Table) Row(r ...interface{}) *Table
- func (t *Table) Rows(r ...interface{}) *Table
- func (t *Table) RowsFromString(colDelim, rowDelim string, header bool, rows string) *Table
- func (t Table) String() string
- func (t Table) Vertical(w io.Writer)
- func (t *Table) Width() int
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( BordersDefault = Borders{'─', '│', '┼', '┌', '┐', '└', '┘', '├', '┤', '┬', '┴'} BordersHeavy = Borders{'━', '┃', '╋', '┏', '┓', '┗', '┛', '┣', '┫', '┳', '┻'} BordersDouble = Borders{'═', '║', '╬', '╔', '╗', '╚', '╝', '╠', '╣', '╦', '╩'} BordersASCII = Borders{'-', '|', '+', '+', '+', '+', '+', '+', '+', '+', '+'} BordersSpace = Borders{' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' '} )
Characters to use to draw the borders.
Functions ¶
This section is empty.
Types ¶
type Borders ¶
type Borders struct {
Line, Bar, Cross rune
TopLeft, TopRight, BottomLeft, BottomRight rune
BarRight, BarLeft, LineTop, LineBottom rune
}
Borders to use.
type Close ¶
type Close uint8 // Which sides of the table to "close".
const ( CloseBottom Close = 1 << iota CloseTop CloseLeft CloseRight CloseAll Close = CloseBottom | CloseTop | CloseLeft | CloseRight )
Which sides to close.
type FormatAs ¶
type FormatAs string // How to print a value; fmt format string (e.g. "%q", "%#v", etc.)
type FormatAsFunc ¶
type FormatAsFunc func(v interface{}) string
func FormatAsFloat ¶
func FormatAsFloat(perc int) FormatAsFunc
FormatAsFloat prints n as a float with the given percision.
Use perc=0 to round to the nearest natural number.
func FormatAsNum ¶
func FormatAsNum() FormatAsFunc
FormatAsNum prints n as a number with , as thousands separators.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table defines a table to print.
func (*Table) AlignCol ¶
AlignCol sets the alignment for column n.
The default is right-aligned for numbers, and left-aligned for everything else.
func (Table) Error ¶
Error returns any error that may have happened when setting the data.
The print functions will never set an error.
func (*Table) FormatCol ¶
FormatCol sets how to format column n, as fmt format string (e.g. "%q", "%#v", etc.)
func (*Table) FormatColFunc ¶
func (t *Table) FormatColFunc(n int, p FormatAsFunc) *Table
FormatColFunc sets a callback function to print a cell.
func (*Table) Header ¶
Header sets the header.
The show parameter controls if the header is printed.
If the list of headers is given then it will use this as the headers, overriding any previously set headers.
func (Table) Horizontal ¶
func (*Table) Row ¶
Row adds a new row.
Remaining columns will be filled with spaces if the number of values is lower than the numbers of headers. It will set an error if the number of values is greater.
func (*Table) Rows ¶
Rows adds multiple rows; the number of values should be an exact multitude of the number of headers; it will set an error if it's not.
For example:
t.Rows(
"row1", "row1",
"row2", "row2",)
func (*Table) RowsFromString ¶
RowsFromString adds multiple rows from a single string. Columns are separated by colDelim, and rows by rowDelim.
Leading and trailing whitespace will be removed, as will all whitespace surrounding the colDelim. All items will be added as strings, but you can still parse/format things with FormatColFunc().
For example:
t.Rows("|", "\n", `
row1 | row1
row2 | row2
`)
If header is set the first row will be used as the header, overriding any header that was given with New().
The biggest advantage is that it looks a bit nicer if you want to print out loads of static data, since gofmt doesn't format it too well. It's also a bit easier to write.
Another use case is to feed output from a program or function.
Source Files