ttygrid 0.3.0

Grid layout engine for tabular data displayed in a TTY
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

/// grid defines a [crate::TTYGrid] full of headers, which are associated with lines.
///
/// Each header is typically defined by the [crate::header!] macro, and [crate::add_line!] is used
/// to add content to the grid. Headers may have an optional priority; in the case where the line
/// is too long to be displayed on a terminal of that width, columns with a lower priority will be
/// removed to help the higher priority items fit.
///
/// Example:
/// ```
///    use ttygrid::{grid, add_line, header};
///    let mut grid = grid!(
///        header!("line"),     header!("one", 1),  header!("two", 2),
///        header!("three", 3), header!("four", 4), header!("five", 5)
///    ).unwrap();
///
///    add_line!(grid, "0", "1", "2", "3", "4", "5");
///
///    println!("{}", grid.display().unwrap());
/// ```
///
#[macro_export]
macro_rules! grid {
    ($($header:expr),*) => {
        {
            use $crate::TTYGrid;
            TTYGrid::new(vec![$($header.clone(),)*])
        }
    };
}

/// header defines a [crate::SafeGridHeader] for use with the [crate::TTYGrid].
///
/// It is variadic and composes of two current options:
///
/// - text by itself as the first position will yield a base header with the text set.
/// - a second parameter, optionally provided, will set the priority to a [usize]. This controls
///   display capabilities where the terminal width is too small to display all columns. See
///   [crate::grid!] for more.
///
/// Examples:
///
/// ```
///    use ttygrid::header;
///
///    assert_eq!(header!("header").borrow().text(), "header");
///
///    let priority_header = header!("header2", 10);
///    assert_eq!(priority_header.borrow().text(), "header2");
///    assert_eq!(priority_header.borrow().priority(), 10);
///
///    let name = "foo";
///    let priority = 20;
///    assert_eq!(header!(name, priority), header!("foo", 20));
/// ```
#[macro_export]
macro_rules! header {
    ($text:tt) => {{
        use std::cell::RefCell;
        use std::rc::Rc;
        use $crate::GridHeader;
        Rc::new(RefCell::new(GridHeader::default().set_text($text)))
    }};

    ($text:tt,$priority:tt) => {{
        use std::cell::RefCell;
        use std::rc::Rc;
        use $crate::GridHeader;
        Rc::new(RefCell::new(
            GridHeader::default()
                .set_text($text)
                .set_priority($priority),
        ))
    }};
}

/// add_line defines a [crate::GridLine] with [crate::GridItem]s attached.
///
/// The first element provided is the grid; and the rest are strings which correspond to headers
/// set to the grid, in order of appearance. A line **must** be equal to the number of headers,
/// otherwise this macro will yield [anyhow::Error].
///
/// Please see the [crate::grid!] example for more.
#[macro_export]
macro_rules! add_line {
    ($grid:expr, $($content:expr),*) => {
        {
            use anyhow::anyhow;
            use $crate::{GridLine, GridItem};
            let content = vec![$($content),*];

            if content.len() != $grid.headers().len() {
                Err(anyhow!("ttygrid panic: content items must equal the number of headers"))
            } else {
                $grid.add_line(GridLine(content.iter().enumerate().map(|(i, item)| {
                    GridItem::new($grid.headers().get(i).unwrap().clone(), item.to_string())
                }).collect()));

                Ok(())
            }
        }
    };
}