tobble

Tobble is a table library for Gleam, which makes it as easy as possible to render tables from simple output. It does provide some customization options, but they are not very expansive, as Tobble does not aim to be a full layout library. Rather, it aims to make it simple to make beautiful output for your programs.

import gleam/io
import tobble

pub fn main() {
  let assert Ok(table) =
    tobble.builder()
    |> tobble.add_row(["", "Output"])
    |> tobble.add_row(["Stage 1", "Wibble"])
    |> tobble.add_row(["Stage 2", "Wobble"])
    |> tobble.add_row(["Stage 3", "WibbleWobble"])
    |> tobble.build()

  io.println(tobble.render(table))
}

+---------+--------------+
|         | Output       |
+---------+--------------+
| Stage 1 | Wibble       |
| Stage 2 | Wobble       |
| Stage 3 | WibbleWobble |
+---------+--------------+

Types

Builder

opaque </>

Builder is a type used to help you build tables. See builder for more details.

pub opaque type Builder

BuilderError

</>

pub type BuilderError {
  InconsistentColumnCountError(expected: Int, got: Int)
  EmptyTableError
  EmptyTitleError
}

Constructors

```
InconsistentColumnCountError(expected: Int, got: Int)
```
Returned when not all rows have the same number of columns.

Why is this an error? It is not possible to render a rectangular table if any row has a different number of columns than another.
```
EmptyTableError
```
Returned when attempting to build a table with no rows.

Why is this an error? It is somewhat unclear how to render this, and is left as an error so callers can handle it however is best for their application.
```
EmptyTitleError
```
Returned when attempting to build a table with an empty string as the title.

Why is this an error? It is somewhat unclear how to render this, and is likely the result of a bug in your app.

Table

opaque </>

Table is the central type of Tobble. It holds the data you wish to display, without regard for how you render it. These can be built using builder/build.

pub opaque type Table

Functions

add_row

</>

pub fn add_row(
  to builder: Builder,
  columns columns: List(String),
) -> Builder

Add a row to a table that is being built. Every call to add_row for a given Builder must have the same number of columns, or an InconsistentColumnCountError will be returned when build is called.

build

</>

pub fn build(
  with builder: Builder,
) -> Result(Table, BuilderError)

Build a Table from the given Builder. If an invalid operation was performed when constructing the Builder, an error will be returned.

builder

</>

pub fn builder() -> Builder

Create a new Builder for table generation. Once you have completed adding your rows to this with add_row, you should call build to generate a Table.

render

</>

pub fn render(table table: Table) -> String

Render the given table to a String, with the default options. The output can be customized by using render_with_options.

Example

let assert Ok(table) =
    tobble.builder()
    |> tobble.add_row(["", "Output"])
    |> tobble.add_row(["Stage 1", "Wibble"])
    |> tobble.add_row(["Stage 2", "Wobble"])
    |> tobble.add_row(["Stage 3", "WibbleWobble"])
    |> tobble.build()

io.println(tobble.render(table))

+---------+--------------+
|         | Output       |
+---------+--------------+
| Stage 1 | Wibble       |
| Stage 2 | Wobble       |
| Stage 3 | WibbleWobble |
+---------+--------------+

render_iter

</>

pub fn render_iter(
  table table: Table,
  options options: List(Option),
) -> Yielder(String)

Render the given table to a Yielder. Each element of the Yielder will produce a single line of output, without a trailing newline. Note that options are applied in order, so if duplicate or conflicting options are given, the last one will win.

Example

let assert Ok(table) =
  tobble.builder()
  |> tobble.add_row(["", "Output"])
  |> tobble.add_row(["Stage 1", "Wibble"])
  |> tobble.add_row(["Stage 2", "Wobble"])
  |> tobble.add_row(["Stage 3", "WibbleWobble"])
  |> tobble.build()


table
|> tobble.render_iter(options: [])
|> yielder.each(io.println)

+---------+--------------+
|         | Output       |
+---------+--------------+
| Stage 1 | Wibble       |
| Stage 2 | Wobble       |
| Stage 3 | WibbleWobble |
+---------+--------------+

render_with_options

</>

pub fn render_with_options(
  table table: Table,
  options options: List(Option),
) -> String

Render the given table to a String, with extra options (found in tobble/table_render_opts). Note that options are applied in order, so if duplicate or conflicting options are given, the last one will win.

let assert Ok(table) =
  tobble.builder()
  |> tobble.add_row(["", "Output"])
  |> tobble.add_row(["Stage 1", "Wibble"])
  |> tobble.add_row(["Stage 2", "Wobble"])
  |> tobble.add_row(["Stage 3", "WibbleWobble"])
  |> tobble.build()

io.println(
  tobble.render_with_options(table, options: [
    table_render_opts.column_width(6),
    table_render_opts.horizontal_rules_after_every_row(),
]),
)

+--------+--------+
|        | Output |
+--------+--------+
| Stage  | Wibble |
| 1      |        |
+--------+--------+
| Stage  | Wobble |
| 2      |        |
+--------+--------+
| Stage  | Wibble |
| 3      | Wobble |
+--------+--------+

set_title

</>

pub fn set_title(
  to builder: Builder,
  title title: String,
) -> Builder

Set a title for a table that is being built. The title must be a non-empty string or a TitleEmptyError will be returned when build is called.

Example

let assert Ok(table) =
  tobble.builder()
  |> tobble.set_title("Setup")
  |> tobble.add_row(["", "Output"])
  |> tobble.add_row(["Stage 1", "Wibble"])
  |> tobble.add_row(["Stage 2", "Wobble"])
  |> tobble.add_row(["Stage 3", "WibbleWobble"])
  |> tobble.build()

io.println(tobble.render(table))

         Setup
+---------+--------------+
|         | Output       |
+---------+--------------+
| Stage 1 | Wibble       |
| Stage 2 | Wobble       |
| Stage 3 | WibbleWobble |
+---------+--------------+

title

</>

pub fn title(table: Table) -> Option(String)

Get the title of a table, if there is one.

Example

let assert Ok(table) =
  tobble.builder()
  |> tobble.set_title("Setup")
  |> tobble.add_row(["", "Output"])
  |> tobble.add_row(["Stage 1", "Wibble"])
  |> tobble.add_row(["Stage 2", "Wobble"])
  |> tobble.add_row(["Stage 3", "WibbleWobble"])
  |> tobble.build()

io.debug(tobble.title(table))

Some("Setup")

to_list

</>

pub fn to_list(table: Table) -> List(List(String))

Convert an existing table to a list of its rows.

Example

let assert Ok(table) =
  tobble.builder()
  |> tobble.add_row(["", "Output"])
  |> tobble.add_row(["Stage 1", "Wibble"])
  |> tobble.add_row(["Stage 2", "Wobble"])
  |> tobble.add_row(["Stage 3", "WibbleWobble"])
  |> tobble.build()

io.debug(tobble.to_list(table))

[
  ["", "Output"],
  ["Stage 1", "Wibble"],
  ["Stage 2", "Wobble"],
  ["Stage 3", "WibbleWobble"]
]