1use crate::spec::{Command, FlagKind};
16use crate::style as s;
17
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22#[derive(Default)]
23pub enum HelpStyle {
24 #[default]
25 Standard,
26 Banner,
27 Sections,
28}
29
30
31pub trait HelpRenderer: 'static {
36 fn app_help(&self, info: &AppInfo, long: bool) -> String;
38 fn command_help(&self, app_name: &str, cmd: &Command, long: bool) -> String;
40}
41
42pub 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 pub globals: &'a [crate::spec::Flag],
51}
52
53pub 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
62pub 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
71fn 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
108fn 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 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
194fn 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 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
270fn 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 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}