Smart adaptive formatting of tabular data.

This crate provides an idiomatic Rust library for building and printing tables with automatic column width calculation, tree rendering, multiple output formats, and a filter expression language.

Quick start

use cols::{Table, Column, print_table_to_string};

let mut table = Table::new();
table.add_column(Column::new("NAME").width_fixed(10));
table.add_column(Column::new("SIZE").width_fixed(6).right(true));

let l1 = table.new_line(None);
table.line_mut(l1).set_data(0, "sda").set_data(1, "100G");

let l2 = table.new_line(None);
table.line_mut(l2).set_data(0, "sdb").set_data(1, "50G");

let output = print_table_to_string(&table).unwrap();
assert!(output.contains("sda"));
assert!(output.contains("100G"));

Output modes

Set via [Table::set_output_mode]:

use cols::{OutputMode, Table, print_table_to_string};

let mut table = Table::new();
table.set_name("devices");
table.new_column("NAME");
table.new_column("SIZE");

let row = table.new_line(None);
table.line_mut(row).set_data(0, "sda").set_data(1, "100G");

// JSON output
table.set_output_mode(OutputMode::Json);
let json = print_table_to_string(&table).unwrap();
assert!(json.contains("\"NAME\": \"sda\""));

// Export (shell-friendly KEY="value" pairs)
table.set_output_mode(OutputMode::Export);
let export = print_table_to_string(&table).unwrap();
assert!(export.contains("NAME=\"sda\""));

Column width hints

Width hints guide the print engine's layout algorithm. Set them via the builder methods on [Column]:

Column flags

Per-column rendering behavior is controlled via builder methods on [Column]:

Tree rendering

Mark a column as a tree column with [Column::tree] and pass a parent [LineId] when creating child lines. The print engine draws Unicode (or ASCII) tree connectors automatically.

use cols::{Table, Column, print_table_to_string};

let mut table = Table::new();
table.enable_no_headings(true);
table.enable_ascii(true);
table.add_column(Column::new("NAME").tree(true));

let root = table.new_line(None);
table.line_mut(root).set_data(0, "parent");

let child1 = table.new_line(Some(root));
table.line_mut(child1).set_data(0, "child-a");

let child2 = table.new_line(Some(root));
table.line_mut(child2).set_data(0, "child-b");

let output = print_table_to_string(&table).unwrap();
assert!(output.contains("|-child-a"));
assert!(output.contains("`-child-b"));

Sorting

Sort child lines under a parent using [Table::sort]. A custom comparator can be set per-column with [Column::cmp_func]. Sorting reorders children within each parent node; for flat tables, add rows as children of a single root line.

use cols::{Table, Column, print_table_to_string};

let mut table = Table::new();
table.enable_ascii(true);
table.enable_no_headings(true);
table.add_column(Column::new("NAME").tree(true));

let root = table.new_line(None);
table.line_mut(root).set_data(0, "root");

for name in ["zebra", "apple", "mango"] {
    let row = table.new_line(Some(root));
    table.line_mut(row).set_data(0, name);
}

table.sort(0); // sort children of root by column 0

let output = print_table_to_string(&table).unwrap();
let lines: Vec<&str> = output.lines().collect();
// lines[0] = root, children appear sorted after it
assert!(lines[1].contains("apple"));
assert!(lines[2].contains("mango"));
assert!(lines[3].contains("zebra"));

Groups

Groups express M:N relationships between lines — multiple lines can be "members" of a group, and other lines can be "children" of that group. The print engine draws bracket connectors on the left margin.

use cols::{Table, TermForce, print_table_to_string};

let mut table = Table::new();
table.enable_no_headings(true);
table.enable_ascii(true);
table.set_termwidth(40);
table.set_termforce(TermForce::Always);
table.new_column("NAME");

let group = table.new_group();

let m1 = table.new_line(None);
table.line_mut(m1).set_data(0, "server");
let m2 = table.new_line(None);
table.line_mut(m2).set_data(0, "worker");

let child = table.new_line(None);
table.line_mut(child).set_data(0, "logger");

table.group_add_member(group, m1);
table.group_add_member(group, m2);
table.group_add_child(group, child);

let output = print_table_to_string(&table).unwrap();
assert!(output.contains(",-server"));
assert!(output.contains("|-worker"));
assert!(output.contains("`-logger"));

Cloning

Both [Table] and [Column] implement [Clone]. Cloning a table produces an independent copy including all lines and column definitions. If a column has a custom comparator set via [Column::cmp_func], the clone shares the same comparator function (via Arc).

use cols::Table;

let mut table = Table::new();
table.new_column("X");
let row = table.new_line(None);
table.line_mut(row).set_data(0, "hello");

let clone = table.clone();
assert_eq!(clone.nlines(), table.nlines());

Filtering

Parse filter expressions with [Filter::parse] and evaluate them against line data. Supports comparisons, boolean logic, regex matching, and integer suffixes (K, M, G, ...).

use cols::Filter;

let f = Filter::parse(r#"SIZE > 1G && TYPE == "disk""#).unwrap();
let matches = f.evaluate(|col| match col {
    "SIZE" => Some("4294967296".into()), // 4G
    "TYPE" => Some("disk".into()),
    _ => None,
}).unwrap();
assert!(matches);