tallboy

Generate pretty Unicode, ASCII or Markdown tables on the terminal for your command line programs.

tallboy is a DSL for quickly creating text based tables in Crystal.

Quick start

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 │
└────────────────┴─────────┘

# 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

Add the dependency to your shard.yml:

dependencies:
  tallboy:
    github: epoch/tallboy

Run shards install

Simple tutorial

create a table with Tallboy.table

table = Tallboy.table do
end

define columns. here we will define a 4 column table with columns.

table = Tallboy.table do
  columns do
    add "id"
    add "name"
    add "description"
    add "price
  end
end

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.

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

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.

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

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! :)

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

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.

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

render with different border styles.

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 |

tallboy supports rendering into custom IO

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   │
└───────────────────────────────────────────────────────────┘

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 - creator and maintainer

epoch/tallboy

epoch

Reviews

Repository Details