Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/epoch/tallboy
Declarative API for drawing unicode/ascii character tables in crystal lang
https://github.com/epoch/tallboy
ascii-art cli colspan crystal-lang table terminal tty
Last synced: 6 days ago
JSON representation
Declarative API for drawing unicode/ascii character tables in crystal lang
- Host: GitHub
- URL: https://github.com/epoch/tallboy
- Owner: epoch
- License: mit
- Created: 2019-03-07T07:15:34.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-04-27T11:29:38.000Z (over 3 years ago)
- Last Synced: 2024-10-25T01:24:14.076Z (15 days ago)
- Topics: ascii-art, cli, colspan, crystal-lang, table, terminal, tty
- Language: Crystal
- Homepage:
- Size: 84 KB
- Stars: 56
- Watchers: 3
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-crystal - tallboy - Generate ASCII character tables with support for spanning cells over multiple columns (CLI Utils)
- awesome-crystal - tallboy - Generate ASCII character tables with support for spanning cells over multiple columns (CLI Utils)
README
# tallboy
Generate pretty **Unicode**, **ASCII** or **Markdown** tables on the terminal for your command line programs.
[tallboy](https://github.com/epoch/tallboy) is a DSL for quickly creating text based tables in [Crystal](https://crystal-lang.org/).
## Quick start
```crystal
table = Tallboy.table do
header ["name", "hex"]
row ["mistyrose", "#ffe4e1"]
row ["darkolivegreen", "#556b2f"]
row ["papayawhip", "#ffefd5"]
end
puts table
```
```
┌────────────────┬─────────┐
│ name │ hex │
├────────────────┼─────────┤
│ mistyrose │ #ffe4e1 │
│ darkolivegreen │ #556b2f │
│ papayawhip │ #ffefd5 │
└────────────────┴─────────┘
```
```crystal
# full API
table = Tallboy.table do
# define 3 columns. set first column width to 12 & align right
columns do
add "size", width: 12, align: :right
add "http method"
add "path"
end
# add header with multiple lines
header "good\nfood\nhunting", align: :right
# add header with column span on one cell
header do
cell ""
cell "routes", span: 2
end
# add header inferred from column definitions
# [size, http method, path]
header
rows [
["207 B", "post", "/dishes"],
["1.3 kB", "get", "/dishes"],
["910 B", "patch", "/dishes/:id"],
["10.2 kB", "delete", "/dishes/:id"],
]
end
puts table
```
```
┌────────────────────────────────────────┐
│ good │
│ food │
│ hunting │
├────────────┬───────────────────────────┤
│ │ routes │
├────────────┼─────────────┬─────────────┤
│ size │ http method │ path │
├────────────┼─────────────┼─────────────┤
│ 207 B │ post │ /dishes │
│ 1.3 kB │ get │ /dishes │
│ 910 B │ patch │ /dishes/:id │
│ 10.2 kB │ delete │ /dishes/:id │
└────────────┴─────────────┴─────────────┘
# draw border joints correctly even with different span sizes :)
```
## Top Features
- spanning cells across muliple columns and entire rows
- simple, readable and flexible API
- text alignment (left, right, center)
- set width and alignment for entire columns with column definitions
- static type checking for almost all DSL options
- support multi-line cells with the newline character
- full custom styling or choose from multiple border styles including ascii, unicode and markdown
- render directly into IO for better performance
## Install it as a shard
1. Add the dependency to your `shard.yml`:
```yaml
dependencies:
tallboy:
github: epoch/tallboy
```
2. Run `shards install`
## Simple tutorial
1. create a table with `Tallboy.table`
```crystal
table = Tallboy.table do
end
```
2. define columns. here we will define a 4 column table with `columns`.
```crystal
table = Tallboy.table do
columns do
add "id"
add "name"
add "description"
add "price
end
end
```
3. add rows. you can add single row with `row` or nested arrays with `rows`. values can be **any object that has a `to_s` method**.
```crystal
table = Tallboy.table do
columns do
add "id"
add "name"
add "description"
add "price"
end
rows [
[1, "cake", "goes well with pudding", 3.4],
[2, "pudding", "so good with cake!", 12.5],
[3, "burger", "from the reburgulator", 22.9],
[4, "chips", "wait you mean fries?", 5],
]
end
```
4. add header. we can manually add header with `header` with arguments or pass no arguments to inferred from column definitions. header is just a row with a border below.
```crystal
table = Tallboy.table do
columns do
add "id"
add "name"
add "description"
add "price"
end
header
rows [
[1, "cake", "goes well with pudding", 3.4],
[2, "pudding", "so good with cake!", 12.5],
[3, "burger", "from the reburgulator", 22.9],
[4, "chips", "wait you mean fries?", 5],
]
end
```
5. add footer. we can add footer with `footer`. footer is a row with border on top. If we pass a string instead of an array it will auto span all 4 columns based on the other rows defined in this table. nice! :)
```crystal
table = Tallboy.table do
columns do
add "id"
add "name"
add "description"
add "price"
end
header
rows [
[1, "cake", "goes well with pudding", 3.4],
[2, "pudding", "so good with cake!", 12.5],
[3, "burger", "from the reburgulator", 22.9],
[4, "chips", "wait you mean fries?", 5],
]
footer "43.8"
end
```
6. set column span, widths and aligments. `header`, `row` and `footer` also take blocks. here we can set column span on a cell within the footer.
```crystal
table = Tallboy.table do
columns do
add "id"
add "name"
add "description"
add "price"
end
header
rows [
[1, "cake", "goes well with pudding", 3.4],
[2, "pudding", "so good with cake!", 12.5],
[3, "burger", "from the reburgulator", 22.9],
[4, "chips", "wait you mean fries?", 5],
]
footer do
cell "total", span: 3
cell "43.8"
end
end
```
7. render with different border styles.
```crystal
puts table.render # defaults to unicode
puts table.render(:ascii) # classic look
# markdown does not support column spans and outer edge borders
# turning off top and bottom border with border set to `:none`
table = Tallboy.table(border: :none) do
header ["name", "hex"]
row ["mistyrose", "#ffe4e1"]
row ["darkolivegreen", "#556b2f"]
row ["papayawhip", "#ffefd5"]
end
puts table.render(:markdown)
```
```
| name | hex |
|----------------|---------|
| mistyrose | #ffe4e1 |
| darkolivegreen | #556b2f |
| papayawhip | #ffefd5 |
```
8. tallboy supports rendering into custom IO
```crystal
table.render(IO::Memory.new)
puts(
Tallboy.table do
row [1,2,3]
end
)
```
## How it works
Most components in tallboy can be invoked separately. The design philosophy is inspired by how web browsers renders HTML.
```
┌───────────────────────────────────────────────────────────┐
│ web browser vs tallboy │
├───────────────────────────────────────────────────────────┤
│ HTML ──> Document Object Model ──> render tree ──> pixels │
│ DSL ──> Table Object Model ──> render tree ──> text │
└───────────────────────────────────────────────────────────┘
```
```crystal
data = [
[1,2,3],
[4,5,6]
]
# TableBuilder is the DSL that returns an object model
table_object_model = Tallboy::TableBuilder.new do
rows(data)
end
# ComputedTableBuilder takes the object model and calculate widths for each cell
computed_table = Tallboy::ComputedTableBuilder.new(table_object_model).build
# RenderTreeBuilder work out borders, spans and organize into nodes to rendering
render_tree = Tallboy::RenderTreeBuilder.new(computed_table).build
# render into output with unicode border style
io = Tallboy::Renderer.new(render_tree).render
```
## API
for more examples checkout `tallboy_spec.cr`
## Contributing
Issues and pull requests are welcome on GitHub at (https://github.com/epoch/tallboy)
- [Daniel Tsui](https://github.com/epoch) - creator and maintainer