Skip to main content

cornerstone/
help.rs

1//! Help rendering with selectable presets.
2//!
3//! Three presets ship, each modelled on a real house style:
4//!
5//! * [`HelpStyle::Standard`] — the classic `Usage: / Commands: / Options:`
6//!   layout (clap-like).
7//! * [`HelpStyle::Banner`] — an indented banner with a tagline and example
8//!   invocation lines, flags grouped under the command.
9//! * [`HelpStyle::Sections`] — a name header followed by one block per command,
10//!   each showing its invocation pattern and a wrapped description.
11//!
12//! Every preset renders both app-level help and per-command help, and supports
13//! a compact tier (`-h`) and an expanded tier (`--help`) with examples.
14
15use crate::spec::{Command, FlagKind};
16use crate::style as s;
17
18/// Which visual preset to use for help output. Beyond the three built-ins, an
19/// app can supply a [`HelpRenderer`] for a fully custom look (see
20/// [`crate::app::App::help_renderer`]).
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22#[derive(Default)]
23pub enum HelpStyle {
24    #[default]
25    Standard,
26    Banner,
27    Sections,
28}
29
30
31/// A pluggable help renderer. Implement this and register it with
32/// [`crate::app::App::help_renderer`] to define a help look the built-in presets
33/// don't cover. The library calls these to produce the final strings; it does
34/// no post-processing, so the renderer has full control.
35pub trait HelpRenderer: 'static {
36    /// Render the top-level app help. `long` selects the expanded tier.
37    fn app_help(&self, info: &AppInfo, long: bool) -> String;
38    /// Render help for a single subcommand.
39    fn command_help(&self, app_name: &str, cmd: &Command, long: bool) -> String;
40}
41
42/// Everything the renderer needs to know about the app itself.
43pub struct AppInfo<'a> {
44    pub name: &'a str,
45    pub version: &'a str,
46    pub about: &'a str,
47    pub long_about: &'a str,
48    pub commands: &'a [Command],
49    /// Global flags available on every command.
50    pub globals: &'a [crate::spec::Flag],
51}
52
53/// Render top-level help. `long` selects the expanded tier.
54pub fn app_help(info: &AppInfo, style: HelpStyle, long: bool) -> String {
55    match style {
56        HelpStyle::Standard => app_standard(info, long),
57        HelpStyle::Banner => app_banner(info, long),
58        HelpStyle::Sections => app_sections(info, long),
59    }
60}
61
62/// Render help for a single subcommand.
63pub fn command_help(app_name: &str, cmd: &Command, style: HelpStyle, long: bool) -> String {
64    match style {
65        HelpStyle::Standard => cmd_standard(app_name, cmd, long),
66        HelpStyle::Banner => cmd_banner(app_name, cmd, long),
67        HelpStyle::Sections => cmd_sections(app_name, cmd, long),
68    }
69}
70
71// ---------- shared helpers ----------
72
73fn usage_line(app_name: &str, cmd: &Command) -> String {
74    let mut u = format!("{} {}", app_name, cmd.name);
75    if !cmd.flags.is_empty() {
76        u.push_str(" [OPTIONS]");
77    }
78    for a in &cmd.args {
79        if a.variadic {
80            u.push_str(&format!(" [{}]...", a.name));
81        } else if a.required {
82            u.push_str(&format!(" <{}>", a.name));
83        } else {
84            u.push_str(&format!(" [{}]", a.name));
85        }
86    }
87    u
88}
89
90fn wrap_to(text: &str, width: usize, indent: &str) -> String {
91    let mut out = String::new();
92    let mut line_len = 0;
93    for (wi, word) in text.split_whitespace().enumerate() {
94        if wi != 0 && line_len + 1 + word.len() > width {
95            out.push('\n');
96            out.push_str(indent);
97            line_len = 0;
98        } else if wi != 0 {
99            out.push(' ');
100            line_len += 1;
101        }
102        out.push_str(word);
103        line_len += word.len();
104    }
105    out
106}
107
108// ---------- Standard preset ----------
109
110fn app_standard(info: &AppInfo, long: bool) -> String {
111    let mut out = String::new();
112    let about = if long && !info.long_about.is_empty() {
113        info.long_about
114    } else {
115        info.about
116    };
117    if !about.is_empty() {
118        out.push_str(&format!("{}\n\n", about));
119    }
120    out.push_str(&format!("{} {} [COMMAND]\n\n", s::bold("Usage:"), info.name));
121
122    if !info.commands.is_empty() {
123        out.push_str(&format!("{}\n", s::bold("Commands:")));
124        let w = info.commands.iter().map(|c| c.name.len()).max().unwrap_or(0);
125        for c in info.commands {
126            out.push_str(&format!("  {:<w$}  {}\n", s::cyan(&c.name), c.about, w = w));
127        }
128        out.push('\n');
129    }
130
131    out.push_str(&format!("{}\n", s::bold("Options:")));
132    for f in info.globals {
133        out.push_str(&format!("  {:<24}  {}\n", f.invocation(), f.help));
134    }
135    out
136}
137
138fn cmd_standard(app_name: &str, cmd: &Command, long: bool) -> String {
139    let mut out = String::new();
140    let about = if long && !cmd.long_about.is_empty() {
141        &cmd.long_about
142    } else {
143        &cmd.about
144    };
145    if !about.is_empty() {
146        out.push_str(&format!("{}\n\n", about));
147    }
148    if long && !cmd.examples.is_empty() {
149        out.push_str(&format!("{} {}\n\n", s::bold("Examples:"), cmd.examples.join("  ")));
150    }
151
152    // Group: show usage as `app cmd <subcommand>` and list the children.
153    if cmd.is_group() {
154        out.push_str(&format!(
155            "{} {} {} <subcommand>\n\n",
156            s::bold("Usage:"),
157            app_name,
158            cmd.name
159        ));
160        out.push_str(&format!("{}\n", s::bold("Commands:")));
161        let w = cmd.subcommands.iter().map(|c| c.name.len()).max().unwrap_or(0);
162        for c in &cmd.subcommands {
163            out.push_str(&format!("  {:<w$}  {}\n", s::cyan(&c.name), c.about, w = w));
164        }
165        return out;
166    }
167
168    out.push_str(&format!("{} {}\n", s::bold("Usage:"), usage_line(app_name, cmd)));
169
170    if !cmd.args.is_empty() {
171        out.push_str(&format!("\n{}\n", s::bold("Arguments:")));
172        let w = cmd.args.iter().map(|a| a.name.len() + 2).max().unwrap_or(0);
173        for a in &cmd.args {
174            let token = format!("<{}>", a.name);
175            out.push_str(&format!("  {:<w$}  {}\n", token, a.help, w = w));
176        }
177    }
178
179    out.push_str(&format!("\n{}\n", s::bold("Options:")));
180    if long {
181        for f in &cmd.flags {
182            out.push_str(&format!("  {}\n          {}\n\n", f.invocation(), f.help));
183        }
184        out.push_str("  -h, --help\n          Print help\n");
185    } else {
186        for f in &cmd.flags {
187            out.push_str(&format!("  {:<24}  {}\n", f.invocation(), f.help));
188        }
189        out.push_str(&format!("  {:<24}  Print help\n", "-h, --help"));
190    }
191    out
192}
193
194// ---------- Banner preset ----------
195
196fn app_banner(info: &AppInfo, long: bool) -> String {
197    let mut out = String::new();
198    out.push('\n');
199    out.push_str(&format!("  {} — {}\n\n", s::heading(info.name), info.about));
200
201    for c in info.commands {
202        let inv = usage_line(info.name, c);
203        out.push_str(&format!("  {:<32} {}\n", s::bold(&inv), c.about));
204    }
205    out.push('\n');
206
207    // Group flags per command, banner-style.
208    for c in info.commands {
209        if c.flags.is_empty() {
210            continue;
211        }
212        let group: Vec<String> = c
213            .flags
214            .iter()
215            .map(|f| {
216                let short = f.short.map(|s| format!("-{}", s)).unwrap_or_default();
217                format!("{} {}", short, f.help)
218            })
219            .collect();
220        out.push_str(&format!(
221            "  {} ({}): {}\n",
222            s::dim("Flags"),
223            c.name,
224            group.join("  ")
225        ));
226    }
227
228    if long && !info.long_about.is_empty() {
229        out.push_str(&format!("\n  {}\n", wrap_to(info.long_about, 70, "  ")));
230    }
231    out.push('\n');
232    out
233}
234
235fn cmd_banner(app_name: &str, cmd: &Command, long: bool) -> String {
236    let mut out = String::new();
237    out.push('\n');
238    out.push_str(&format!("  {} — {}\n\n", s::heading(&cmd.name), cmd.about));
239
240    if cmd.is_group() {
241        for c in &cmd.subcommands {
242            out.push_str(&format!(
243                "  {:<28} {}\n",
244                s::bold(format!("{} {} {}", app_name, cmd.name, c.name)),
245                c.about
246            ));
247        }
248        out.push('\n');
249        return out;
250    }
251
252    out.push_str(&format!("  {}\n", s::bold(usage_line(app_name, cmd))));
253
254    if !cmd.flags.is_empty() {
255        out.push('\n');
256        for f in &cmd.flags {
257            out.push_str(&format!("    {:<28} {}\n", f.invocation(), f.help));
258        }
259    }
260    if long && !cmd.examples.is_empty() {
261        out.push_str(&format!("\n  {}\n", s::dim("Examples:")));
262        for ex in &cmd.examples {
263            out.push_str(&format!("    {}\n", ex));
264        }
265    }
266    out.push('\n');
267    out
268}
269
270// ---------- Sections preset ----------
271
272fn app_sections(info: &AppInfo, long: bool) -> String {
273    let mut out = String::new();
274    out.push_str(&format!("{}\n\n", s::heading(info.name)));
275
276    for c in info.commands {
277        // Header line: the invocation pattern.
278        let mut pattern = format!("{}: {} {}", c.name, info.name, c.name);
279        for a in &c.args {
280            if a.required {
281                pattern.push_str(&format!(" <{}>", a.name));
282            } else {
283                pattern.push_str(&format!(" [{}]", a.name));
284            }
285        }
286        for f in &c.flags {
287            let short = f.short.map(|c| format!("-{}", c)).unwrap_or(format!("--{}", f.long));
288            if f.kind == FlagKind::Value {
289                pattern.push_str(&format!(" [{} {}]", short, f.value_name.as_deref().unwrap_or("val")));
290            } else {
291                pattern.push_str(&format!(" [{}]", short));
292            }
293        }
294        out.push_str(&format!("  {}\n", s::bold(&pattern)));
295        if !c.about.is_empty() {
296            out.push_str(&format!("           {}\n", wrap_to(&c.about, 60, "           ")));
297        }
298        out.push('\n');
299    }
300
301    if long && !info.long_about.is_empty() {
302        out.push_str(&format!("{}\n", wrap_to(info.long_about, 72, "")));
303    }
304    out
305}
306
307fn cmd_sections(app_name: &str, cmd: &Command, long: bool) -> String {
308    let mut out = String::new();
309    out.push_str(&format!("{}\n\n", s::heading(format!("{} {}", app_name, cmd.name))));
310    let about = if long && !cmd.long_about.is_empty() {
311        &cmd.long_about
312    } else {
313        &cmd.about
314    };
315    if !about.is_empty() {
316        out.push_str(&format!("{}\n\n", wrap_to(about, 72, "")));
317    }
318
319    if cmd.is_group() {
320        for c in &cmd.subcommands {
321            out.push_str(&format!(
322                "  {}\n           {}\n\n",
323                s::bold(format!("{} {} {}", app_name, cmd.name, c.name)),
324                wrap_to(&c.about, 60, "           ")
325            ));
326        }
327        return out;
328    }
329
330    out.push_str(&format!("  {}\n", s::bold(usage_line(app_name, cmd))));
331    if !cmd.flags.is_empty() {
332        out.push('\n');
333        for f in &cmd.flags {
334            out.push_str(&format!("    {:<28} {}\n", f.invocation(), f.help));
335        }
336    }
337    if long && !cmd.examples.is_empty() {
338        out.push('\n');
339        for ex in &cmd.examples {
340            out.push_str(&format!("  {} {}\n", s::dim("e.g."), ex));
341        }
342    }
343    out
344}