Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/reminder.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
name: reminder

on:
schedule:
- cron: "0 9 1 * *"

permissions:
issues: write

jobs:
remind:
runs-on: ubuntu-latest
steps:
- name: Open a comparison refresh issue when none is open
uses: actions/github-script@v9
with:
script: |
const runReminder = require(`${process.env.GITHUB_WORKSPACE}/scripts/reminder.js`);
await runReminder({ github, context, core });
206 changes: 66 additions & 140 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,188 +1,114 @@
# Simple tables in terminal with Go

[![Quality gates](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml/badge.svg)](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml) [![Coverage Status](https://coveralls.io/repos/github/alexeyco/simpletable/badge.svg?branch=master)](https://coveralls.io/github/alexeyco/simpletable?branch=master) [![Go Reference](https://pkg.go.dev/badge/github.com/alexeyco/simpletable.svg)](https://pkg.go.dev/github.com/alexeyco/simpletable)
![simpletable banner](assets/banner.svg)

This package allows to generate and display ascii tables in the terminal, f.e.:
[![Quality gates](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml/badge.svg)](https://github.com/alexeyco/simpletable/actions/workflows/quality-gates.yml) [![Coverage Status](https://coveralls.io/repos/github/alexeyco/simpletable/badge.svg?branch=master)](https://coveralls.io/github/alexeyco/simpletable?branch=master) [![Go Reference](https://pkg.go.dev/badge/github.com/alexeyco/simpletable.svg)](https://pkg.go.dev/github.com/alexeyco/simpletable) [![License](https://img.shields.io/github/license/alexeyco/simpletable)](LICENSE)

```
+----+------------------+--------------+-----------------------------+------+
| # | NAME | PHONE | EMAIL | QTTY |
+----+------------------+--------------+-----------------------------+------+
| 1 | Newton G. Goetz | 252-585-5166 | NewtonGGoetz@dayrep.com | 10 |
| 2 | Rebecca R. Edney | 865-475-4171 | RebeccaREdney@armyspy.com | 12 |
| 3 | John R. Jackson | 810-325-1417 | JohnRJackson@armyspy.com | 15 |
| 4 | Ron J. Gomes | 217-450-8568 | RonJGomes@rhyta.com | 25 |
| 5 | Penny R. Lewis | 870-794-1666 | PennyRLewis@rhyta.com | 5 |
| 6 | Sofia J. Smith | 770-333-7379 | SofiaJSmith@armyspy.com | 3 |
| 7 | Karlene D. Owen | 231-242-4157 | KarleneDOwen@jourrapide.com | 12 |
| 8 | Daniel L. Love | 978-210-4178 | DanielLLove@rhyta.com | 44 |
| 9 | Julie T. Dial | 719-966-5354 | JulieTDial@jourrapide.com | 8 |
| 10 | Juan J. Kennedy | 908-910-8893 | JuanJKennedy@dayrep.com | 16 |
+----+------------------+--------------+-----------------------------+------+
| Subtotal | 150 |
+----+------------------+--------------+-----------------------------+------+
```
Build readable terminal tables in Go with seven built-in styles, multiline cells, alignment, and column spanning.

There are the following key features:
* **Declarative style.** _Have to write more code, and hell with it._
* **Styling.** _With 7 predefined styles: MySql-like (default), compact, compact lite, compact classic, markdown,
rounded and unicode. And you can change it._
* **Header and footer.** _Separated from table body._
* **Multiline cells support.** _See [_example/main.go/_example/04-multiline/main.go](https://github.com/alexeyco/simpletable/blob/master/_example/04-multiline/main.go) for example._
* **Cell content alignment.** _Left, right or center._
* **Row spanning.** _By analogy with the way it is done in HTML. See `Cell.Span` attribute
description._
* **Fast!** _Really fast, see [_example/main.go/_example/03-benchmarks-with-others](https://github.com/alexeyco/simpletable/blob/master/_example/03-benchmarks-with-others)._

## Installation
```
$ go get -u github.com/alexeyco/simpletable
```
To run unit tests:
```
$ cd $GOPATH/src/github.com/alexeyco/simpletable
$ go test -cover
```
To run benchmarks:
```
$ cd $GOPATH/src/github.com/alexeyco/simpletable
$ go test -bench=.
```
Comparison with similar libraries see [_example/main.go/_example/03-benchmarks-with-others](https://github.com/alexeyco/simpletable/blob/master/_example/03-benchmarks-with-others)
## Comparison

✅ documented · ⚠️ partial · ❌ not found in sources checked. The last status means the sources checked did not document the feature; it does not establish that the library lacks it. Each symbol links to the public source checked for that comparison.

| Feature | [simpletable](https://github.com/alexeyco/simpletable) | [termtables](https://pkg.go.dev/github.com/apcera/termtables) | [uitable](https://github.com/gosuri/uitable) | [tablewriter](https://github.com/olekukonko/tablewriter) | [go-pretty](https://github.com/jedib0t/go-pretty) |
| --- | --- | --- | --- | --- | --- |
| Multiline cell content | [✅](https://github.com/alexeyco/simpletable/blob/master/_example/04-multiline/main.go) | [❌](https://pkg.go.dev/github.com/apcera/termtables) | [⚠️](https://github.com/gosuri/uitable#example-usage) | [⚠️](https://github.com/olekukonko/tablewriter#advanced-examples) | [❌](https://github.com/jedib0t/go-pretty/tree/main/table) |
| Explicit column spans | [✅](https://github.com/alexeyco/simpletable/blob/master/cell.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#CellStyle) | [❌](https://pkg.go.dev/github.com/gosuri/uitable) | [⚠️](https://github.com/olekukonko/tablewriter#examples) | [⚠️](https://github.com/jedib0t/go-pretty/tree/main/table) |
| Markdown output | [✅](https://github.com/alexeyco/simpletable/blob/master/style.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#Table.SetModeMarkdown) | [❌](https://github.com/gosuri/uitable) | [✅](https://github.com/olekukonko/tablewriter#key-features) | [✅](https://github.com/jedib0t/go-pretty) |
| Alignment controls | [✅](https://github.com/alexeyco/simpletable/blob/master/cell.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#Table.SetAlign) | [⚠️](https://pkg.go.dev/github.com/gosuri/uitable#Table.RightAlign) | [✅](https://github.com/olekukonko/tablewriter#examples) | [✅](https://github.com/jedib0t/go-pretty/tree/main/table) |
| Custom table styles | [✅](https://github.com/alexeyco/simpletable/blob/master/style.go) | [✅](https://pkg.go.dev/github.com/apcera/termtables#TableStyle) | [❌](https://pkg.go.dev/github.com/gosuri/uitable) | [✅](https://github.com/olekukonko/tablewriter#key-features) | [✅](https://github.com/jedib0t/go-pretty/tree/main/table) |

Sources checked on 2026-11-09. Add a library as a column or a feature as a row, and link each status to the public source checked.

## Quick start

## Basic example
```go
package main

import (
"fmt"
"strings"

"github.com/alexeyco/simpletable"
)

var (
data = [][]interface{}{
{1, "Newton G. Goetz", 532.7},
{2, "Rebecca R. Edney", 1423.25},
{3, "John R. Jackson", 7526.12},
{4, "Ron J. Gomes", 123.84},
{5, "Penny R. Lewis", 3221.11},
}
)

func main() {
table := simpletable.New()

table.Header = &simpletable.Header{
Cells: []*simpletable.Cell{
{Align: simpletable.AlignCenter, Text: "#"},
{Align: simpletable.AlignCenter, Text: "NAME"},
{Align: simpletable.AlignCenter, Text: "TAX"},
},
}
rows := []struct {
name string
tax float64
}{
{"Newton G. Goetz", 532.70},
{"Rebecca R. Edney", 1423.25},
{"John R. Jackson", 7526.12},
{"Ron J. Gomes", 123.84},
{"Penny R. Lewis", 3221.11},
}

subtotal := float64(0)
for _, row := range data {
r := []*simpletable.Cell{
{Align: simpletable.AlignRight, Text: fmt.Sprintf("%d", row[0].(int))},
{Text: row[1].(string)},
{Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", row[2].(float64))},
}
total := 0.0
for i, row := range rows {
table.Body.Cells = append(table.Body.Cells, []*simpletable.Cell{
{Align: simpletable.AlignRight, Text: fmt.Sprintf("%d", i+1)},
{Text: row.name},
{Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", row.tax)},
})

table.Body.Cells = append(table.Body.Cells, r)
subtotal += row[2].(float64)
total += row.tax
}

table.Footer = &simpletable.Footer{
Cells: []*simpletable.Cell{
{},
{Align: simpletable.AlignRight, Text: "Subtotal"},
{Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", subtotal)},
{Align: simpletable.AlignRight, Span: 2, Text: "Subtotal"},
{Align: simpletable.AlignRight, Text: fmt.Sprintf("$ %.2f", total)},
},
}

table.SetStyle(simpletable.StyleCompactLite)
fmt.Println(table.String())

for _, line := range strings.Split(table.String(), "\n") {
fmt.Println(strings.TrimPrefix(strings.TrimRight(line, " "), " "))
}
}
```

Result:
```
# NAME TAX
# NAME TAX
--- ------------------ ------------
1 Newton G. Goetz $ 532.70
2 Rebecca R. Edney $ 1423.25
3 John R. Jackson $ 7526.12
4 Ron J. Gomes $ 123.84
5 Penny R. Lewis $ 3221.11
1 Newton G. Goetz $ 532.70
2 Rebecca R. Edney $ 1423.25
3 John R. Jackson $ 7526.12
4 Ron J. Gomes $ 123.84
5 Penny R. Lewis $ 3221.11
--- ------------------ ------------
Subtotal $ 12827.02
Subtotal $ 12827.02
```

You can see also [_example/main.go/01-styles-demo/main.go](https://github.com/alexeyco/simpletable/blob/master/_example/01-styles-demo/main.go) for styles demonstration.
```
$ cd $GOPATH/src/github.com/alexeyco/simpletable/_example/01-styles-demo
$ go run main.go
```
Install with `go get github.com/alexeyco/simpletable`.

More examples:
For more examples see [_example](https://github.com/alexeyco/simpletable/tree/master/_example) directory:
```
$ cd $GOPATH/src/github.com/alexeyco/simpletable/_example
$ ls -F | grep /
See the [styles demo](https://github.com/alexeyco/simpletable/tree/master/_example/01-styles-demo), [multiline example](https://github.com/alexeyco/simpletable/tree/master/_example/04-multiline), and [column-span example](https://github.com/alexeyco/simpletable/tree/master/_example/02-ugly-span) for more.

01-styles-demo/
02-ugly-span/
03-benchmarks-with-others/
04-multiline/
```
## Benchmarks

## Styling
There is 6 styles available. To view them, run [_example/main.go/01-styles-demo/main.go](https://github.com/alexeyco/simpletable/blob/master/_example/01-styles-demo/main.go):
```
$ cd $GOPATH/src/github.com/alexeyco/simpletable/_example/01-styles-demo
$ go run main.go
```
<details>
<summary>(MacBook)</summary>

## Cell content alignment
You can set cell content alignment:
```go
c := &simpletable.Cell{
// or simpletable.AlignLeft (default), or simpletable.AlignCenter
Align: simpletable.AlignRight,
Content: "Subtotal",
}
```
Run these benchmarks using the [benchmark instructions](https://github.com/alexeyco/simpletable/tree/master/_example/03-benchmarks-with-others#run-benchmarks).

## Column spanning
By analogy with HTML:
```go
c := &simpletable.Cell{
Span: 2, // Default: 1
Content: "Subtotal",
}
```
Note: by default `Span` is `1`. If you try to set it to `0`, the value will still be `1`.
BenchmarkSimpletable-12 31845 37586 ns/op 34903 B/op 760 allocs/op
BenchmarkTermtables-12 34851 34191 ns/op 24192 B/op 755 allocs/op
BenchmarkUITable-12 6452 176884 ns/op 55480 B/op 3070 allocs/op
PASS
ok github.com/alexeyco/simpletable/_example/03-benchmarks-with-others/bench 5.172s
```

</details>

## License
```
Copyright (c) 2017 Alexey Popov

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

[MIT](LICENSE)
9 changes: 1 addition & 8 deletions _example/03-benchmarks-with-others/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,4 @@ $ cd $GOPATH/src/github.com/alexeyco/simpletable/_example/03-benchmarks-with-oth
$ go test -bench=. -benchmem
```
## Results
Intel Core i5 (3470), 8Gb DDR3 memory, Windows 10 results:
```
BenchmarkSimpletable-4 10000 186476 ns/op 45651 B/op 1330 allocs/op
BenchmarkTermtables-4 10000 130461 ns/op 27632 B/op 1164 allocs/op
BenchmarkUITable-4 10000 229150 ns/op 39425 B/op 1073 allocs/op
PASS
ok github.com/alexeyco/simpletable/_example/03-benchmarks-with-others/bench 5.559s
```
See the [current benchmark results in the root README](../../README.md#benchmarks).
33 changes: 33 additions & 0 deletions assets/banner.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-09
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Design

## Approach

Create a standalone wide SVG banner in `assets/banner.svg`. Use an asymmetrical broken-grid and row motif to suggest tabular structure without depicting a rendered table. Keep the package-name wordmark, package-specific caption, and accent replaceable; apply the accent to selected strokes or cells. The simpletable version uses blue and displays `Simple tables in terminal with Go`. The README starts with the heading `# Simple tables in terminal with Go`, then references the banner before its badges, followed by the package summary, an evidence-linked feature matrix, and a compact example. Put detailed benchmark output inside an HTML `<details>` element so it remains available without interrupting the primary reading path.

Keep the feature comparison as a Markdown table in `README.md`. Use a fixed legend with `✅ documented`, `⚠️ partial`, and `❌ not found in sources checked`. The cross label describes the public sources checked and does not assert that a feature is absent. Link each library and comparison claim to the relevant public sources checked and include a last-checked date. Add new libraries as columns and new capabilities as rows. The initial libraries are simpletable, termtables, uitable, tablewriter, and go-pretty.

Rerun the existing benchmark suite with `go test -bench=. -benchmem` from `_example/03-benchmarks-with-others/bench` on the user's MacBook. Replace the historical output rather than relabeling the Windows measurements. Keep the benchmark harness and its comparator set unchanged; put the refreshed results in the root README's collapsible section. Keep the example README as the reproducible invocation guide and link it to the results in the root README.

Add `.github/workflows/reminder.yml` with a monthly schedule. Keep the issue lookup and creation logic in `scripts/reminder.js`, invoked by the workflow. The script checks for an already-open comparison-refresh issue and only creates one when none exists. Grant only the issue-write permission required to create the reminder. Keep the README's displayed Quick start output identical to the output produced by its code.

## Files to touch

- `assets/banner.svg` — reusable wide banner with an asymmetrical broken-grid and row motif, replaceable package-name wordmark, and accent on selected strokes or cells; blue for simpletable.
- `README.md` — opening structure, evidence-linked comparison, short example that produces its displayed ASCII table, corrected feature count, collapsible benchmark results, and license link.
- `_example/03-benchmarks-with-others/README.md` — benchmark invocation instructions and a link to the current results in the root README.
- `.github/workflows/reminder.yml` — monthly comparison-refresh issue workflow.
- `scripts/reminder.js` — comparison-refresh issue lookup and creation logic invoked by the workflow.

## Trade-offs

- A Markdown feature matrix is easy to extend and review in diffs; evidence links and a checked date make claims auditable without introducing a data-generation tool.
- The detailed benchmark output stays available but collapsed, so performance evidence does not dominate the README introduction.
- The comparison refresh is a scheduled issue rather than automated scraping; maintainers verify public evidence before changing claims.
Loading
Loading