boxy_cli/lib.rs
1#![warn(missing_docs)]
2
3//! # boxy-cli
4//!
5//! A Rust library for creating beautifully styled, multi-segment text boxes in terminal
6//! applications — with full Unicode border support, true-color text, word-wrapping, columnar
7//! layouts, and automatic terminal-width awareness.
8//!
9//! ## Features
10//!
11//! - **9 border styles** — classic ASCII, single, double, bold, rounded, and more
12//! - **True-color support** — hex color codes for both borders and per-line text
13//! - **Multi-segment boxes** — stack multiple sections separated by smart dividers
14//! - **Columnar layouts** — side-by-side columns inside a single box, with per-segment
15//! ratio control and correct `┼`/`┬`/`┴` junction characters where column boundaries meet
16//! - **Word wrapping** — automatic wrapping to terminal width with internal padding awareness
17//! - **Text alignment** — left, center, or right per segment
18//! - **Terminal-aware sizing** — auto-sizes to terminal width, or use a fixed width
19//! - **Two APIs** — imperative ([`Boxy`]) and fluent builder
20//! ([`BoxyBuilder`])
21//! - **Macro support** — [`boxy!`] for quick one-liner (Work in Progress)
22//!
23//! ## Known Limitations
24//!
25//! **Unicode wide characters** — characters that occupy two terminal columns (CJK
26//! glyphs, most emoji) are measured as one column internally. Text containing these
27//! characters will appear narrower than expected and centering/alignment will be off.
28//! Full wide-character support is planned for a future release.
29//!
30//! ## Quick Start
31//!
32//! ```rust
33//! use boxy_cli::prelude::*;
34//!
35//! // Fluent builder API
36//! Boxy::builder()
37//! .box_type(BoxType::Double)
38//! .color("#00ffff")
39//! .add_segment("Hello, boxy-cli!", "#ffffff", BoxAlign::Center)
40//! .add_segment("A terminal box library for Rust", "#32CD32", BoxAlign::Center)
41//! .padding(BoxPad::uniform(1), BoxPad::vh(1, 2))
42//! .build()
43//! .display();
44//! ```
45//!
46//! ## Columnar Layout
47//!
48//! Columnar segments let you place content side-by-side inside one box. Column widths are
49//! controlled by ratio values — `vec![1, 2, 1]` gives the middle column twice the space.
50//!
51//! ```rust
52//! use boxy_cli::prelude::*;
53//!
54//! let mut b = Boxy::new(BoxType::Single, "#00ffff");
55//! b.add_text_sgmt("Project Status", "#ffffff", BoxAlign::Center);
56//! b.add_col_text_sgmt(BoxAlign::Left, 3);
57//! b.add_col_text_line("Name", "#aaaaaa", &0usize);
58//! b.add_col_text_line("Status", "#aaaaaa", &1usize);
59//! b.add_col_text_line("Notes", "#aaaaaa", &2usize);
60//! b.add_col_text_line("Lumio V2", "#ffffff", &0usize);
61//! b.add_col_text_line("Shipped", "#32CD32", &1usize);
62//! b.add_col_text_line("Internship project", "#ffffff", &2usize);
63//! b.set_segment_ratios(1, vec![1, 1, 2]);
64//! b.display();
65//! ```
66//!
67//! ## Further Reading
68//!
69//! - [`Boxy`] — imperative API reference
70//! - [`BoxyBuilder`] — builder API reference
71//! - [`BoxType`] — all available border styles
72//! - [`boxy!`] — macro reference
73//! - [GitHub README](https://github.com/BastaMasta/boxy-cli) — more examples and screenshots
74
75#[allow(dead_code)]
76pub mod boxer;
77mod constructs;
78mod macros;
79pub mod prelude;
80pub(crate) mod templates;
81
82// crate tests
83mod tests;
84
85// Re-export prelude at crate root
86pub use prelude::*;