Struct colonnade::Colonnade

pub struct Colonnade {
    pub columns: Vec<Column>,
    /* private fields */
}

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

Fields

columns: Vec<Column>

Implementations

impl Colonnade

pub fn new(columns: usize, width: usize) -> Result<Colonnade, ColonnadeError>

Construct a Colonnade with default values: left alignment, no column size constraints, no blank lines between rows, 1 space margin between columns.

Arguments

• columns - The number of columns of data to expect
• width - Viewport size in characters

Errors

• ColonnadeError::InsufficientSpace - the viewport isn’t wide enough for the columns and their margins

Example

let colonnade = Colonnade::new(4, 100);

pub fn width(&self) -> Option<usize>

Returns the width of the colonnade in columns if the colonnade has already laid out data and knows how much space this data will require.

pub fn tabulate<T, U, V, W, X>( &mut self, table: T ) -> Result<Vec<String>, ColonnadeError>

where T: IntoIterator<Item = U, IntoIter = V>, U: IntoIterator<Item = W, IntoIter = X>, V: Iterator<Item = U>, W: ToString, X: Iterator<Item = W>,

Converts the raw data in table into a vector of strings representing the data in tabular form. Blank lines will be zero-width rather than full-width lines of whitespace.

If you need finer control over the text, for instance, if you want to add color codes, see macerate.

Arguments

• table - The data to display.

Errors

Any errors of lay_out. If the data has already been laid out, this method will throw no errors.

Example

let mut colonnade = Colonnade::new(4, 100)?;
let data = vec![vec!["some", "words", "for", "example"]];
let lines = colonnade.tabulate(&data)?;

pub fn macerate<T, U, V, W, X>( &mut self, table: T ) -> Result<Vec<Vec<Vec<(String, String)>>>, ColonnadeError>

where T: IntoIterator<Item = U, IntoIter = V>, U: IntoIterator<Item = W, IntoIter = X>, V: Iterator<Item = U>, W: ToString, X: Iterator<Item = W>,

Chew up the text into bits suitable for piecemeal layout.

More specifically, macerate digests the raw data in table into a vector of vectors of (String, String) tuples representing the data in tabular form. Each tuple consists of a whitespace left margin and the contents of a column. Separator lines will consist of a margin and text tuple where the text is zero-width and the “margin” is as wide as the table.

Maceration is useful if you wish to insert color codes to colorize the data or otherwise manipulate the data post-layout. If you don’t want to do this, see tabulate.

Arguments

• table - The data to display.

Errors

Any errors of lay_out. If the data has already been laid out, this method will throw no errors.

Example

extern crate term;
// ... [some details omitted]
// 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.",
        "It doesn't natively support color codes, but it is easy enough to combine with a crate like term.",
    ],
    vec!["", "Two or more rows of columns makes a table.", ""],
];
let mut colonnade = Colonnade::new(3, 80)?;

// configure the table a bit
colonnade.spaces_between_rows(1).left_margin(4)?.fixed_width(15)?;
colonnade.columns[0].alignment(Alignment::Right).left_margin(8);
colonnade.columns[1].alignment(Alignment::Center).clear_limits();
// if the text is in colored cells, you will probably want some padding
colonnade.padding(1)?;
///
// now print out the table
let mut t = term::stdout().unwrap();
for row in colonnade.macerate(&text)? {
    for line in row {
        for (i, (margin, text)) in line.iter().enumerate() {
            write!(t, "{}", margin)?;
            let background_color = if i % 2 == 0 {
                term::color::WHITE
            } else {
                term::color::BLACK
            };
            let foreground_color = match i % 3 {
                1 => term::color::GREEN,
                2 => term::color::RED,
                _ => term::color::BLUE,
            };
            t.bg(background_color)?;
            t.fg(foreground_color)?;
            write!(t, "{}", text)?;
            t.reset()?;
        }
        println!();
    }
}

pub fn reset(&mut self)

Erase column widths established by a previous tabulate or macerate.

Note that adjusting any configuration that may affect the horizontal layout of data has an equivalent effect, forcing a fresh layout of the columns.

Example

let mut colonnade = Colonnade::new(3, 80)?;
colonnade.alignment(Alignment::Right);
for line in colonnade.tabulate(&[[100, 200, 300]])? {
    println!("{}", line);
}
// 100 200 300
for line in colonnade.tabulate(&[[1, 2, 3]])? {
    println!("{}", line);
}
//   1   2   3
colonnade.reset();
for line in colonnade.tabulate(&[[1, 2, 3]])? {
    println!("{}", line);
}
// 1 2 3

pub fn spaces_between_rows(&mut self, n: usize) -> &mut Self

Specify a number of blank lines to insert between table rows.

Arguments

• n - A number of spaces.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// we want rows to be separated by a single blank line
colonnade.spaces_between_rows(1);

pub fn priority(&mut self, priority: usize) -> &mut Self

Assign the same priority to all columns. By default, all columns have the lowest priority.

Priority determines the order in which columns give up space when the viewport lacks sufficient space to display all columns without wrapping. Lower priority columns give up space first.

Arguments

• priority - The common priority. Lower numbers confer higher priority; 0 is the highest priority.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns the highest priority
colonnade.priority(0);
// now demote the last column
colonnade.columns[3].priority(1);

