Crate tabled

Help

Expand description

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

The library is based on a Tabled trait which is used to actually build tables. It also provides an variate of dynamic settings for customization of a Table.

Table can be build from vast majority of Rust’s standard types.

§Usage

If you want to build a table for your custom type. A starting point is to a anotate your type with #[derive(Tabled)].

Then one of ways to create a table is to call Table::new to create a table.

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: "Rust",
        designed_by: "Graydon Hoare",
        invented_year: 2010
    },
    Language{
        name: "Go",
        designed_by: "Rob Pike",
        invented_year: 2009
    },
];

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 create a table by using TableIteratorExt.

use tabled::TableIteratorExt;
let table = languages.table();

Not all types can derive Tabled trait though. The example below can’t be compiled.

    #[derive(Tabled)]
    struct SomeType {
        field1: SomeOtherType,
    }

    struct SomeOtherType;

We must know what we’re up to print as a field. Because of this each field must implement std::fmt::Display.

§Default implementations

As I’ve already mentioned most of the default types implements the trait out of the box.

This allows you to run the following code.

use tabled::{Tabled, Table};
let table = Table::new(&[1, 2, 3]);

§Combination of types via tuples

Personally I consider this a feature which drives the library to shine. You can combine any types that implements Tabled trait into one table.

You can also see in this example a #[header("name")] usage which configures a header of a table which will be printed. You could change it dynamically as well.

use tabled::{Tabled, Table, Style, Alignment, ModifyObject, object::{Rows, Columns, Object}};

#[derive(Tabled)]
enum Domain {
    Security,
    Embeded,
    Frontend,
    Unknown,
}

#[derive(Tabled)]
struct Developer(#[tabled(rename = "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())
    .with(Rows::new(1..).not(Columns::first()).modify().with(Alignment::center()))
    .to_string();

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

§Dynamic table

When you data sheme is not known at compile time. You mostlikely will not able to use Tabled trait. But you could build table from scratch.

use tabled::{builder::Builder, ModifyObject, object::Rows, Alignment, Style};

let mut builder = Builder::default();

for i in 0..3 {
    let mut row = vec![];
    row.push(i.to_string());
    for j in 0..10 {
        row.push((i*j).to_string());
    }

    builder.add_record(row);
}

builder.set_columns(std::iter::once(String::from("i")).chain((0..10).map(|i| i.to_string())));

let table = builder.build()
    .with(Style::rounded())
    .with(Rows::new(1..).modify().with(Alignment::left()))
    .to_string();

assert_eq!(
    table,
    concat!(
        "╭───┬───┬───┬───┬───┬───┬────┬────┬────┬────┬────╮\n",
        "│ i │ 0 │ 1 │ 2 │ 3 │ 4 │ 5  │ 6  │ 7  │ 8  │ 9  │\n",
        "├───┼───┼───┼───┼───┼───┼────┼────┼────┼────┼────┤\n",
        "│ 0 │ 0 │ 0 │ 0 │ 0 │ 0 │ 0  │ 0  │ 0  │ 0  │ 0  │\n",
        "│ 1 │ 0 │ 1 │ 2 │ 3 │ 4 │ 5  │ 6  │ 7  │ 8  │ 9  │\n",
        "│ 2 │ 0 │ 2 │ 4 │ 6 │ 8 │ 10 │ 12 │ 14 │ 16 │ 18 │\n",
        "╰───┴───┴───┴───┴───┴───┴────┴────┴────┴────┴────╯",
    )
);

§Build table using `row` and `col`.

use tabled::{row, col};

let table = row![
    col!["Hello", "World", "!"],
    col!["Hello"; 3],
    col!["World"; 3],
].to_string();

assert_eq!(
    table,
    concat!(
        "+-----------+-----------+-----------+\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "| | Hello | | | Hello | | | World | |\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "| | World | | | Hello | | | World | |\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "| | !     | | | Hello | | | World | |\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "+-----------+-----------+-----------+",
    )
);

§Settings

You can find more examples of settings and attributes in README.md

Re-exports§

pub use papergrid;

Modules§

alignment: This module contains an Alignment setting for cells on the Table.
builder: Builder module provides a Builder type which helps building a Table dynamically.
display: A module which contains a different Views for a Table.
format: This module contains a list of primitives to help to modify a Table.
formatting: This module contains settings for render strategy of papergrid.
height: The module contains Height structure which is responsible for a table and cell height.
locator: The module contains a Locator trait and implementations for it.
macros: This module contains macro functions for dynamic Table construction.
measurment: The module contains Measurment trait and its implementations to be used in Height and Width.
merge: The module contains a set of methods to merge cells together via Spans.
object: This module contains a list of primitives that implement a Object trait. They help to locate a necessary segment on a Table.
peaker: The module contains Peaker trait and its implementations to be used in Height and Width.
shadow: This module contains a Shadow option for a Table.
style: Module contains different things to tweak the style of the Table.
width: This module contains object which can be used to limit a cell to a given width:

Macros§

col: Creates a Table with Display arguments nested within.
row: Creates a Table with Display arguments nested within.

Structs§

Border: Border represents a border of a Cell.
BorderText: BorderText writes a custom text on a border.
CellSettingsList: This is a container of CellOptions.
Concat: Concat concatenate tables along a particular axis [Horizontal | Vertical]. It doesn’t do any key or column comparisons like SQL’s join does.
Disable: Disable removes particular rows/columns from a Table.
Extract: Returns a new Table that reflects a segment of the referenced Table
Footer: Footer renders a Panel at the bottom. See Panel.
Header: Header inserts a Panel at the top. See Panel.
Height: Height is a abstract factory for height settings.
Highlight: Highlight modifies a table style by changing a border of a target Table segment.
Margin: Margin is responsible for a left/right/top/bottom outer indent of a grid.
Modify: Modify structure provide an abstraction, to be able to apply a set of CellOptions to the same object.
ModifyList: This is a container of CellOptions which are applied to a set Object.
Padding: Padding is responsible for a left/right/top/bottom inner indent of a particular cell.
Panel: Panel allows to add a Row which has 1 continues Cell to a Table.
Span: Span represent a horizontal/column span setting for any cell on a Table.
Style: Style is represents a theme of a Table.
Table: The structure provides an interface for building a table for types that implements Tabled.
Width: Width allows you to set a min and max width of an object on a Table using different strategies.

Enums§

Alignment: Alignment represent a horizontal and vertical alignment setting for any cell on a Table.
Rotate: Rotate can be used to rotate a table by 90 degrees.

Traits§

CellOption: A trait for configuring a single cell. Where cell represented by ‘row’ and ‘column’ indexes.
ModifyObject: An utility trait for a different interface of Modify creation.
TableIteratorExt: A trait for IntoIterator whose Item type is bound to Tabled. Any type implements IntoIterator can call this function directly
TableOption: A trait which is responsilbe for configuration of a Table.
Tabled: Tabled a trait responsible for providing a header fields and a row fields.

Derive Macros§

Tabled: A derive to implement a Tabled trait.

Crate tabledCopy item path