# `Owl.Table`
[🔗](https://github.com/fuelen/owl/blob/v0.13.1/lib/owl/table.ex#L1)

Draws rich, customizable tables.

# `new`

```elixir
@spec new(rows :: [row :: %{required(column) => value}, ...],
  border_style: :solid | :solid_rounded | :none | :double,
  divide_body_rows: boolean(),
  word_wrap: :break_word | :normal,
  truncate_lines: boolean(),
  filter_columns: (column -> as_boolean(term())),
  padding_x: non_neg_integer(),
  max_column_widths: (column -> pos_integer() | :infinity),
  max_width: pos_integer() | :infinity,
  render_cell:
    [
      header: (column -> Owl.Data.t()),
      body: (value -> Owl.Data.t()) | (column, value -> Owl.Data.t())
    ]
    | (value | column -> Owl.Data.t()),
  sort_columns:
    (column, column -> boolean())
    | :asc
    | :desc
    | module()
    | {:asc | :desc, module()}
) :: Owl.Data.t()
when column: any(), value: any()
```

Draws a table.

Accepts a list of maps, where each map represents a row.
The keys and values in the maps should be of type `t:Owl.Data.t/0`. Otherwise, use the `:render_cell` option to make values printable.

## Options

* `:border_style` - sets the border style. Defaults to `:solid`.
* `:divide_body_rows` - whether to show a divider between rows in the body. Prefer enabling this if cells have multi-line values. Ignored if `:border_style` is `:none`. Defaults to `false`.
* `:filter_columns` - a function that filters columns (second argument to `Enum.filter/2`). No filter function by default.
* `:padding_x` - sets horizontal padding. Defaults to `0`.
* `:render_cell` - sets how to render header and body cells. Accepts either a function or a keyword list. Defaults to `&Function.identity/1`.
Options in case of a keyword list:
  * `:header` - sets a function to render header cell. Defaults to `&Function.identity/1`.
  * `:body` - sets a function to render body cell. Defaults to `&Function.identity/1`.
* `:sort_columns` - sets a sorter (second argument to `Enum.sort/2`) for columns. Defaults to `:asc`.
* `:max_column_widths` - sets the maximum width for columns in characters. Accepts a function that returns the inner width (content + padding) for each column. Defaults to `fn _ -> :infinity end`.
* `:max_width` - sets the maximum width of the table in characters, including borders. Defaults to the terminal width or `:infinity` if a terminal is not available.
* `:word_wrap` - sets the word-wrapping mode. Can be `:break_word` or `:normal`. Defaults to `:break_word`. Ignored if `:truncate_lines` is `true`.
* `:truncate_lines` - whether to truncate lines when they reach the maximum column width. Defaults to `false`.

## Examples

    # render as is without options
    iex> [
    ...>   %{"id" => "1", "name" => "Yaroslav"},
    ...>   %{"id" => "2", "name" => "Volodymyr"}
    ...> ] |> Owl.Table.new() |> to_string()
    """
    ┌──┬─────────┐
    │id│name     │
    ├──┼─────────┤
    │1 │Yaroslav │
    │2 │Volodymyr│
    └──┴─────────┘
    """ |> String.trim_trailing()

    # ...and more complex example with a bunch of options
    iex> [
    ...>   %{a: :qwertyuiop, b: :asdfghjkl},
    ...>   %{a: :zxcvbnm, b: :dcb}
    ...> ]
    ...> |> Owl.Table.new(
    ...>   render_cell: [
    ...>     header: &(&1 |> inspect() |> Owl.Data.tag(:red)),
    ...>     body: &(&1 |> inspect() |> Owl.Data.truncate(8) |> Owl.Data.tag(:yellow))
    ...>   ],
    ...>   divide_body_rows: true,
    ...>   border_style: :solid_rounded,
    ...>   padding_x: 1,
    ...>   sort_columns: :desc
    ...> )
    ...> |> Owl.Data.to_chardata()
    ...> |> to_string()
    """
    ╭──────────┬──────────╮
    │ \e[31m:b\e[39m       │ \e[31m:a\e[39m       │
    ├──────────┼──────────┤
    │ \e[33m:asdfgh…\e[39m │ \e[33m:qwerty…\e[39m │
    ├──────────┼──────────┤
    │ \e[33m:dcb\e[39m     │ \e[33m:zxcvbnm\e[39m │
    ╰──────────┴──────────╯\e[0m
    """ |> String.trim_trailing()

---

*Consult [api-reference.md](api-reference.md) for complete listing*