## veg

Flexible tables

### 15 releases(4 breaking)

 0.5.0 Mar 10, 2024 Jan 6, 2024 Dec 18, 2023 Dec 12, 2023 Dec 11, 2023

#2 in #colored

Used in 4 crates

63KB
256 lines

# Usage

1. Implement `Table` trait for your custom type by defining the `row` method which returns the type as a `Vec``<``String``>`.

2. Create a `Veg` struct with a header definition based on a Markdown table header.

3. Use the `Veg` struct like a `Vec` to gather instances of your type.

4. Call one of the following methods to generate a table:

# Example

``````// Import Veg
# use anyhow::anyhow;
use veg::Veg;

// Create a custom type
struct Point {
x: f32,
y: f32,
}

// Implement a method that creates a Box of the custom type
impl Point {
fn new(x: f32, y: f32) -> Box<Point> {
Box::new(Point { x, y })
}
}

// Implement the veg::Table::row method to define how to print the custom type
impl veg::Table for Point {
fn row(&self) -> Vec<String> {
// Add `\$` for inline LaTeX math spans
[self.x, self.y].iter().map(|x| format!("\${x}\$")).collect()

// Other ideas:
//
// - Add 3 decimal places:
//
// [self.x, self.y].iter().map(|x| format!("\${x:.3}\$")).collect()
//
// - Do something different for x and y:
//
// vec![
//     format!("\${:.1}\$", self.x),
//     format!("\${:.4}\$", self.y),
// ]
//
// - Just convert to string:
//
// [self.x, self.y].iter().map(|x| x.to_string())).collect()
//
// ...
}
}

// Create a Veg via the table method with a header definition
let mut v = Veg::table("\$x\$|\$y\$\n-:|-:");

v.push(Point::new(1.0, 1.0));

// Add a bunch of points
v.append(&mut vec![
Point::new(2.0, 4.0),
Point::new(3.0, 9.0),
Point::new(4.0, 16.0),
]);

// Render as a markdown table
assert_eq!(
v.markdown().unwrap(),
"\
| \$x\$ |  \$y\$ |
|----:|-----:|
| \$1\$ |  \$1\$ |
| \$2\$ |  \$4\$ |
| \$3\$ |  \$9\$ |
| \$4\$ | \$16\$ |
\
",
);

// Render as a markdown table with a modified header definition
assert_eq!(
v.markdown_with(Some("X|Y\n-|-"), None).unwrap(),
"\
| X   | Y    |
|-----|------|
| \$1\$ | \$1\$  |
| \$2\$ | \$4\$  |
| \$3\$ | \$9\$  |
| \$4\$ | \$16\$ |
\
",
);

// Render as a markdown table with a modified header definition to increase the
// column widths
assert_eq!(
v.markdown_with(Some("X|Y\n------|------"), None).unwrap(),
"\
| X      | Y      |
|--------|--------|
| \$1\$    | \$1\$    |
| \$2\$    | \$4\$    |
| \$3\$    | \$9\$    |
| \$4\$    | \$16\$   |
\
",
);

// Just render the second column
assert_eq!(
v.markdown_with(None, Some(&[1])).unwrap(),
"\
|  \$y\$ |
|-----:|
|  \$1\$ |
|  \$4\$ |
|  \$9\$ |
| \$16\$ |
\
",
);

// Reorder the columns
assert_eq!(
v.markdown_with(None, Some(&[1, 0])).unwrap(),
"\
|  \$y\$ | \$x\$ |
|-----:|----:|
|  \$1\$ | \$1\$ |
|  \$4\$ | \$2\$ |
|  \$9\$ | \$3\$ |
| \$16\$ | \$4\$ |
\
",
);

// Duplicate column `y`
assert_eq!(
v.markdown_with(None, Some(&[0, 1, 1])).unwrap(),
"\
| \$x\$ |  \$y\$ |  \$y\$ |
|----:|-----:|-----:|
| \$1\$ |  \$1\$ |  \$1\$ |
| \$2\$ |  \$4\$ |  \$4\$ |
| \$3\$ |  \$9\$ |  \$9\$ |
| \$4\$ | \$16\$ | \$16\$ |
\
",
);

// Try to give invalid column indexes
assert_eq!(
v.markdown_with(None, Some(&[3, 2, 0, 1])).unwrap_err().to_string(),
"Invalid column indexes: 2, 3",
);
``````

# Features

## `colored`

The `colored` feature enables the `veg::colored` module which provides the same API, but uses the `colored` crate to colorize `Veg` tables for printing to the terminal.

See `tests/colored.rs` and/or run `cargo test --features colored --test colored -- --nocapture`.

# Changelog

• 0.1.0 (2023-12-11): Initial release
• 0.2.0 (2023-12-11): Convert the table function to a method
• 0.3.0 (2023-12-12): Enable single column tables; add the `markdown_with` method to enable column subsets, reordering, duplicating, and temporary headers; add examples to the module doctest
• 0.4.0 (2023-12-16): Add `colored` feature/module enabling terminal colors via the `colored` crate
• 0.4.1 (2023-12-16): Fix changelog
• 0.4.2 (2023-12-17): Improve readme, doc, and tests
• 0.4.3 (2023-12-17): Add doc for colored module; make the colored png smaller; improve doc
• 0.4.4 (2023-12-17): Fix colored module doc
• 0.4.5 (2023-12-17): Fix doc
• 0.4.6 (2023-12-18): Fix veg::colored::Veg::table argument type
• 0.4.7 (2023-12-18): Add `Veg::is_empty` methods
• 0.4.8 (2024-01-06): Fix empty string find unwrap issue; update dependencies
• 0.5.0 (2024-03-10): Fix Unicode text width algorithm; update dependencies

~0.8–10MB
~64K SLoC