Build Status Coverage Status Crate docs.rs license dependency status

tabled

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

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.

```rust use tabled::{Tabled, Table};

[derive(Tabled)]

struct Language { name: &'static str, designedby: &'static str, inventedyear: usize, }

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

let table = Table::new(languages).to_string();

let expected = "+------+----------------+---------------+\n\ | name | designedby | inventedyear |\n\ +------+----------------+---------------+\n\ | C | Dennis Ritchie | 1972 |\n\ +------+----------------+---------------+\n\ | Rust | Graydon Hoare | 2010 |\n\ +------+----------------+---------------+\n\ | Go | Rob Pike | 2009 |\n\ +------+----------------+---------------+\n";

assert_eq!(table, expected); ```

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.

```rust,compile_fail use tabled::Tabled;

[derive(Tabled)]

struct SomeType { field1: SomeOtherType, }

struct SomeOtherType; ```

Most of the default types implements the trait out of the box.

rust use tabled::Table; let some_numbers = [1, 2, 3]; let table = Table::new(&some_numbers);

Style

Styles

A list of ready to use styles. Styles can be chosen by passing a Style argument option.

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

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.

```rust let style = tabled::Style::noborder() .frame_bottom(Some(Line::short('*', ' ''))) .split(Some(Line::short(' ', ' '))) .inner(' ');

let table = Table::new(&data).with(style); ```

Alignment

You can set a horizontal and vertical alignment for a Header, Column, Row or Full set of cells.

rust Table::new(&data) .with(Modify::new(Full) .with(Alignment::left()) .with(Alignment::top()) );

Format

The Format function provides an interface for a modification of cells.

rust Table::new(&data) .with(Style::psql()), .with(Modify::new(Column(..)).with(Format(|s| format!("<< {} >>", s)))) .with(Modify::new(Row(..1)).with(Format(|s| format!("Head {}", s))));

It's also possible to use functions with signature Fn(&str) -> String as a formatter.

rust Table::new(&data) .with(Style::psql()), .with(Modify::new(Column(..)).with(|s: &str| format!("<< {} >>", s))) .with(Modify::new(Row(..1)).with(str::to_lowercase));

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.

rust Table::new(&data).with(Modify::new(Row(1..)).with(Indent::new(1, 1, 0, 2)));

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.

rust Table::new(&data).with(Modify::new(Row(1..)).with(MaxWidth(10, "...")));

Disable

You can remove certain rows or columns from the table.

rust Table::new(&data) .with(Disable::Row(..1)) .with(Disable::Column(3..4));

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

rust Table::new(&data) .with(Header("Tabled Name")) .with(Footer(format!("{} elements", data.len())))

A look will differ from a style you choose. But it's how it may look like.

text ┌────────────────────────────────────────────────────────────┐ │ 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.

rust Table::new(&data) .with(Style::psql()) .with(Modify::new(Column(..1)).with(Format(|s| s.red().to_string()))) .with(Modify::new(Column(1..2)).with(Format(|s| s.blue().to_string()))) .with(Modify::new(Column(2..)).with(Format(|s| s.green().to_string())));

carbon-2

Features

Column name override

You can use a #[header("")] attribute to override a column name.

```rust

[derive(Tabled)]

struct Person { #[header("Name")] firstname: &'static str, #[header("Surname")] lastname: &'static str, } ```

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.

rust struct Person { #[header(hidden = true)] id: u8, #[header("field 2", hidden)] number: &'static str, name: &'static str, }

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:

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.

```rust fn display_option(o: &Option) -> String { match o { Some(s) => format!("is valid thing = {}", s), None => format!("is not valid"), } }

[derive(Tabled)]

pub struct MyRecord { pub id: i64, #[field(displaywith="displayoption")] pub valid: Option } ```

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.

```rust #[derive(Tabled)] struct Person { id: u8, name: &'static str, #[header(inline)] ed: Education, }

[derive(Tabled)]

struct Education { uni: &'static str, graduated: bool, } ```

And it works for enums as well.

```rust

[derive(Tabled)]

enum Vehicle { #[header(inline("Auto::"))] Auto { model: &'static str, engine: &'static str, }, #[header(inline)] Bikecycle(#[header("name")] &'static str, #[header(inline)] Bike), }

[derive(Tabled)]

struct Bike { brand: &'static str, price: f32, } ```

Tuple combination

You also can combine objets which implements Tabled by means of tuples, you will get a combined columns of them.

```rust use tabled::{Tabled, Table, Style};

[derive(Tabled)]

enum Domain { Security, Embeded, Frontend, Unknown, }

[derive(Tabled)]

struct Developer(#[header("name")] &'static str);

let data = vec![ (Developer("Terri Kshlerin"), Domain::Embeded), (Developer("Catalina Dicki"), Domain::Security), (Developer("Jennie Schmeler"), Domain::Frontend), (Developer("Maxim Zhiburt"), Domain::Unknown), ];

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

assert_eq!( table, concat!( " name | Security | Embeded | Frontend | Unknown \n", "-----------------+----------+---------+----------+---------\n", " Terri Kshlerin | | + | | \n", " Catalina Dicki | + | | | \n", " Jennie Schmeler | | | + | \n", " Maxim Zhiburt | | | | + \n" ) ); ```

Object

You can peak your target for settings using and and not methods for an object.

rust Full.not(Row(..1)) // peak all cells except header Head.and(Column(..1)).not(Cell(0, 0)) // 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.

rust 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 triks a bit a return table, but GNOME terminal and Alacritty terminal handles it correctly.

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