Expand description

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 |
+------------+----------------+

Display trait implementation

To get a Display trait implementation of TableStruct, use display() function on the struct to get an instance of TableDisplay which implements Display trait.

use cli_table::{format::Justify, 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);

let table_display = table.display().unwrap();

println!("{}", table_display);

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

Utilities for formatting of a table

Structs

Concrete cell of a table
Concrete row of a table
A table which implements the Display trait
Struct for building a table on command line

Enums

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

Traits

Trait to convert raw types into cells
Trait to convert raw types into rows
Trait for modifying style of table and cells
Trait to convert raw type into table
Titletitle or derive
Trait for getting title row of a struct
WithTitletitle or derive
Trait for creating a table with titles at the top

Functions

Prints a table to stderr
Prints a table to stdout

Derive Macros

Tablederive
Derive macro to implementing cli_table traits