Getting Started

To use cols, add it to your Cargo.toml:

[dependencies]
cols = "0.1"

Core concepts

A cols table has three layers:

• A Table holds configuration (output mode, terminal width, symbols) and owns all columns and lines.
• Columns define the vertical structure — each column has a name, a width hint, and formatting flags (right-align, truncate, wrap, etc.). Columns are built with a fluent builder API.
• Lines are rows. Each line holds one cell per column. Lines can optionally have a parent, forming a tree hierarchy.

You build a table by adding columns, then adding lines and setting their cell data. When you’re ready, call print_table to render the output.

Your first table

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

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

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

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

    print_table(&t, &mut std::io::stdout().lock()).unwrap();
}

Output:

NAME         SIZE
sda          100G
sdb           50G

The NAME column gets a fixed width of 10 characters. The SIZE column is right-aligned and 6 characters wide. The print engine pads and aligns the data automatically.

Printing

print_table writes to any std::io::Write. For stdout:

use cols::print_table;

print_table(&table, &mut std::io::stdout().lock()).unwrap();

To capture the output as a String instead (useful for tests or further processing):

use cols::print_table_to_string;

let output = print_table_to_string(&table).unwrap();

What’s next

The following chapters walk through each feature in detail:

• Tables and Columns explains width hints, terminal settings, and modifying columns after creation.
• Adding Data covers lines, cells, handles, and iteration.
• Output Modes walks through Normal, Raw, Export, JSON, and ShellVar output.
• Tree Rendering shows how to build parent/child hierarchies.
• Column Formatting covers right-align, truncation, wrapping, and hidden columns.
• Sorting demonstrates alphabetic, numeric, and custom comparators.
• Groups explains M:N relationships with bracket connectors.
• Filtering introduces the expression language for filtering rows.