tabled

An easy to use library for pretty printing tables of Rust structs and enums.

You can do a lot of things with the library.\ If it does not do something which you feel it should or it is not clear how to, please file an issue.

This README contains lots of information but it might still be not complete,\ you can find more examples in the examples folder.

Table of Contents

• Usage
• Settings
  • Style
    • Styles
      • ascii
      • modern
      • sharp
      • rounded
      • extended
      • psql
      • markdown
      • re_structured_text
      • dots
      • ascii_rounded
      • blank
      • empty
    • Customization
    • Cell Border
    • Text on borders
    • Colorize borders
    • Theme
      • Layout
      • Colorize content
      • Column names
      • Border span correction
  • Alignment
  • Format
  • Padding
  • Margin
    • Color
  • Shadow
  • Width
    • Truncate
    • Wrapping
    • Increase width
    • Justify
    • Priority
    • Percent
  • Height
    • Height Increase
    • Height Limit
  • Rotate
  • Remove
  • Extract
  • Header and Footer and Panel
  • Merge
  • Concat
  • Highlight
  • Span
    • Horizontal span
    • Vertical span
  • Split
  • Duplicate
• Derive
  • Override a column name
  • Hide a column
  • Set column order
  • Format fields
  • Format headers
  • Inline
• Table types
  • Table
  • IterTable
  • CompactTable
  • PoolTable
  • ExtendedTable
  • Table::kv
• Tips and Tricks
  • std::fmt::* options
  • Tuple combination
  • Tuple options
  • Object
  • Builder
  • Macros
    • col and row
    • static_table
• Features
• Formats
  • json format
  • ron format
  • csv format
  • toml format
  • html format
• Notes
  • Charset
  • ANSI escape codes
  • Emoji
  • Semver
  • MSRV
  • Comparison

Usage

To print a list of structs or enums as a table, there are 2 ways.

• Using a builder pattern to build a table step by step.
• Implement a Tabled trait for your type.

A builder pattern gets handy when a data schema is unknown.\ While a typed struct is useful in cases where we know the data structure beforehand.

use tabled::{Tabled, Table};
use tabled::assert::assert_table;

#[derive(Tabled)]
struct Language {
    name: &'static str,
    designed_by: &'static str,
    invented_year: usize,
}

let languages = vec![
    Language { name: "C",    designed_by: "Dennis Ritchie",  invented_year: 1972 },
    Language { name: "Go",   designed_by: "Rob Pike",        invented_year: 2009 },
    Language { name: "Rust", designed_by: "Graydon Hoare",   invented_year: 2010 },
];

let table = Table::new(languages);

assert_table!(
    table,
    "+------+----------------+---------------+"
    "| name | designed_by    | invented_year |"
    "+------+----------------+---------------+"
    "| C    | Dennis Ritchie | 1972          |"
    "+------+----------------+---------------+"
    "| Go   | Rob Pike       | 2009          |"
    "+------+----------------+---------------+"
    "| Rust | Graydon Hoare  | 2010          |"
    "+------+----------------+---------------+"
);

The next example illustrates a builder pattern.

use tabled::{builder::Builder, settings::Style};
use tabled::assert::assert_table;

let mut b = Builder::with_capacity(3, 0);
b.push_record(["row=0 col=0", "row=0 col=1"]);
b.push_column(["row=0 col=2", "row=1 col=2"]);

let mut table = b.build();
table.with(Style::modern());

assert_table!(
    table,
    "┌─────────────┬─────────────┬─────────────┐"
    "│ row=0 col=0 │ row=0 col=1 │ row=0 col=2 │"
    "├─────────────┼─────────────┼─────────────┤"
    "│             │             │ row=1 col=2 │"
    "└─────────────┴─────────────┴─────────────┘"
);

NOTICE: In case you got to perform table rendering fast with no footprint you might be worth looking at IterTable and CompactTable.

Settings

There are a lot of functions available for your tables, as well as helpers such as derive macros and proc macros.

This section lists the settings you can apply to your table. All of the settings are leveraged by Table::with and Table::modify.

But you can tweak things yourself by using table.get_records_mut() and table.get_config_mut().\ or by creating a new setting, which is a simple do.

Style

Style sole purpouse is to configure table look. Style primarily usage is in const/static context. If you want to peak style at runtime Theme might be better suited for it.

Any Style can be customized. As well as a custom Style can be created from scratch.

use tabled::{Table, Style};

let mut table = Table::new(&data);
table.with(Style::psql());

Styles

There are numerous preconfigured styles. Below there is a rendered list of them.

If you think that there's some valuable style to be added, please open an issue.

ascii

+------+----------------+---------------+
| name | designed_by    | invented_year |
+------+----------------+---------------+
| C    | Dennis Ritchie | 1972          |
+------+----------------+---------------+
| Rust | Graydon Hoare  | 2010          |
+------+----------------+---------------+
| Go   | Rob Pike       | 2009          |
+------+----------------+---------------+

modern

┌──────┬────────────────┬───────────────┐
│ name │ designed_by    │ invented_year │
├──────┼────────────────┼───────────────┤
│ C    │ Dennis Ritchie │ 1972          │
├──────┼────────────────┼───────────────┤
│ Rust │ Graydon Hoare  │ 2010          │
├──────┼────────────────┼───────────────┤
│ Go   │ Rob Pike       │ 2009          │
└──────┴────────────────┴───────────────┘

sharp

┌──────┬────────────────┬───────────────┐
│ name │ designed_by    │ invented_year │
├──────┼────────────────┼───────────────┤
│ C    │ Dennis Ritchie │ 1972          │
│ Rust │ Graydon Hoare  │ 2010          │
│ Go   │ Rob Pike       │ 2009          │
└──────┴────────────────┴───────────────┘

