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 doesn't do something which you feel it should or it's not clear how to, please file an issue.
This README contains a lot of information but it might be not complete,
you can find more examples in an examples folder.
- Usage
- Settings
- Derive
- Features
- Table types
- Formats
- Notes
To print a list of structs or enums as a table your types should implement the the Tabled trait or derive it with a #[derive(Tabled)] macro.
Most of the default types implement the trait out of the box.
use tabled::{Tabled, 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).to_string();
let expected = "+------+----------------+---------------+\n\
| name | designed_by | invented_year |\n\
+------+----------------+---------------+\n\
| C | Dennis Ritchie | 1972 |\n\
+------+----------------+---------------+\n\
| Rust | Graydon Hoare | 2010 |\n\
+------+----------------+---------------+\n\
| Go | Rob Pike | 2009 |\n\
+------+----------------+---------------+";
assert_eq!(table, expected);You can also use some of the formatting(std::fmt::*) options.
use tabled::Table;
let numbers = [1, 2, 3];
let table = Table::new(numbers);
println!("{:#^10}", table);Sometimes you can't say what type of data you are going to deal with (like parsing csv).
In such cases it may be handy to build table dynamically (step by step).
use tabled::{builder::Builder, settings::Style};
let song = r#"
And the cat's in the cradle and the silver spoon
Little boy blue and the man on the moon
When you comin' home dad?
I don't know when, but we'll get together then son
You know we'll have a good time then
"#;
let mut builder = Builder::default();
for line in song.lines() {
if line.is_empty() {
continue;
}
let words: Vec<_> = line.trim().split_terminator(' ').collect();
builder.push_record(words);
}
let columns = (0..builder.count_columns()).map(|i| i.to_string());
builder.set_header(columns);
let mut table = builder.build();
table.with(Style::ascii_rounded());
println!("{}", table);.------------------------------------------------------------------------------------.
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
| And | the | cat's | in | the | cradle | and | the | silver | spoon |
| Little | boy | blue | and | the | man | on | the | moon | |
| When | you | comin' | home | dad? | | | | | |
| I | don't | know | when, | but | we'll | get | together | then | son |
| You | know | we'll | have | a | good | time | then | | |
'------------------------------------------------------------------------------------'
You can change a table layout by Builder.
// previous example
// ...
let mut builder = builder.index();
builder.transpose();.-------------------------------------------------.
| | 0 | 1 | 2 | 3 | 4 |
| 0 | And | Little | When | I | You |
| 1 | the | boy | you | don't | know |
| 2 | cat's | blue | comin' | know | we'll |
| 3 | in | and | home | when, | have |
| 4 | the | the | dad? | but | a |
| 5 | cradle | man | | we'll | good |
| 6 | and | on | | get | time |
| 7 | the | the | | together | then |
| 8 | silver | moon | | then | |
| 9 | spoon | | | son | |
'-------------------------------------------------'
You can use Builder::index to make a particular column an index, which will stay on the left.
use tabled::{builder::Builder, settings::Style};
let mut builder = Builder::default();
builder
.set_header(["Index", "Language", "Status"])
.push_record(["1", "English", "In progress"])
.push_record(["2", "Deutsch", "Not ready"]);
let builder = builder.index().column(1).name(None);
let mut table = builder.build();
table.with(Style::rounded());
println!("{}", table);╭─────────┬───────┬─────────────╮
│ │ Index │ Status │
├─────────┼───────┼─────────────┤
│ English │ 1 │ In progress │
│ Deutsch │ 2 │ Not ready │
╰─────────┴───────┴─────────────╯
This section lists the set of settings you can apply to your table.
Most of the settings are used by .with method of Table.
You can find a list of show cases in examples folder.
There are a list of ready to use styles. Each style can be customized. A custom style also can be created from scratch.
A style can be used like this.
use tabled::{Table, Style};
let mut table = Table::new(&data);
table.with(Style::psql());Below is a rendered list of the preconfigured styles.
If you think that there's some valuable style to be added, please open an issue.
+------+----------------+---------------+
| name | designed_by | invented_year |
+------+----------------+---------------+
| C | Dennis Ritchie | 1972 |
+------+----------------+---------------+
| Rust | Graydon Hoare | 2010 |
+------+----------------+---------------+
| Go | Rob Pike | 2009 |
+------+----------------+---------------+
┌──────┬────────────────┬───────────────┐
│ name │ designed_by │ invented_year │
├──────┼────────────────┼───────────────┤
│ C │ Dennis Ritchie │ 1972 │
├──────┼────────────────┼───────────────┤
│ Rust │ Graydon Hoare │ 2010 │
├──────┼────────────────┼───────────────┤
│ Go │ Rob Pike │ 2009 │
└──────┴────────────────┴───────────────┘
┌──────┬────────────────┬───────────────┐
│ name │ designed_by │ invented_year │
├──────┼────────────────┼───────────────┤
│ C │ Dennis Ritchie │ 1972 │
│ Rust │ Graydon Hoare │ 2010 │
│ Go │ Rob Pike │ 2009 │
└──────┴────────────────┴───────────────┘
╭──────┬────────────────┬───────────────╮
│ name │ designed_by │ invented_year │
├──────┼────────────────┼───────────────┤
│ C │ Dennis Ritchie │ 1972 │
│ Rust │ Graydon Hoare │ 2010 │
│ Go │ Rob Pike │ 2009 │
╰──────┴────────────────┴───────────────╯
╔══════╦════════════════╦═══════════════╗
║ name ║ designed_by ║ invented_year ║
╠══════╬════════════════╬═══════════════╣
║ C ║ Dennis Ritchie ║ 1972 ║
╠══════╬════════════════╬═══════════════╣
║ Rust ║ Graydon Hoare ║ 2010 ║
╠══════╬════════════════╬═══════════════╣
║ Go ║ Rob Pike ║ 2009 ║
╚══════╩════════════════╩═══════════════╝
name | designed_by | invented_year
------+----------------+---------------
C | Dennis Ritchie | 1972
Rust | Graydon Hoare | 2010
Go | Rob Pike | 2009
| name | designed_by | invented_year |
|------|----------------|---------------|
| C | Dennis Ritchie | 1972 |
| Rust | Graydon Hoare | 2010 |
| Go | Rob Pike | 2009 |
====== ================ ===============
name designed_by invented_year
====== ================ ===============
C Dennis Ritchie 1972
Rust Graydon Hoare 2010
Go Rob Pike 2009
====== ================ ===============
.........................................
: name : designed_by : invented_year :
:......:................:...............:
: C : Dennis Ritchie : 1972 :
: Rust : Graydon Hoare : 2010 :
: Go : Rob Pike : 2009 :
:......:................:...............:
.---------------------------------------.
| name | designed_by | invented_year |
| C | Dennis Ritchie | 1972 |
| Rust | Graydon Hoare | 2010 |
| Go | Rob Pike | 2009 |
'---------------------------------------'
name designed_by invented_year
C Dennis Ritchie 1972
Rust Graydon Hoare 2010
Go Rob Pike 2009
name designed_by invented_year
C Dennis Ritchie 1972
Rust Graydon Hoare 2010
Go Rob Pike 2009
You can modify existing styles to fit your needs.
let style = tabled::settings::Style::modern().remove_horizontal();The style will look like the following.
┌──────┬────────────────┬───────────────┐
│ name │ designed_by │ invented_year │
│ C │ Dennis Ritchie │ 1972 │
│ Rust │ Graydon Hoare │ 2010 │
│ Go │ Rob Pike │ 2009 │
└──────┴────────────────┴───────────────┘You can change the existing styles.
use tabled::settings::style::{HorizontalLine, Style, VerticalLine};
let style = Style::modern()
.remove_horizontals()
.remove_verticals()
.horizontals([HorizontalLine::new(1, Style::modern().get_horizontal())
.main(Some('═'))
.intersection(None)])
.verticals([VerticalLine::new(1, Style::modern().get_vertical())]);The style will look like the following.
┌──────┬───────────────────────────────┐
│ name │ designed_by invented_year │
├══════┼═══════════════════════════════┤
│ C │ Dennis Ritchie 1972 │
│ Rust │ Graydon Hoare 2010 │
│ Go │ Rob Pike 2009 │
└──────┴───────────────────────────────┘Check the documentation for more customization options.
Sometimes tabled::Style settings are not enough.
Sometimes it's nesessary to change a border of a particular cell.
For this purpose you can use Border.
use tabled::{settings::{object::Rows, Border, Modify, Style}, Table};
let data = [["123", "456"], ["789", "000"]];
let table = Table::new(data)
.with(Style::ascii())
.with(Modify::new(Rows::first()).with(Border::default().top('x')))
.to_string();
let expected = "+xxxxx+xxxxx+\n\
| 0 | 1 |\n\
+-----+-----+\n\
| 123 | 456 |\n\
+-----+-----+\n\
| 789 | 000 |\n\
+-----+-----+";
assert_eq!(table, expected);You can set a string to a horizontal border line.
use tabled::{settings::style::BorderText, Table};
let mut table = Table::new(["Hello World"]);
table.with(BorderText::new("+-.table").horizontal(0));
assert_eq!(
table.to_string(),
"+-.table------+\n\
| &str |\n\
+-------------+\n\
| Hello World |\n\
+-------------+"
);Sometimes though it's not convenient to set a string. But rather necessary to set a custom char.
You can use BorderChar to achieve this.
use tabled::{
settings::{
object::Columns,
style::{BorderChar, Offset},
Modify, Style,
},
Table,
};
let table = Table::new([["Hello", "World", "!"]])
.with(Style::markdown())
.with(
Modify::new(Columns::new(..))
.with(BorderChar::horizontal(':', Offset::Begin(0)))
.with(BorderChar::horizontal(':', Offset::End(0))),
)
.to_string();
assert_eq!(
table,
"| 0 | 1 | 2 |\n\
|:-----:|:-----:|:-:|\n\
| Hello | World | ! |"
);You can set a colors of all borders using Color.
use tabled::settings::{Color, style::BorderColor};
table.with(BorderColor::default().top(Color::FG_GREEN)))You can also set a color border of intividial cell by using BorderColored.
use tabled::settings::{Modify, style::BorderColor, Color, object::Columns};
table.with(Modify::new(Columns::single(2)).with(BorderColor::default().top(Color::FG_GREEN)))You can set a horizontal and vertical alignment for any Object (e.g Columns, Rows).
use tabled::{
settings::{Modify, Alignment, object::Segment}
Table,
};
let mut table = Table::new(data);
table
.with(Modify::new(Segment::all()).with(Alignment::left()).with(Alignment::top()));The Format function provides an interface for a modification of cells.
use tabled::{
Table,
settings::{Modify, format::Format, object::{Rows, Columns}},
};
let mut table = Table::new(&data);
table
.with(Modify::new(Rows::first()).with(Format::new(|s| format!("Head {}", s))))
.with(Modify::new(Columns::new(1..=2)).with(Format::new(|s| format!("<< {} >>", s))));The Padding structure provides an interface for a left, right, top and bottom padding of cells.
use tabled::{
Table,
settings::{Modify, Padding, object::Cell}
};
let mut table = Table::new(&data);
table.with(Modify::new(Cell(0, 3)).with(Padding::new(1, 1, 0, 2)));
// It's possible to set a fill char for padding.
let mut table = Table::new(&data)
table.with(Modify::new(Cell(0, 3)).with(Padding::new(1, 1, 0, 2).fill('>', '<', '^', 'V')));You can set a color for padding characters.
BE AWARE: It only works with color feature.
use tabled::{
settings::{Color, Padding},
Table,
};
let mut table = Table::new(&data);
table.with(Padding::new(1, 1, 0, 2).colorize(
Color::FG_BLUE,
Color::FG_BLUE,
Color::FG_BLUE,
Color::FG_BLUE,
));Margin sets extra space around the border (top, bottom, left, right).
use tabled::{Table, settings::Margin};
let mut table = Table::new(&data);
table.with(Margin::new(3, 4, 1, 2).fill('>', '<', 'v', '^'));An output would depend on the data. But it could look like the following.
vvvvvvvvvvvvvvvvvvvvvvvvvvvvv
>>>┌─────────┬──────────┐<<<<
>>>│ feature │ released │<<<<
>>>│ margin │ 0.6.0 │<<<<
>>>└─────────┴──────────┘<<<<
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can set a color for padding characters.
use tabled::{
settings::{Color, Margin},
Table,
};
let mut table = Table::new(data);
table
.with(Margin::new(3, 4, 1, 2))
.with(Margin::new(1, 1, 1, 1).colorize( Color::BG_RED, Color::BG_RED, Color::BG_RED, Color::BG_RED));Shadow can be used to set a 'shadow' like margin.
use tabled::{settings::{Style, Shadow}, Table};
let data = vec![["A", "B", "C"]];
let table = Table::new(data)
.with(Style::modern())
.with(Shadow::new(1))
.to_string();
println!("{}", table);An output could look like the following.
┌───┬───┬───┐
│ 0 │ 1 │ 2 │▒
├───┼───┼───┤▒
│ A │ B │ C │▒
└───┴───┴───┘▒
▒▒▒▒▒▒▒▒▒▒▒▒▒
Using the following structures you can configure a width of a table and a single cell.
But be aware that it doesn't often consider Padding.
The functions preserves the text color.
Truncate sets a maximum width of a cell by truncating its content.
use tabled::{Table, settings::{Modify, Width, object::Rows}};
let mut table = Table::new(data);
// Truncating content to 10 chars in case it's bigger than that
// in a first row.
table.with(Modify::new(Rows::first()).with(Width::truncate(10)));
// Truncating content to 7 chars and puts a suffix '...' after it
// in all rows except a first.
table.with(Modify::new(Rows::new(1..)).with(Width::truncate(10).suffix("...")));Truncate also can be used to set a maximum width of a whole table.
use tabled::{Table, settings::Width};
let mut table = Table::new(data);
// Tries to set table width to 22, in case it's bigger than that.
table.with(Width::truncate(22));It can be used in combination with MinWidth to set an exact table size.
Wrap sets a maximum width of a cell by wrapping its content to new lines.
use tabled::{Table, settings::{Modify, Width, object::Rows}};
let mut table = Table::new(data);
// Wrap content to 10 chars in case it's bigger than that
// in a first row.
table.with(Modify::new(Rows::first()).with(Width::wrap(10)));
// Use a strategy where we try to keep words not splited (where possible).
table.with(Modify::new(Rows::new(1..)).with(Width::wrap(10).keep_words()));Wrap also can be used to set a maximum width of a whole table.
use tabled::{Table, settings::Width};
let mut table = Table::new(data);
// Tries to set table width to 22, in case it's bigger than that.
table.with(Width::wrap(22));It can be used in combination with MinWidth to set an exact table size.
MinWidth sets a minimal width of an object.
use tabled::{Table, settings::{Modify, Width, object::Rows}};
let mut table = Table::new(data);
// increase the space used by cells in all rows except the header to be at least 10
table.with(Modify::new(Rows::new(1..)).with(Width::increase(10)));MinWidth also can be used to set a minimum width of a whole table.
use tabled::{Table, settings::Width};
let mut table = Table::new(data);
// increase width of a table in case it was lower than 10.
table.with(Width::increase(10));It can be used in combination with Truncate and Wrap to set an exact table size.
You can set a constant width for all columns using Justify.
use tabled::{Table, settings::Width};
let mut table = Table::new(data);
table.with(Width::justify(10));You can tweak Truncate, Wrap, MinWidth logic by setting a priority by which a trim/inc be done.
use tabled::{Table, settings::{Width, peaker::PriorityMax}};
let mut table = Table::new(data);
table.with(Width::truncate(10).priority::<PriorityMax>());By default you use usize int to set width settings,
but you could do it also with tabled::width::Percent.
use tabled::width::{Table, settings::{measurement::Percent, Width}};
let mut table = Table::new(data);
table.with(Width::wrap(Percent(75)));You can increase a table or a specific cell height using Height motifier.
use tabled::{Table, settings::{Height, Modify, object::Rows}};
let mut table = Table::new(data);
// increase height of a table in case it was lower than 10.
table.with(Height::increase(10));
// increase height of cells in the last row on a table in case if some of them has it lower than 10.
table.with(Modify::new(Rows::last()).with(Height::increase(10)));use tabled::{Table, settings::{Height, Modify, object::Rows}};
let mut table = Table::new(data);
// decrease height of a table to 10 in case it was bigger than that.
table.with(Height::limit(10));
// decrease height of cells in the last row on a table to 10 in case if some of them has it bigger than that.
table.with(Modify::new(Rows::last()).with(Height::limit(10)));You can rotate table using tabled::Rotate.
Imagine you have a table already which output may look like this.
┌────┬──────────────┬───────────────────────────┐
│ id │ destribution │ link │
├────┼──────────────┼───────────────────────────┤
│ 0 │ Fedora │ https://getfedora.org/ │
├────┼──────────────┼───────────────────────────┤
│ 2 │ OpenSUSE │ https://www.opensuse.org/ │
├────┼──────────────┼───────────────────────────┤
│ 3 │ Endeavouros │ https://endeavouros.com/ │
└────┴──────────────┴───────────────────────────┘
Now we will add the following modificator and the output will be;
use tabled::settings::Rotate;
table.with(Rotate::Left)┌──────────────┬────────────────────────┬───────────────────────────┬──────────────────────────┐
│ link │ https://getfedora.org/ │ https://www.opensuse.org/ │ https://endeavouros.com/ │
├──────────────┼────────────────────────┼───────────────────────────┼──────────────────────────┤
│ destribution │ Fedora │ OpenSUSE │ Endeavouros │
├──────────────┼────────────────────────┼───────────────────────────┼──────────────────────────┤
│ id │ 0 │ 2 │ 3 │
└──────────────┴────────────────────────┴───────────────────────────┴──────────────────────────┘
You can remove certain rows or columns from the table.
use tabled::{Table, settings::Disable};
let mut table = Table::new(data);
table
.with(Disable::Row(..1))
.with(Disable::Column(3..4));You can Extract segments of a table to focus on a reduced number of rows and columns.
use tabled::{Table, settings::Extract};
let mut table = Table::new(&data);
table.with(Extract::segment(1..3, 1..));+-------+-------------+-----------+
| i32 | &str | bool |
+-------+-------------+-----------+ +-------------+-----------+
| : 0 : | : Grodno : | : true : | | : Grodno : | : true : |
+-------+-------------+-----------+ = +-------------+-----------+
| : 1 : | : Minsk : | : true : | | : Minsk : | : true : |
+-------+-------------+-----------+ +-------------+-----------+
| : 2 : | : Hamburg : | : false : |
+-------+-------------+-----------+
| : 3 : | : Brest : | : true : |
+-------+-------------+-----------+
For styles with unique corner and edge textures it is possible to reapply a table style once a Table extract has been created.
use tabled::{Table, settings::{Extract, Style}};
let mut table = Table::new(&data);
table
.with(Extract::segment(1..3, 1..))
.with(Style::modern());Raw extract
┼───────────────────────────┼──────────────────┼──────────────┤
│ The Dark Side of the Moon │ 01 March 1973 │ Unparalleled │
┼───────────────────────────┼──────────────────┼──────────────┤
│ Rumours │ 04 February 1977 │ Outstanding │
┼───────────────────────────┼──────────────────┼──────────────┤
Refinished extract
┌───────────────────────────┬──────────────────┬───────────────┐
│ The Dark Side of the Moon │ 01 March 1973 │ Unparalleled │
├───────────────────────────┼──────────────────┼───────────────┤
│ Rumours │ 04 February 1977 │ Outstanding │
└───────────────────────────┴──────────────────┴───────────────┘
You can add a Header and Footer to display some information.
use tabled::{Table, settings::Panel};
let mut table = Table::new(&data);
table
.with(Panel::header("Tabled Name"))
.with(Panel::footer(format!("{} elements", data.len())))The look will depend on the style you choose but it may look something like this:
┌────────────────────────────────────────────────────────────┐
│ Tabled Name │
├────────────────────────────────────────────────────────────┤
...
├───────┼──────────────┼─────────┼───────────────────────────┤
│ 3 elements │
└────────────────────────────────────────────────────────────┘
You can also add a full row/column using tabled::Panel.
use tabled::{Table, settings::Panel};
let mut table = Table::new(&data);
table
.with(Panel::vertical(2).text("A panel on 2nd row"))
.with(Panel::horizontal(0).text("A panel on 1st column"));It's possible to create "Panel"s by combining the duplicates using Merge.
use tabled::{settings::merge::Merge, Table};
let data = [['A', 'B', 'B'], ['A', 'W', 'E'], ['Z', 'Z', 'Z']];
let mut table = Table::new(data);
table.with(Merge::horizontal()).with(Merge::vertical());
println!("{}", table);+---+---+---+
| 0 | 1 | 2 |
+---+---+---+
| A | B |
+ +---+---+
| | W | E |
+---+---+---+
| Z |
+---+---+---+
You can concatanate 2 tables using Concat.
It will stick 2 tables together either vertically or horizontally.
use tabled::settings::Concat;
// let t1: Table = ...;
// let t2: Table = ...;
// vertical concat
t1.with(Concat::vertical(t2));
// horizontal concat
t1.with(Concat::horizontal(t2));Highlight can be used to change the borders of target region.
Here's an example.
use tabled::{
settings::{
object::{Columns, Object, Rows},
Border, Highlight, Style,
},
Table,
};
let data = vec![["A", "B", "C"], ["D", "E", "F"]];
let mut table = Table::new(data);
table.with(Style::modern());
table.with(Highlight::new(
Rows::first().and(Columns::single(2).and((1, 1))),
Border::filled('*'),
));
println!("{}", table);The resulting table would be the following.
*************
* 0 │ 1 │ 2 *
*****───┼───*
│ A * B │ C *
├───*****───*
│ D │ E * F *
└───┴───*****
It's possible to set a horizontal(column) span and vertical(row) span to a cell.
use tabled::{
settings::{Alignment, Modify, Span},
Table,
};
let data = vec![["A", "B", "C"], ["D", "E", "F"]];
let mut table = Table::new(data);
table
.with(Modify::new((0, 0)).with(Span::column(3)))
.with(Modify::new((1, 0)).with(Span::column(2)))
.with(Alignment::center());
println!("{}", table);+---+---+---+
| 0 |
+---+---+---+
| A | C |
+---+---+---+
| D | E | F |
+---+---+---+
use tabled::{
settings::{Alignment, Modify, Span},
Table,
};
let data = vec![["A", "B", "C"], ["D", "E", "F"]];
let mut table = Table::new(data);
table
.with(Modify::new((0, 1)).with(Span::row(3)))
.with(Alignment::center())
.with(Alignment::center_vertical());
println!("{}", table);+---+---+---+
| 0 | | 2 |
+---+ +---+
| A | 1 | C |
+---+ +---+
| D | | F |
+---+---+---+
You can Split a table on a row or column to redistribute the cells beyond that point
into a new shape with the provided point acting as the new, upper boundry in the direction selected.
Direction functions are the entry point for the Split setting.
There are two directions available: column and row.
use std::iter::FromIterator;
use tabled::{Table, settings::split::Split};
let mut table = Table::from_iter(['a'..='z']);
table.with(Split::column(12));
table.with(Split::row(2));┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │ z │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │
├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
│ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │
├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
│ y │ z │ │ │ │ │ │ │ │ │ │ │<- y and z act as anchors to new empty cells
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘ to conform to the new shape
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ a │ y │ b │ z │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │
├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤<- Display::Clean removes empty cells that would be anchors otherwise
│ m │ │ n │ │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
^anchors^
Behaviors determine how cells attempt to conform to the new tables shape.
There are two behaviors available: zip and concat.
zip is the default behavior.
use tabled::{Table, settings::split::Split};
let mut table = Table::new(&data);
table.with(Split::column(2).concat());
table.with(Split::column(2).zip()); +---+---+
| a | b |
+---+---+
+---+---+---+---+---+ | f | g |
| a | b | c | d | e | Split::column(2).concat() +---+---+
+---+---+---+---+---+ => | c | d |
| f | g | h | i | j | +---+---+
+---+---+---+---+---+ | h | i |
+---+---+
| e | |
+---+---+
| j | |
+---+---+
sect 3 +---+---+
sect 1 sect 2 (anchors) | a | b |
/ \ / \ / \ +---+---+
+---+---+---+---+---+ | c | d |
| a | b | c | d | e | Split::column(2).zip() +---+---+
+---+---+---+---+---+ => | e | |
| f | g | h | i | j | +---+---+
+---+---+---+---+---+ | f | g |
+---+---+
| h | i |
+---+---+
| j | |
+---+---+
Display functions give the user the choice to retain or clean empty sections in a Split table result.
-
retaindoes not filter any existing or newly added cells when conforming to a new shape. -
cleanfilters out empty columns/rows from the output and prevents empty cells from acting as anchors to newly inserted cells.
clean is the default Display.
use std::iter::FromIterator;
use tabled::{
settings::{split::Split, style::Style},
Table,
};
let mut table = Table::from_iter(['a'..='z']);
table.with(Split::column(25)).with(Style::modern());
table.clone().with(Split::column(1).concat().retain());
table.clone().with(Split::column(1).concat()); // .clean() is not necessary as it is the default display property ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │
├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
│ z │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │<- lots of extra cells generated
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
│ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │ z │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ^ cells retained during concatenation
│ a │ b │ c │ d │ e │ f │ g │ h │ i │ j │ k │ l │ m │ n │ o │ p │ q │ r │ s │ t │ u │ v │ w │ x │ y │ z │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘<- cells removed during concatenation
To be able to use a Tabled macros each field must implement std::fmt::Display
otherwise it will not work.
The following example will cause a error.
use tabled::Tabled;
#[derive(Tabled)]
struct SomeType {
field1: SomeOtherType,
}
struct SomeOtherType;The Tabled macros available when derive feature in turned on.
And it is by default.
You can use a #[tabled(rename = "")] attribute to override a column name.
use tabled::Tabled;
#[derive(Tabled)]
struct Person {
#[tabled(rename = "Name")]
first_name: &'static str,
#[tabled(rename = "Surname")]
last_name: &'static str,
}Beside #[tabled(rename = "")] you can change a format of a column name using
#[tabled(rename_all = "UPPERCASE")].
use tabled::Tabled;
#[derive(Tabled)]
#[tabled(rename_all = "CamelCase")]
struct Person {
id: u8,
number: &'static str,
name: &'static str,
#[tabled(rename_all = "snake_case")]
middle_name: &'static str,
}You can mark filds as hidden in which case they fill be ignored and not be present on a sheet.
A similar affect could be achieved by the means of a Disable setting.
use tabled::Tabled;
#[derive(Tabled)]
struct Person {
id: u8,
#[tabled(skip)]
number: &'static str,
name: &'static str,
}You can change the order in which they will be displayed in table.
use tabled::Tabled;
#[derive(Tabled)]
struct Person {
id: u8,
#[tabled(order = 0)]
number: &'static str,
#[tabled(order = 1)]
name: &'static str,
}As was said already, using #[derive(Tabled)] is possible only when all fields implement a Display trait.
However, this may be often not the case for example when a field uses the Option type. There's 2 common ways how to solve this:
- Implement
Tabledtrait manually for a type. - Wrap
Optionto something likeDisplayedOption<T>(Option<T>)and implement a Display trait for it.
Alternatively, you can use the #[tabled(display_with = "func")] attribute for the field to specify a display function.
use tabled::Tabled;
#[derive(Tabled)]
pub struct MyRecord {
pub id: i64,
#[tabled(display_with = "display_option")]
pub valid: Option<bool>
}
fn display_option(o: &Option<bool>) -> String {
match o {
Some(s) => format!("is valid thing = {}", s),
None => format!("is not valid"),
}
}You can send an argument to a function like this (it also possible to use &self),
using #[tabled(display_with("some_function", "arg1", 2, self))]
use tabled::Tabled;
#[derive(Tabled)]
pub struct MyRecord {
pub id: i64,
#[tabled(display_with("Self::display_valid", self, 1))]
pub valid: Option<bool>
}
impl MyRecord {
fn display_valid(&self, arg: usize) -> String {
match self.valid {
Some(s) => format!("is valid thing = {} {}", s, arg),
None => format!("is not valid {}", arg),
}
}
}It's possible to inline internal data if it implements the Tabled trait using #[tabled(inline)].
You can also set a prefix which will be used for all inlined elements by #[tabled(inline("prefix>>"))].
use tabled::Tabled;
#[derive(Tabled)]
struct Person {
id: u8,
name: &'static str,
#[tabled(inline)]
ed: Education,
}
#[derive(Tabled)]
struct Education {
uni: &'static str,
graduated: bool,
}And it works for enums as well.
use tabled::Tabled;
#[derive(Tabled)]
enum Vehicle {
#[tabled(inline("Auto::"))]
Auto {
model: &'static str,
engine: &'static str,
},
#[tabled(inline)]
Bikecycle(
&'static str,
#[tabled(inline)] Bike,
),
}
#[derive(Tabled)]
struct Bike {
brand: &'static str,
price: f32,
}The library doesn't bind you in usage of any color library but to be able to work correctly with color input, and avoid miscalculation of string width
because of embedded ansi sequences, you should add the color feature of tabled to your Cargo.toml:
tabled = { version = "*", features = ["color"] } Then you can use colored strings as values and table dimension will be properly estimated.
use owo_colors::OwoColorize;
// ...
let mut builder = tabled::builder::Builder::default();
builder.push_record(vec!["green".green(), "red".red()])
let mut table = builder.build();Another example:
use tabled::{format::Format, object::Columns, Modify, Style, Table};
let mut table = Table::new(&data);
table
.with(Style::psql())
.with(Modify::new(Columns::single(0)).with(Format::new(|s| s.red().to_string())))
.with(Modify::new(Columns::single(1)).with(Format::new(|s| s.blue().to_string())))
.with(Modify::new(Columns::new(2..)).with(Format::new(|s| s.green().to_string())));
You also can combine objects which implements Tabled by means of tuples, you will get a combined columns of them.
use tabled::{
settings::{Alignment, Style},
Table, Tabled,
};
#[derive(Tabled)]
struct Developer(#[tabled(rename = "name")] &'static str);
#[derive(Tabled)]
enum Domain {
Security,
Embedded,
Frontend,
Unknown,
}
let data = vec![
(Developer("Terri Kshlerin"), Domain::Embedded),
(Developer("Catalina Dicki"), Domain::Security),
(Developer("Jennie Schmeler"), Domain::Frontend),
(Developer("Maxim Zhiburt"), Domain::Unknown),
];
let table = Table::new(data)
.with(Style::psql())
.with(Alignment::center())
.to_string();
assert_eq!(
table,
concat!(
" name | Security | Embedded | Frontend | Unknown \n",
"-----------------+----------+---------+----------+---------\n",
" Terri Kshlerin | | + | | \n",
" Catalina Dicki | + | | | \n",
" Jennie Schmeler | | | + | \n",
" Maxim Zhiburt | | | | + ",
)
);You can apply settings to a subgroup of cells using and and not methods for an object.
use tabled::settings::object::{Object, Segment, Cell, Rows, Columns};
Segment::all().not(Rows::first()); // select all cells except header.
Columns::first().and(Columns::last()); // select cells from first and last columns.
Rows::first().and(Columns::single(0)).not(Cell(0, 0)); // select the header and first column except the (0, 0) cell.Also you can target a column via its name using ByColumnName.
use tabled::{locator::ByColumnName, Alignment, Modify};
table.with(Modify::new(ByColumnName::new("name")).with(Alignment::center()));Utilities for dynamic Table displays.
Combine col! and row! to create flexible table visualizations.
row![table1, table2];+-------------------------------------------+---------------------------------------------+
| .---------------------------------------. | ┌────────────────────┬─────┬──────────────┐ |
| | name | age | is_validated | | │ name │ age │ is_validated │ |
| | Jon Doe | 255 | false | | ├────────────────────┼─────┼──────────────┤ |
| | Mark Nelson | 13 | true | | │ Jack Black │ 51 │ false │ |
| | Terminal Monitor | 0 | false | | ├────────────────────┼─────┼──────────────┤ |
| | Adam Blend | 17 | true | | │ Michelle Goldstein │ 44 │ true │ |
| '---------------------------------------' | └────────────────────┴─────┴──────────────┘ |
+-------------------------------------------+---------------------------------------------+
col![table1, table2];+---------------------------------------------+
| .---------------------------------------. |
| | name | age | is_validated | |
| | Jon Doe | 255 | false | |
| | Mark Nelson | 13 | true | |
| | Terminal Monitor | 0 | false | |
| | Adam Blend | 17 | true | |
| '---------------------------------------' |
+---------------------------------------------+
| ┌────────────────────┬─────┬──────────────┐ |
| │ name │ age │ is_validated │ |
| ├────────────────────┼─────┼──────────────┤ |
| │ Jack Black │ 51 │ false │ |
| ├────────────────────┼─────┼──────────────┤ |
| │ Michelle Goldstein │ 44 │ true │ |
| └────────────────────┴─────┴──────────────┘ |
+---------------------------------------------+
row![table1; 3];+-------------------------------------------+-------------------------------------------+-------------------------------------------+
| .---------------------------------------. | .---------------------------------------. | .---------------------------------------. |
| | name | age | is_validated | | | name | age | is_validated | | | name | age | is_validated | |
| | Jon Doe | 255 | false | | | Jon Doe | 255 | false | | | Jon Doe | 255 | false | |
| | Mark Nelson | 13 | true | | | Mark Nelson | 13 | true | | | Mark Nelson | 13 | true | |
| | Terminal Monitor | 0 | false | | | Terminal Monitor | 0 | false | | | Terminal Monitor | 0 | false | |
| | Adam Blend | 17 | true | | | Adam Blend | 17 | true | | | Adam Blend | 17 | true | |
| '---------------------------------------' | '---------------------------------------' | '---------------------------------------' |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+
col![
row![table_a, table_b],
table_c
]+----------------------------------------------------------------------------------+
| +--------------------------------+---------------------------------------------+ |
| | +-------+-----+--------------+ | ┌────────────────────┬─────┬──────────────┐ | |
| | | name | age | is_validated | | │ name │ age │ is_validated │ | |
| | +-------+-----+--------------+ | ├────────────────────┼─────┼──────────────┤ | |
| | | Sam | 31 | true | | │ Jack Black │ 51 │ false │ | |
| | +-------+-----+--------------+ | ├────────────────────┼─────┼──────────────┤ | |
| | | Sarah | 26 | true | | │ Michelle Goldstein │ 44 │ true │ | |
| | +-------+-----+--------------+ | └────────────────────┴─────┴──────────────┘ | |
| +--------------------------------+---------------------------------------------+ |
+----------------------------------------------------------------------------------+
| .---------------------------------------. |
| | name | age | is_validated | |
| | Jon Doe | 255 | false | |
| | Mark Nelson | 13 | true | |
| | Terminal Monitor | 0 | false | |
| | Adam Blend | 17 | true | |
| '---------------------------------------' |
+----------------------------------------------------------------------------------+
It's possible to construct a table at compile time, via static_table.
You'd need to include a different crate to use it.
Notice that you can even use it in documentation.
/// Multiply 2 integers together.
///
/// ```
#[doc = static_table::static_table!([
["a", "b", "result"],
["1", '2', '3'],
["2", '2', '4']
])]
/// ```
pub fn mul(left: usize, right: usize) -> usize {
left + right
}tabled has a few representations of tables some differs from it's view some from it's implememtation details.
There are situations when you might better use one but not another. But sometimes some can be used interchangable.
Bellow you'll find a short list of existing ones. You can find a descriptive information about each at the documentation.
Main table of the library. It's implemenentation requires that all data be stored on heap.
It's simmilar to main Table, it's only difference is that it does not require a the whole buffer.
It only requires a buffer for 1 row at a time.
It might be usefull when you can't fit all your data in memory.
Simmular to IterTable but it might not require any buffer.
It also has capability for a sniffing logic, where we estimate data dimension on a small selection of data.
It might be usefull in a very constrain environments.
It is the only table which supports no-std.
Unlike Table it does not nessarily requires columns be aligned.
It provides capabilities for a completely uterly diverse table layout.
Example
use tabled::{
settings::{Alignment, Style},
tables::PoolTable,
};
fn main() {
let characters = [
"Naruto Uzumaki",
"Kakashi Hatake",
"Minato Namikaze",
"Jiraiya",
"Orochimaru",
"Itachi Uchiha",
];
let data = characters.chunks(2);
let table = PoolTable::new(data)
.with(Style::dots())
.with(Alignment::center())
.to_string();
println!("{table}");
}The output would look like the following.
...................................
: Naruto Uzumaki : Kakashi Hatake :
:................:................:
: Minato Namikaze : Jiraiya :
:....................:............:
: Orochimaru : Itachi Uchiha :
:...............:.................:
You can use ExpandedDisplay if your data structure has a lot of fields.
Here's an example.
use tabled::{display::ExpandedDisplay, Tabled};
#[derive(Tabled)]
struct Distribution {
name: &'static str,
is_active: bool,
is_cool: bool,
}
let data = [
Distribution {
name: "Manjaro",
is_cool: true,
is_active: true,
},
Distribution {
name: "Debian",
is_cool: true,
is_active: true,
},
Distribution {
name: "Debian",
is_cool: true,
is_active: true,
},
];
let table = ExpandedDisplay::new(&data);
println!("{}", table);You'll see the following.
-[ RECORD 0 ]------
name | Manjaro
is_active | true
is_cool | true
-[ RECORD 1 ]------
name | Debian
is_active | true
is_cool | true
-[ RECORD 2 ]------
name | Debian
is_active | true
is_cool | true
You can convert some formats to a Table.
You can convert arbitrary json to a Table using json_to_table library.
See the example.
You can convert arbitrary ron to a Table using ron_to_table library.
See the example.
You can convert arbitrary csv to a Table using csv_to_table library.
See the example.
You can convert a Table into HTML <table> using table_to_html library.
See the example.
Since version 0.11 we no longer have special treatment for symbols which WILL break your terminal output such as
\t and \r.
So if your content might contain them you shall either handle it yourself,
or call tabled::settings::formatting::Charset::clean and tabled::settings::formatting::Tabsize.
By default tabled doesn't handle ANSI escape codes.
By default such things as hyperlinks, blinking and others things which can be achieved via ANSI codes might not work correctly.
To enable this support, add the color feature to your Cargo.toml
tabled = { version = "*", features = ["color"] }The library support emojies out of the box (include color feature)
but be aware that some of the terminals and editors may not render them as you would expect.
Let's add emojies to an example from a Usage section.
let languages = vec![
Language {
name: "C 💕",
designed_by: "Dennis Ritchie",
invented_year: 1972,
},
Language {
name: "Rust 👍",
designed_by: "Graydon Hoare",
invented_year: 2010,
},
Language {
name: "Go 🧋",
designed_by: "Rob Pike",
invented_year: 2009,
},
];The resultant table will look like the following.
As you can see Github tricks a bit a return table, but GNOME terminal and Alacritty terminal handles it correctly.
+---------+----------------+---------------+
| name | designed_by | invented_year |
+---------+----------------+---------------+
| C 💕 | Dennis Ritchie | 1972 |
+---------+----------------+---------------+
| Rust 👍 | Graydon Hoare | 2010 |
+---------+----------------+---------------+
| Go 🧋 | Rob Pike | 2009 |
+---------+----------------+---------------+It's a friquent case where it's nessary to align a table to a terminal width or height.
You can achieve that by using Width and Height.
You can peak a strategy by which a column/row truncation/widening will be done by using Priority.
This example uses terminal_size crate to determine ones size, but it's possible to use anything.
use tabled::{
builder::Builder,
settings::{peaker::PriorityMax, Height, Settings, Width},
Table,
};
use terminal_size::{terminal_size, Height as TerminalHeight, Width as TerminalWidth};
fn build_table() -> Table {
let data = [
["0.2.1", "2021-06-23", "true", "#[header(inline)] attribute"],
["0.2.0", "2021-06-19", "false", "API changes"],
["0.1.4", "2021-06-07", "false", "display_with attribute"],
];
Builder::from_iter(data).build()
}
fn get_terminal_size() -> (usize, usize) {
let (TerminalWidth(width), TerminalHeight(height)) =
terminal_size().expect("failed to obtain a terminal size");
(width as usize, height as usize)
}
fn main() {
let (width, height) = get_terminal_size();
let term_size_settings = Settings::default()
.with(Width::wrap(width).priority::<PriorityMax>())
.with(Width::increase(width))
.with(Height::limit(height))
.with(Height::increase(height));
let mut table = build_table();
table.with(term_size_settings);
println!("{table}");
}When you need to release a breaking change—any breaking change—you do it in a major version. Period. No excuses.
We still do it.
We often do break change on minor version bump.
So you probably shall not depend on minor version (like 0.7).
It's likely better to depend on constant version e.g. =0.8.0
Breaking MSRV considered to be a breaking change; but see semver-note
Nowadays there's a few libraries for pretty tables.
Some may wonder why tabled is better or worse than others libraries?
I hope tabled does it's job good, but at the end of the day you probably need to decide it yourself.
If you have any ideas for an enhancement or have a question about tabled please file an issue.
Bellow you will find a list of crates which do similar things or do something which tabled doesn't.
You can find performance comparison benchmarks here.
The description is taken from the author's quotes.
-
cli-tabletends to keep the compile time and crate size low and support all the platforms. It has an optionalcsvsupport. -
comfy-tablefocuses on providing a minimalistic, but rock-solid library for building text-based tables with focus on safety and dynamic-length content arrangement. -
term-table-rsmain focus is on a good set of tools for rendering CLI tables, while allowing users to bring their own tools for things like colors. It has an ability to have different number of columns in each row of the table.
Please if you feel about some crate being worth menthioned open an issue.