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, 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);
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 struct
s 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 withorder = 0
will be displayed on the left followed by column withorder = 1
and so on.display_fn
: Used to print types which do not implementDisplay
trait. Usage#[table(display_fn = "<func_name>")]
. Signature of provided function should befn <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 befn <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 usingcsv
. 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
title
or derive
Trait for getting title row of a struct
title
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
derive
Derive macro to implementing cli_table
traits