cli_grid/lib.rs
1//! A small and dependency free crate for formatting the terminal outputs
2//! in a column based grid style.
3//! ```text
4//! [---------------------] [---------------------] [---------------------]
5//! [---------------------] [---------------------] [---------------------]
6//! [---------------------] [---------------------] [---------------------]
7//! <----------1----------> <-2->
8//!
9//! 1: Grid column
10//! 2: Grid padding
11//! ```
12//! Each `Cell` of the grid can span into 1 or more columns.
13//! ```text
14//! [ Cell with colspan 1 ] [---------------------] [---------------------]
15//! [-------------- Cell with colspan 2 --------------] [---------------------]
16//! [---------------------------- Cell with colspan 3 ----------------------------]
17//! ```
18//!
19//! Horizontal alignments of cells are [`HAlign::Left`], [`HAlign::Center`],
20//! [`HAlign::Right`] and [`HAlign::Fill`],
21//!
22//! [`HAlign::Left`]: enum.HAlign.html#variant.Left
23//! [`HAlign::Center`]: enum.HAlign.html#variant.Center
24//! [`HAlign::Right`]: enum.HAlign.html#variant.Right
25//! [`HAlign::Fill`]: enum.HAlign.html#variant.Fill
26//!
27//! Vertical alignments of cells are [`VAlign::Top`], [`VAlign::Middle`] and
28//! [`VAlign::Bottom`].
29//!
30//! [`VAlign::Top`]: enum.VAlign.html#variant.Top
31//! [`VAlign::Middle`]: enum.VAlign.html#variant.Middle
32//! [`VAlign::Bottom`]: enum.VAlign.html#variant.Bottom
33//!
34//! # Examples:
35//! ```rust
36//! use cli_grid::*;
37//!
38//! let grid = Grid::builder(vec![
39//! Row::new(vec![
40//! Cell::new("1".into(), 1),
41//! Cell::new("1".into(), 1),
42//! Cell::new("1".into(), 1),
43//! ]),
44//! Row::new(vec![
45//! Cell::new("2".into(), 2),
46//! Cell::new("1".into(), 1),
47//! ]),
48//! Row::new(vec![
49//! Cell::new("3".into(), 3),
50//! ]),
51//! ])
52//! .default_blank_char('.')
53//! .column_width(15)
54//! .build();
55//!
56//! let expected = format!(
57//! "{}\n{}\n{}\n",
58//! "1.............. 1.............. 1..............",
59//! "2.............................. 1..............",
60//! "3..............................................",
61//! );
62//!
63//! assert_eq!(grid.to_string(), expected);
64//! ```
65//! Multi line `Cell`s also is supported:
66//! ```rust
67//! use cli_grid::*;
68//!
69//! let grid = Grid::builder(vec![
70//! Row::new(vec![
71//! Cell::new("1".into(), 1),
72//! Cell::new("1\n1\n1".into(), 1),
73//! Cell::new("1".into(), 1),
74//! ]),
75//! Row::new(vec![
76//! Cell::new("2".into(), 2),
77//! Cell::new("1".into(), 1),
78//! ]),
79//! Row::new(vec![
80//! Cell::new("3".into(), 3),
81//! ]),
82//! ])
83//! .default_blank_char('.')
84//! .column_width(15)
85//! .build();
86//!
87//! let expected = format!(
88//! "{}\n{}\n{}\n{}\n{}\n",
89//! "1.............. 1.............. 1..............",
90//! "............... 1.............. ...............",
91//! "............... 1.............. ...............",
92//! "2.............................. 1..............",
93//! "3..............................................",
94//! );
95//!
96//! assert_eq!(grid.to_string(), expected);
97//! ```
98//! So nested grids also is supported:
99//! ```rust
100//! use cli_grid::*;
101//!
102//! let nested_grid = Grid::builder(vec![
103//! Row::new(vec![
104//! Cell::new("1".into(), 1),
105//! Cell::new("1".into(), 1),
106//! ]),
107//! Row::new(vec![
108//! Cell::new("1".into(), 1),
109//! Cell::new("1".into(), 1),
110//! ]),
111//! Row::new(vec![
112//! Cell::new("1".into(), 1),
113//! Cell::new("1".into(), 1),
114//! ]),
115//! ])
116//! .default_h_align(HAlign::Center)
117//! .default_blank_char('-')
118//! .column_width(5)
119//! .build();
120//!
121//! let grid = Grid::builder(vec![
122//! Row::new(vec![
123//! Cell::new("2".into(), 2),
124//! Cell::new("1".into(), 1),
125//! ]),
126//! Row::new(vec![
127//! Cell::new("1".into(), 1),
128//! Cell::new(nested_grid.to_string(), 1),
129//! Cell::new("1".into(), 1),
130//! ]),
131//! Row::new(vec![
132//! Cell::new("3".into(), 3),
133//! ]),
134//! ])
135//! .default_h_align(HAlign::Center)
136//! .default_v_align(VAlign::Middle)
137//! .default_blank_char('.')
138//! .column_width(15)
139//! .build();
140//!
141//! let expected = format!(
142//! "{}\n{}\n{}\n{}\n{}\n",
143//! "...............2............... .......1.......",
144//! "............... ..--1-- --1--.. ...............",
145//! ".......1....... ..--1-- --1--.. .......1.......",
146//! "............... ..--1-- --1--.. ...............",
147//! ".......................3.......................",
148//! );
149//!
150//! assert_eq!(grid.to_string(), expected);
151//! ```
152//!
153//! Empty cells and rows can be created by [`Cell::new_empty`] and [`Row::new_empty`] methods.
154//!
155//! [`Cell::new_empty`]: struct.Cell.html#method.new_empty
156//! [`Row::new_empty`]: struct.Row.html#method.new_empty
157//!
158//! Filled cells and rows can be created by [`Cell::new_fill`] and [`Row::new_fill`] methods.
159//!
160//! [`Cell::new_fill`]: struct.Cell.html#method.new_fill
161//! [`Row::new_fill`]: struct.Row.html#method.new_fill
162//!
163
164mod grid;
165mod row;
166mod cell;
167mod options;
168
169pub use cell::{Cell, CellBuilder, HAlign, VAlign};
170pub use grid::{Grid, GridBuilder};
171pub use row::{Row, RowBuilder};
172pub use options::Options;