tabled
An easy to use library for pretty printing tables of Rust struct
s and enum
s.
Agenda
Usage
To print a list of structs or enums as a table your types should implement the the Tabled
trait or derive with a #[derive(Tabled)]
macro.
use ;
let languages = vec!;
let table = new.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\
+------+----------------+---------------+\n";
assert_eq!;
Derive information
To be able to use a Tabled
macro each field should implement std::fmt::Display
otherwise it will not work.
The following example will cause a error.
use Tabled;
;
Most of the default types implements the trait out of the box.
use Table;
let some_numbers = ;
let table = new;
Style
Styles
A list of ready to use styles.
Styles can be chosen by passing a Style
argument option.
let table = new.with;
Default
+------+----------------+---------------+
| 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
GithubMarkdown
| name | designed_by | invented_year |
|------+----------------+---------------|
| C | Dennis Ritchie | 1972 |
| Rust | Graydon Hoare | 2010 |
| Go | Rob Pike | 2009 |
Pseudo
┌──────┬────────────────┬───────────────┐
│ name │ designed_by │ invented_year │
├──────┼────────────────┼───────────────┤
│ C │ Dennis Ritchie │ 1972 │
├──────┼────────────────┼───────────────┤
│ Rust │ Graydon Hoare │ 2010 │
├──────┼────────────────┼───────────────┤
│ Go │ Rob Pike │ 2009 │
└──────┴────────────────┴───────────────┘
PseudoClean
┌──────┬────────────────┬───────────────┐
│ name │ designed_by │ invented_year │
├──────┼────────────────┼───────────────┤
│ C │ Dennis Ritchie │ 1972 │
│ Rust │ Graydon Hoare │ 2010 │
│ Go │ Rob Pike │ 2009 │
└──────┴────────────────┴───────────────┘
Noborder
name designed_by invented_year
C Dennis Ritchie 1972
Rust Graydon Hoare 2010
Go Rob Pike 2009
Custom Style
You can modify existing styles to fits your needs.
let style = noborder
.frame_bottom
.split
.inner;
let table = new.with;
Alignment
You can set a horizontal and vertical alignment for a Header
, Column
, Row
or Full
set of cells.
.with;
new
Format
The Format
function provides an interface for a modification of cells.
.with,
.with
.with;
new
It's also possible to use functions with signature Fn(&str) -> String
as a formatter.
.with,
.with
.with;
new
IMPORTANT: you may need to specify type in your lambda otherwise compiler may be disagreed to work :)
Indent
The Indent
type provides an interface for a left, right, top and bottom indent of cells.
.with;
new
Max width
Using MaxWidth
type its possible to set a max width of an object.
While tinkering content we don't forget about its color.
.with;
new
Disable
You can remove certain rows or columns from the table.
.with
.with;
new
Header and Footer
You can add a Header
and Footer
to display some information.
By the way you can even add such line by using Panel
.with
.with
new
A look will differ from a style you choose. But it's how it may look like.
┌────────────────────────────────────────────────────────────┐
│ Tabled Name │
├────────────────────────────────────────────────────────────┤
...
├───────┼──────────────┼─────────┼───────────────────────────┤
│ 3 elements │
└────────────────────────────────────────────────────────────┘
Color
The library doesn't bind you in usage of any color library but to be able to work corectly with color input you should provide a --features color
.
.with
.with
.with
.with;
new
Features
Column name override
You can use a #[header("")]
attribute to override a column name.
Hide a column
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 achived by the means of a Disable
setting.
Custom field formatting
#[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
Tabled
trait manually for a type. - Wrap
Option
to something likeDisplayedOption<T>(Option<T>)
and implement a Display trait for it.
Or to use an attribute #[field(display_with = "func")]
for the field. To use it you must provide a function name in a display_with
parameter.
Inline
It's possible to inline internal data if it implements Tabled
trait.
Use #[header(inline)]
or #[header(inline("prefix>>"))]
.
The string argument is a prefix which will be used for all inlined elements.
And it works for enums as well.
Tuple combination
You also can combine objets which implements Tabled
by means of tuples, you will get a combined columns of them.
use ;
] &'static str);
let data = vec!;
let table = new.with.to_string;
assert_eq!;
Object
You can peak your target for settings using and
and not
methods for an object.
Full.not // peak all cells except header
Head.and.not // peak a header and first column except a (0, 0) cell
Notes
Emoji
The library support emojies out of the box 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!;
The resultant table will look like the following.
As you can see Github triks 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 |
+---------+----------------+---------------+