Crate colonnade

This crate provides a library for displaying tabular data in, for instance, a command line app.

Usage

Colonnade is on crates.io and can be used by adding colonnade to your dependencies in your project’s Cargo.toml.

[dependencies]
colonnade = "1"

Example

extern crate colonnade;
use colonnade::{Alignment, Colonnade};

#[allow(unused_must_use)]
fn main() {
    // text to put in tabular form
    let text = vec![
        vec![
            "Colonnade lets you format text in columns.",
            "As you can see, it supports text alignment, viewport width, and column widths.",
            "If you want to colorize your table, you'll need to use the macerate method.",
        ],
        vec!["", "Two or more rows of columns makes a table.", ""],
    ];

    // 3 columns of text in an 80-character viewport
    let mut colonnade = Colonnade::new(3, 80).unwrap();

    // configure the table a bit
    colonnade.left_margin(4);
    colonnade.columns[0].left_margin(8);      // the first column should have a left margin 8 spaces wide
    colonnade.fixed_width(15);                // first we set all the columns to 15 characters wide
    colonnade.columns[1].clear_limits();      // but then remove this restriction on the central column
    colonnade.columns[0].alignment(Alignment::Right);
    colonnade.columns[1].alignment(Alignment::Center);
    colonnade.spaces_between_rows(1);         // add a blank link between rows

    // now print out the table
    for line in colonnade.tabulate(&text).unwrap() {
        println!("{}", line);
    }
}

which produces

         Colonnade lets     As you can see, it supports text     If you want to
        you format text      alignment, viewport width, and      colorize your
            in columns.              column widths.              table, you'll
                                                                 need to use the
                                                                 macerate
                                                                 method.

                           Two or more rows of columns makes
                                        a table.

If Colonnade doesn’t have enough space in a column to fit the text, it will attempt to wrap it, splitting on whitespace. If this is not possible because a word in the text is so long it does not fit in the column, it will fit as much as it can, splitting mid-word and marking the split with a hyphen (unless the column is only one character wide).

To control the layout you can specify minimum and maximum column widths and column priorities. If the columns differ in priority, lower priority, higher priority number, columns will get wrapped first.

Optional Features

Colonnade by default takes full control over whitespace, stripping away any that exists in the data it receives and adding it back in as needed to arrange the columns. If you want to regain some control, to indent the beginning of paragraphs, say, you can use the nbsp feature, which causes Colonnade to treat the non-breaking space character \u{00A0} like a non-space character.

To require nbsp, specify your Colonnade dependency like so in your Cargo.toml:

two_timer = { version = "^1.3.0", features = ["nbsp"] }

or

[dependencies.colonnade]
version  = "^1.3.0"
features = ["nbsp"]

This feature has a dependency on the regex and lazy_static crates.

Structs

Colonnade

A struct holding formatting information. This is the object which tabulates data.

Column

A struct holding formatting information for a particular column.

Enums

Alignment

Alignments left-to-right one can apply to columns of text.

ColonnadeError

All the things that can go wrong when laying out tabular data.

VerticalAlignment

Vertical alignments of text within a column.