pub fn max_width( &mut self, max_width: usize ) -> Result<&mut Self, ColonnadeError>

Assign the same maximum width to all columns. By default columns have no maximum width.

Arguments

• max_width - The common maximum width.

Errors

• ColonnadeError::MinGreaterThanMax - Assigning a maximum width in conflict with some assigned minimum width.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a maximum width of 20
colonnade.max_width(20)?;
// at most we will now use only 83 of the characters provided by the viewport (until we mess with margins)

pub fn min_width( &mut self, min_width: usize ) -> Result<&mut Self, ColonnadeError>

Assign the same minimum width to all columns. By default columns have no minimum width.

Arguments

• min_width - The common minimum width.

Errors

• ColonnadeError::MinGreaterThanMax - Assigning a maximum width in conflict with some assigned minimum width.
• ColonnadeError::InsufficientSpace - Assigning this minimum width means the columns require more space than the viewport provides.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a minimum width of 20
colonnade.min_width(20)?;
// we will now use at least 83 of the characters provided by the viewport (until we mess with margins)

pub fn fixed_width(&mut self, width: usize) -> Result<&mut Self, ColonnadeError>

Assign the same maximum and minimum width to all columns. By default columns have neither a maximum nor a minimum width.

Arguments

• width - The common width.

Errors

This method is a convenience method which assigns all columns the same maximum and minimum width. Therefore the errors thrown are those thrown by max_width and min_width.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a width of 20
colonnade.fixed_width(20)?;
// we will now use at exactly 83 of the characters provided by the viewport (until we mess with margins)

pub fn clear_limits(&mut self) -> &mut Self

Remove any maximum or minimum column widths.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// assign all columns a width of 20
colonnade.fixed_width(20)?;
// later ...
colonnade.clear_limits();

pub fn alignment(&mut self, alignment: Alignment) -> &mut Self

Assign all columns the same alignment. The default alignment is left.

Arguments

• alignment - The desired alignment.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// all columns should be right-aligned (they're numeric)
colonnade.alignment(Alignment::Right);

pub fn vertical_alignment( &mut self, vertical_alignment: VerticalAlignment ) -> &mut Self

Assign all columns the same vertical alignment. The default alignment is top.

Arguments

• vertical_alignment - The desired alignment.

Example

let mut colonnade = Colonnade::new(4, 100)?;
// all columns should be right-aligned (they're numeric)
colonnade.vertical_alignment(VerticalAlignment::Middle);

pub fn left_margin( &mut self, left_margin: usize ) -> Result<&mut Self, ColonnadeError>

Assign all columns the same left margin. The left margin is a number of blank spaces before the content of the column. By default the first column has a left margin of 0 and the other columns have a left margin of 1.

Arguments

• left_margin - The width in blank spaces of the desired margin.

Errors

• ColonnadeError::InsufficientSpace - This margin will require more space than is available in the viewport.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.left_margin(2)?;

pub fn padding(&mut self, padding: usize) -> Result<&mut Self, ColonnadeError>

Assign all columns the same padding. The padding is a number of blank spaces before and after the contents of the column and a number of blank lines above and below it. By default the padding is 0. You most likely don’t want any padding unless you are colorizing the text – text immediately after color transitions is more difficult to read and less aesthetically pleasing.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Errors

• ColonnadeError::InsufficientSpace - This padding will require more space than is available in the viewport.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding(1)?;

pub fn padding_horizontal( &mut self, padding: usize ) -> Result<&mut Self, ColonnadeError>

Assign all columns the same horizontal padding – space before and after the column’s text.

See padding.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Errors

• ColonnadeError::InsufficientSpace - This padding will require more space than is available in the viewport.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding_horizontal(1)?;

pub fn padding_left( &mut self, padding: usize ) -> Result<&mut Self, ColonnadeError>

Assign all columns the same left padding – space before the column’s text.

See padding.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Errors

• ColonnadeError::InsufficientSpace - This padding will require more space than is available in the viewport.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding_left(1)?;

pub fn padding_right( &mut self, padding: usize ) -> Result<&mut Self, ColonnadeError>

Assign all columns the same right padding – space after the column’s text.

See padding.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Errors

• ColonnadeError::InsufficientSpace - This padding will require more space than is available in the viewport.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding_right(1)?;

pub fn padding_vertical(&mut self, padding: usize) -> &mut Self

Assign all columns the same vertical padding – blank lines before and after the column’s text.

See padding.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding_vertical(1);

pub fn padding_top(&mut self, padding: usize) -> &mut Self

Assign all columns the same top padding – blank lines before the column’s text.

See padding.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding_top(1);

pub fn padding_bottom(&mut self, padding: usize) -> &mut Self

Assign all columns the same bottom padding – blank lines after the column’s text.

See padding.

Arguments

• padding - The width in blank spaces/lines of the desired padding.

Example

let mut colonnade = Colonnade::new(4, 100)?;
colonnade.padding_bottom(1);

pub fn hyphenate(&mut self, hyphenate: bool) -> &mut Self

Toggle the hyphenation of all columns.

See Column::hyphenate.

Arguments

• hyphenate - Whether long words will be hyphenated when split.

Trait Implementations

impl Clone for Colonnade

fn clone(&self) -> Colonnade

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Colonnade

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.