rounded

╭──────┬────────────────┬───────────────╮
│ name │ designed_by    │ invented_year │
├──────┼────────────────┼───────────────┤
│ C    │ Dennis Ritchie │ 1972          │
│ Rust │ Graydon Hoare  │ 2010          │
│ Go   │ Rob Pike       │ 2009          │
╰──────┴────────────────┴───────────────╯

extended

╔══════╦════════════════╦═══════════════╗
║ name ║ designed_by    ║ invented_year ║
╠══════╬════════════════╬═══════════════╣
║ C    ║ Dennis Ritchie ║ 1972          ║
╠══════╬════════════════╬═══════════════╣
║ Rust ║ Graydon Hoare  ║ 2010          ║
╠══════╬════════════════╬═══════════════╣
║ Go   ║ Rob Pike       ║ 2009          ║
╚══════╩════════════════╩═══════════════╝

psql

 name | designed_by    | invented_year 
------+----------------+---------------
 C    | Dennis Ritchie | 1972          
 Rust | Graydon Hoare  | 2010          
 Go   | Rob Pike       | 2009          

markdown

| name | designed_by    | invented_year |
|------|----------------|---------------|
| C    | Dennis Ritchie | 1972          |
| Rust | Graydon Hoare  | 2010          |
| Go   | Rob Pike       | 2009          |

re_structured_text

====== ================ ===============
 name   designed_by     invented_year 
====== ================ ===============
 C      Dennis Ritchie   1972          
 Rust   Graydon Hoare    2010          
 Go     Rob Pike         2009          
====== ================ ===============

dots

.........................................
: name : designed_by    : invented_year :
:......:................:...............:
: C    : Dennis Ritchie : 1972          :
: Rust : Graydon Hoare  : 2010          :
: Go   : Rob Pike       : 2009          :
:......:................:...............:

ascii_rounded

.---------------------------------------.
| name | designed_by    | invented_year |
| C    | Dennis Ritchie | 1972          |
| Rust | Graydon Hoare  | 2010          |
| Go   | Rob Pike       | 2009          |
'---------------------------------------'

blank

 name   designed_by      invented_year 
 C      Dennis Ritchie   1972          
 Rust   Graydon Hoare    2010          
 Go     Rob Pike         2009                 

empty

name designed_by    invented_year
C    Dennis Ritchie 1972         
Rust Graydon Hoare  2010         
Go   Rob Pike       2009         

Style customization

You can modify existing styles to fit your needs. Mind that all modifications are done at compile time.

Check the documentation for more customization options.

If you can't make desicions at compile time - use Theme.

An example for castomization, where we remove all vertical and horizontal lines but adding single line.

use tabled::settings::{Style, HorizontalLine, VerticalLine};

let style = Style::modern()
    .horizontals([(1, HorizontalLine::inherit(Style::modern()).horizontal('═'))])
    .verticals([(1, VerticalLine::inherit(Style::modern()))])
    .remove_horizontal()
    .remove_vertical();

This style will look like the next table:

┌──────┬───────────────────────────────┐
│ name │ designed_by     invented_year │
├══════┼═══════════════════════════════┤
│ C    │ Dennis Ritchie  1972          │
│ Go   │ Rob Pike        2009          │
│ Rust │ Graydon Hoare   2010          │
└──────┴───────────────────────────────┘

As was said doing customization at constant context is not always a best choise, you may need to change a style at runtime, you may use Theme object to do that.

Theme is quite powerful by itself, you can check it in the documentation.

use tabled::grid::config::{Border, HorizontalLine};
use tabled::settings::Theme;

let mut style = Theme::default();
style.insert_horizontal_line(1, HorizontalLine::full('-', '-', '+', '+'));
style.set_frame(Border::filled('+'));

This style will look like the following:

+++++++++++++++++++++++++++++++++++++++
+ name  designed_by     invented_year +
+-------------------------------------+
+ C     Dennis Ritchie  1972          +
+ Go    Rob Pike        2009          +
+ Rust  Graydon Hoare   2010          +
+++++++++++++++++++++++++++++++++++++++

Cell Border

Sometimes tabled::Style settings are not enough. Sometimes it's necessary to change a border of a particular cell.

For this purpose you can use Border.

use tabled::{
    settings::{object::Rows, Border, Style},
    assert::assert_table,
    Table,
};

let data = [["123", "456"], ["789", "000"]];

let mut table = Table::new(data);
table.modify(
    Rows::first(),
    Border::inherit(Style::ascii())
        .top('=')
        .corner_top_left('=')
        .corner_top_right('='),
);

assert_table!(
    table,
    "============="
    "| 0   | 1   |"
    "+-----+-----+"
    "| 123 | 456 |"
    "+-----+-----+"
    "| 789 | 000 |"
    "+-----+-----+"
);

Text on borders

You can write text on any border horizontal and vertical. Just bellow you'll find a text set on first horizontal line and first vertical line. Example based on the first example in the readme.

use tabled::settings::{
    object::{Columns, Rows},
    style::LineText, Alignment,
};

table.with(LineText::new("Languages", Rows::first()).offset(2));
table.with(LineText::new("name", Columns::first()).align(Alignment::center_vertical()));

assert_table!(
    table,
    "+-Languages-------------+---------------+"
    "| name | designed_by    | invented_year |"
    "n------+----------------+---------------+"
    "a C    | Dennis Ritchie | 1972          |"
    "m------+----------------+---------------+"
    "e Go   | Rob Pike       | 2009          |"
    "+------+----------------+---------------+"
    "| Rust | Graydon Hoare  | 2010          |"
    "+------+----------------+---------------+"
);

Sometimes though it's not convenient to set a string.