Skip to main content

rustcmdpev_core/display/
tree.rs

1//! Tree-drawing primitives for plan rendering.
2//!
3//! This module owns the glyphs and joint-selection logic used to draw plan
4//! trees. Rendering code combines these with formatting and color helpers
5//! from the sibling `format` and `colors` modules.
6//!
7//! [`TreeStyle`] groups every glyph the renderer needs into one struct so
8//! callers can swap between the historical Unicode look (parity with
9//! gocmdpev), a portable ASCII fallback, and a heavier Unicode style without
10//! editing constants per call site.
11
12use crate::constants::{
13    TREE_BRANCH, TREE_ELBOW, TREE_NODE_CONNECTOR, TREE_OUTPUT_BRANCH, TREE_OUTPUT_CHILD,
14    TREE_OUTPUT_CONTINUATION, TREE_OUTPUT_PADDING, TREE_ROOT_MARKER, TREE_VERTICAL,
15};
16use crate::structure::data::plan::Plan;
17
18/// A complete set of glyphs for drawing a plan tree.
19///
20/// Each field maps directly onto a position in the rendered output. The
21/// `vertical_pad` and `padding` fields keep child indentation aligned even
22/// when the elbow/branch glyphs change width.
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24pub struct TreeStyle {
25    pub root_marker: &'static str,
26    pub vertical: &'static str,
27    pub vertical_pad: &'static str,
28    pub elbow: &'static str,
29    pub branch: &'static str,
30    pub node_connector: &'static str,
31    pub output_child: &'static str,
32    pub output_branch: &'static str,
33    pub output_continuation: &'static str,
34    pub output_padding: &'static str,
35    pub padding: &'static str,
36}
37
38impl TreeStyle {
39    /// Historical Unicode glyphs matching the gocmdpev parity output.
40    pub const fn unicode() -> Self {
41        Self {
42            root_marker: TREE_ROOT_MARKER,
43            vertical: TREE_VERTICAL,
44            vertical_pad: " ",
45            elbow: TREE_ELBOW,
46            branch: TREE_BRANCH,
47            node_connector: TREE_NODE_CONNECTOR,
48            output_child: TREE_OUTPUT_CHILD,
49            output_branch: TREE_OUTPUT_BRANCH,
50            output_continuation: TREE_OUTPUT_CONTINUATION,
51            output_padding: TREE_OUTPUT_PADDING,
52            padding: "  ",
53        }
54    }
55
56    /// Pure ASCII alternative for terminals or pipelines that mangle Unicode.
57    pub const fn ascii() -> Self {
58        Self {
59            root_marker: "+",
60            vertical: "|",
61            vertical_pad: " ",
62            elbow: "+",
63            branch: "+",
64            node_connector: "--",
65            output_child: ">> ",
66            output_branch: "+>  ",
67            output_continuation: "|  ",
68            output_padding: "   ",
69            padding: "  ",
70        }
71    }
72
73    /// Heavier Unicode box-drawing variant with bolder strokes.
74    pub const fn heavy() -> Self {
75        Self {
76            root_marker: "┳",
77            vertical: "┃",
78            vertical_pad: " ",
79            elbow: "┗",
80            branch: "┣",
81            node_connector: "━┓",
82            output_child: "╚▶ ",
83            output_branch: "┣▶  ",
84            output_continuation: "┃  ",
85            output_padding: "   ",
86            padding: "  ",
87        }
88    }
89
90    pub fn parse(name: &str) -> Option<TreeStyle> {
91        match name {
92            "unicode" | "default" => Some(TreeStyle::unicode()),
93            "ascii" | "plain" => Some(TreeStyle::ascii()),
94            "heavy" | "bold" => Some(TreeStyle::heavy()),
95            _ => None,
96        }
97    }
98}
99
100impl Default for TreeStyle {
101    fn default() -> Self {
102        Self::unicode()
103    }
104}
105
106/// Choose the joint glyph for a node based on whether it has multiple children
107/// or is the last child of its parent.
108pub fn node_joint(child_count: usize, last_child: bool) -> &'static str {
109    styled_node_joint(&TreeStyle::unicode(), child_count, last_child)
110}
111
112pub fn styled_node_joint(style: &TreeStyle, child_count: usize, last_child: bool) -> &'static str {
113    if child_count > 1 || last_child {
114        style.elbow
115    } else {
116        style.branch
117    }
118}
119
120/// Continuation glyphs to extend the prefix as rendering descends.
121pub fn prefix_continuation(child_count: usize, last_child: bool) -> &'static str {
122    styled_prefix_continuation(&TreeStyle::unicode(), child_count, last_child)
123}
124
125pub fn styled_prefix_continuation(
126    style: &TreeStyle,
127    child_count: usize,
128    last_child: bool,
129) -> &'static str {
130    if child_count > 1 || last_child {
131        style.padding
132    } else {
133        style.vertical
134    }
135}
136
137/// Glyph used at the leftmost column of an output line for a child plan.
138pub fn output_terminator(index: usize, plan: &Plan) -> &'static str {
139    styled_output_terminator(&TreeStyle::unicode(), index, plan)
140}
141
142pub fn styled_output_terminator(style: &TreeStyle, index: usize, plan: &Plan) -> &'static str {
143    if index == 0 {
144        if plan.plans.is_empty() {
145            style.output_child
146        } else {
147            style.output_branch
148        }
149    } else if plan.plans.is_empty() {
150        style.output_padding
151    } else {
152        style.output_continuation
153    }
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159
160    #[test]
161    fn node_joint_uses_elbow_for_multi_child_or_last() {
162        assert_eq!(node_joint(2, false), TREE_ELBOW);
163        assert_eq!(node_joint(1, true), TREE_ELBOW);
164    }
165
166    #[test]
167    fn node_joint_uses_branch_for_single_non_last() {
168        assert_eq!(node_joint(1, false), TREE_BRANCH);
169        assert_eq!(node_joint(0, false), TREE_BRANCH);
170    }
171
172    #[test]
173    fn prefix_continuation_collapses_for_multi_child_or_last() {
174        assert_eq!(prefix_continuation(2, false), "  ");
175        assert_eq!(prefix_continuation(1, true), "  ");
176    }
177
178    #[test]
179    fn prefix_continuation_keeps_vertical_for_single_non_last() {
180        assert_eq!(prefix_continuation(1, false), TREE_VERTICAL);
181    }
182
183    #[test]
184    fn output_terminator_handles_leaf_first_line() {
185        let plan = Plan::default();
186        assert_eq!(output_terminator(0, &plan), TREE_OUTPUT_CHILD);
187    }
188
189    #[test]
190    fn output_terminator_handles_branch_first_line() {
191        let mut plan = Plan::default();
192        plan.plans.push(Plan::default());
193        assert_eq!(output_terminator(0, &plan), TREE_OUTPUT_BRANCH);
194    }
195
196    #[test]
197    fn output_terminator_handles_leaf_continuation() {
198        let plan = Plan::default();
199        assert_eq!(output_terminator(1, &plan), TREE_OUTPUT_PADDING);
200    }
201
202    #[test]
203    fn output_terminator_handles_branch_continuation() {
204        let mut plan = Plan::default();
205        plan.plans.push(Plan::default());
206        assert_eq!(output_terminator(1, &plan), TREE_OUTPUT_CONTINUATION);
207    }
208
209    #[test]
210    fn ascii_style_has_no_unicode_box_drawing_glyphs() {
211        let style = TreeStyle::ascii();
212        let payload = format!(
213            "{}{}{}{}{}{}{}{}{}{}",
214            style.root_marker,
215            style.vertical,
216            style.elbow,
217            style.branch,
218            style.node_connector,
219            style.output_child,
220            style.output_branch,
221            style.output_continuation,
222            style.output_padding,
223            style.padding,
224        );
225        assert!(
226            payload.is_ascii(),
227            "expected ascii-only payload, got: {payload}"
228        );
229    }
230
231    #[test]
232    fn heavy_style_uses_distinct_glyphs_from_unicode() {
233        let unicode = TreeStyle::unicode();
234        let heavy = TreeStyle::heavy();
235        assert_ne!(unicode.vertical, heavy.vertical);
236        assert_ne!(unicode.elbow, heavy.elbow);
237        assert_ne!(unicode.root_marker, heavy.root_marker);
238    }
239
240    #[test]
241    fn parse_returns_named_style_or_none() {
242        assert_eq!(TreeStyle::parse("unicode"), Some(TreeStyle::unicode()));
243        assert_eq!(TreeStyle::parse("ascii"), Some(TreeStyle::ascii()));
244        assert_eq!(TreeStyle::parse("heavy"), Some(TreeStyle::heavy()));
245        assert_eq!(TreeStyle::parse("bold"), Some(TreeStyle::heavy()));
246        assert_eq!(TreeStyle::parse("rococo"), None);
247    }
248
249    #[test]
250    fn styled_helpers_match_legacy_helpers_for_unicode_style() {
251        let style = TreeStyle::unicode();
252        assert_eq!(styled_node_joint(&style, 2, false), node_joint(2, false));
253        assert_eq!(
254            styled_prefix_continuation(&style, 1, false),
255            prefix_continuation(1, false)
256        );
257        let mut plan = Plan::default();
258        plan.plans.push(Plan::default());
259        assert_eq!(
260            styled_output_terminator(&style, 0, &plan),
261            output_terminator(0, &plan)
262        );
263    }
264}