Crate cli_table

Rust crate for printing tables on command line.

Usage

Add cli-table in your Cargo.toms’s dependencies section

[dependencies]
cli-table = "0.4"

Simple usage

use cli_table::{format::Justify, print_stdout, Cell, Style, Table};

let table = vec![
    vec!["Tom".cell(), 10.cell().justify(Justify::Right)],
    vec!["Jerry".cell(), 15.cell().justify(Justify::Right)],
    vec!["Scooby Doo".cell(), 20.cell().justify(Justify::Right)],
]
.table()
.title(vec![
    "Name".cell().bold(true),
    "Age (in years)".cell().bold(true),
])
.bold(true);

assert!(print_stdout(table).is_ok());

Below is the output of the table we created just now:

+------------+----------------+
| Name       | Age (in years) |  <-- This row and all the borders/separators
+------------+----------------+      will appear in bold
| Tom        |             10 |
+------------+----------------+
| Jerry      |             15 |
+------------+----------------+
| Scooby Doo |             25 |
+------------+----------------+

Derive macro

#[derive(Table)] can also be used to print a Vec or slice of structs as table.

use cli_table::{format::Justify, print_stdout, Table, WithTitle};

#[derive(Table)]
struct User {
    #[table(title = "ID", justify = "Justify::Right")]
    id: u64,
    #[table(title = "First Name")]
    first_name: &'static str,
    #[table(title = "Last Name")]
    last_name: &'static str,
}

let users = vec![
    User {
        id: 1,
        first_name: "Scooby",
        last_name: "Doo",
    },
    User {
        id: 2,
        first_name: "John",
        last_name: "Cena",
    },
];

assert!(print_stdout(users.with_title()).is_ok());

Below is the output of the table we created using derive macro:

+----+------------+-----------+
| ID | First Name | Last Name |  <-- This row will appear in bold
+----+------------+-----------+
|  1 | Scooby     | Doo       |
+----+------------+-----------+
|  2 | John       | Cena      |
+----+------------+-----------+

Field attributes

• title | name: Used to specify title of a column. Usage: #[table(title = "Title")]
• justify: Used to horizontally justify the contents of a column. Usage: #[table(justify = "Justify::Right")]
• align: Used to vertically align the contents of a column. Usage: #[table(align = "Align::Top")]
• color: Used to specify color of contents of a column. Usage: #[table(color = "Color::Red")]
• bold: Used to specify boldness of contents of a column. Usage: #[table(bold)]
• order: Used to order columns in a table while printing. Usage: #[table(order = <usize>)]. Here, columns will be sorted based on their order. For e.g., column with order = 0 will be displayed on the left followed by column with order = 1 and so on.
• display_fn: Used to print types which do not implement Display trait. Usage #[table(display_fn = "<func_name>")]. Signature of provided function should be fn <func_name>(value: &<type>) -> impl Display.
• customize_fn: Used to customize style of a cell. Usage #[table(customize_fn = "<func_name>")]. Signature of provided function should be fn <func_name>(cell: CellStruct, value: &<type>) -> CellStruct. This attribute can be used when you want to change the formatting/style of a cell based on its contents. Note that this will overwrite all the style settings done by other attributes.
• skip: Used to skip a field from table. Usage: #[table(skip)]

For more information on configurations available on derive macro, go to cli-table/examples/struct.rs.

CSV

This crate also integrates with csv crate. On enabling "csv" feature, you can use TryFrom<&mut Reader> for TableStruct trait implementation to convert csv::Reader to TableStruct.

For more information on handling CSV values, go to cli-table/examples/csv.rs.

Styling

Style of a table/cell can be modified by calling functions of Style trait. It is implementated by both TableStruct and CellStruct.

For individually formatting each cell of a table, justify, align and padding functions can be used from CellStruct.

In addition to this, borders and separators of a table can be customized by calling border and separator functions in TableStruct. For example, to create a borderless table:

use cli_table::{Cell, Table, TableStruct, format::{Justify, Border}, print_stdout};

fn get_table() -> TableStruct {
    vec![
        vec!["Tom".cell(), 10.cell().justify(Justify::Right)],
        vec!["Jerry".cell(), 15.cell().justify(Justify::Right)],
        vec!["Scooby Doo".cell(), 20.cell().justify(Justify::Right)],
    ]
    .table()
}

let table = get_table().border(Border::builder().build()); // Attaches an empty border to the table
assert!(print_stdout(table).is_ok());

Features

• derive: Enables derive macro for creating tables using structs. Enabled by default.
• csv: Enables support for printing tables using csv. Enabled by default.

Modules

format

Utilities for formatting of a table

Structs

CellStruct	Concrete cell of a table
RowStruct	Concrete row of a table
TableStruct	Struct for building a table on command line

Enums

Color	The set of available colors for the terminal foreground/background.
ColorChoice	ColorChoice represents the color preferences of an end user.

Traits

Cell	Trait to convert raw types into cells
Row	Trait to convert raw types into rows
Style	Trait for modifying style of table and cells
Table	Trait to convert raw type into table
Title	title or derive Trait for getting title row of a struct
WithTitle	title or derive Trait for creating a table with titles at the top

Functions

print_stderr	Prints a table to stderr
print_stdout	Prints a table to stdout

Derive Macros

Table

derive Derive macro to implementing cli_table traits