use crate::spec::{Command, FlagKind};
use crate::style as s;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Default)]
pub enum HelpStyle {
#[default]
Standard,
Banner,
Sections,
}
pub trait HelpRenderer: 'static {
fn app_help(&self, info: &AppInfo, long: bool) -> String;
fn command_help(&self, app_name: &str, cmd: &Command, long: bool) -> String;
}
pub struct AppInfo<'a> {
pub name: &'a str,
pub version: &'a str,
pub about: &'a str,
pub long_about: &'a str,
pub commands: &'a [Command],
pub globals: &'a [crate::spec::Flag],
}
pub fn app_help(info: &AppInfo, style: HelpStyle, long: bool) -> String {
match style {
HelpStyle::Standard => app_standard(info, long),
HelpStyle::Banner => app_banner(info, long),
HelpStyle::Sections => app_sections(info, long),
}
}
pub fn command_help(app_name: &str, cmd: &Command, style: HelpStyle, long: bool) -> String {
match style {
HelpStyle::Standard => cmd_standard(app_name, cmd, long),
HelpStyle::Banner => cmd_banner(app_name, cmd, long),
HelpStyle::Sections => cmd_sections(app_name, cmd, long),
}
}
fn usage_line(app_name: &str, cmd: &Command) -> String {
let mut u = format!("{} {}", app_name, cmd.name);
if !cmd.flags.is_empty() {
u.push_str(" [OPTIONS]");
}
for a in &cmd.args {
if a.variadic {
u.push_str(&format!(" [{}]...", a.name));
} else if a.required {
u.push_str(&format!(" <{}>", a.name));
} else {
u.push_str(&format!(" [{}]", a.name));
}
}
u
}
fn wrap_to(text: &str, width: usize, indent: &str) -> String {
let mut out = String::new();
let mut line_len = 0;
for (wi, word) in text.split_whitespace().enumerate() {
if wi != 0 && line_len + 1 + word.len() > width {
out.push('\n');
out.push_str(indent);
line_len = 0;
} else if wi != 0 {
out.push(' ');
line_len += 1;
}
out.push_str(word);
line_len += word.len();
}
out
}
fn app_standard(info: &AppInfo, long: bool) -> String {
let mut out = String::new();
let about = if long && !info.long_about.is_empty() {
info.long_about
} else {
info.about
};
if !about.is_empty() {
out.push_str(&format!("{}\n\n", about));
}
out.push_str(&format!("{} {} [COMMAND]\n\n", s::bold("Usage:"), info.name));
if !info.commands.is_empty() {
out.push_str(&format!("{}\n", s::bold("Commands:")));
let w = info.commands.iter().map(|c| c.name.len()).max().unwrap_or(0);
for c in info.commands {
out.push_str(&format!(" {:<w$} {}\n", s::cyan(&c.name), c.about, w = w));
}
out.push('\n');
}
out.push_str(&format!("{}\n", s::bold("Options:")));
for f in info.globals {
out.push_str(&format!(" {:<24} {}\n", f.invocation(), f.help));
}
out
}
fn cmd_standard(app_name: &str, cmd: &Command, long: bool) -> String {
let mut out = String::new();
let about = if long && !cmd.long_about.is_empty() {
&cmd.long_about
} else {
&cmd.about
};
if !about.is_empty() {
out.push_str(&format!("{}\n\n", about));
}
if long && !cmd.examples.is_empty() {
out.push_str(&format!("{} {}\n\n", s::bold("Examples:"), cmd.examples.join(" ")));
}
if cmd.is_group() {
out.push_str(&format!(
"{} {} {} <subcommand>\n\n",
s::bold("Usage:"),
app_name,
cmd.name
));
out.push_str(&format!("{}\n", s::bold("Commands:")));
let w = cmd.subcommands.iter().map(|c| c.name.len()).max().unwrap_or(0);
for c in &cmd.subcommands {
out.push_str(&format!(" {:<w$} {}\n", s::cyan(&c.name), c.about, w = w));
}
return out;
}
out.push_str(&format!("{} {}\n", s::bold("Usage:"), usage_line(app_name, cmd)));
if !cmd.args.is_empty() {
out.push_str(&format!("\n{}\n", s::bold("Arguments:")));
let w = cmd.args.iter().map(|a| a.name.len() + 2).max().unwrap_or(0);
for a in &cmd.args {
let token = format!("<{}>", a.name);
out.push_str(&format!(" {:<w$} {}\n", token, a.help, w = w));
}
}
out.push_str(&format!("\n{}\n", s::bold("Options:")));
if long {
for f in &cmd.flags {
out.push_str(&format!(" {}\n {}\n\n", f.invocation(), f.help));
}
out.push_str(" -h, --help\n Print help\n");
} else {
for f in &cmd.flags {
out.push_str(&format!(" {:<24} {}\n", f.invocation(), f.help));
}
out.push_str(&format!(" {:<24} Print help\n", "-h, --help"));
}
out
}
fn app_banner(info: &AppInfo, long: bool) -> String {
let mut out = String::new();
out.push('\n');
out.push_str(&format!(" {} — {}\n\n", s::heading(info.name), info.about));
for c in info.commands {
let inv = usage_line(info.name, c);
out.push_str(&format!(" {:<32} {}\n", s::bold(&inv), c.about));
}
out.push('\n');
for c in info.commands {
if c.flags.is_empty() {
continue;
}
let group: Vec<String> = c
.flags
.iter()
.map(|f| {
let short = f.short.map(|s| format!("-{}", s)).unwrap_or_default();
format!("{} {}", short, f.help)
})
.collect();
out.push_str(&format!(
" {} ({}): {}\n",
s::dim("Flags"),
c.name,
group.join(" ")
));
}
if long && !info.long_about.is_empty() {
out.push_str(&format!("\n {}\n", wrap_to(info.long_about, 70, " ")));
}
out.push('\n');
out
}
fn cmd_banner(app_name: &str, cmd: &Command, long: bool) -> String {
let mut out = String::new();
out.push('\n');
out.push_str(&format!(" {} — {}\n\n", s::heading(&cmd.name), cmd.about));
if cmd.is_group() {
for c in &cmd.subcommands {
out.push_str(&format!(
" {:<28} {}\n",
s::bold(format!("{} {} {}", app_name, cmd.name, c.name)),
c.about
));
}
out.push('\n');
return out;
}
out.push_str(&format!(" {}\n", s::bold(usage_line(app_name, cmd))));
if !cmd.flags.is_empty() {
out.push('\n');
for f in &cmd.flags {
out.push_str(&format!(" {:<28} {}\n", f.invocation(), f.help));
}
}
if long && !cmd.examples.is_empty() {
out.push_str(&format!("\n {}\n", s::dim("Examples:")));
for ex in &cmd.examples {
out.push_str(&format!(" {}\n", ex));
}
}
out.push('\n');
out
}
fn app_sections(info: &AppInfo, long: bool) -> String {
let mut out = String::new();
out.push_str(&format!("{}\n\n", s::heading(info.name)));
for c in info.commands {
let mut pattern = format!("{}: {} {}", c.name, info.name, c.name);
for a in &c.args {
if a.required {
pattern.push_str(&format!(" <{}>", a.name));
} else {
pattern.push_str(&format!(" [{}]", a.name));
}
}
for f in &c.flags {
let short = f.short.map(|c| format!("-{}", c)).unwrap_or(format!("--{}", f.long));
if f.kind == FlagKind::Value {
pattern.push_str(&format!(" [{} {}]", short, f.value_name.as_deref().unwrap_or("val")));
} else {
pattern.push_str(&format!(" [{}]", short));
}
}
out.push_str(&format!(" {}\n", s::bold(&pattern)));
if !c.about.is_empty() {
out.push_str(&format!(" {}\n", wrap_to(&c.about, 60, " ")));
}
out.push('\n');
}
if long && !info.long_about.is_empty() {
out.push_str(&format!("{}\n", wrap_to(info.long_about, 72, "")));
}
out
}
fn cmd_sections(app_name: &str, cmd: &Command, long: bool) -> String {
let mut out = String::new();
out.push_str(&format!("{}\n\n", s::heading(format!("{} {}", app_name, cmd.name))));
let about = if long && !cmd.long_about.is_empty() {
&cmd.long_about
} else {
&cmd.about
};
if !about.is_empty() {
out.push_str(&format!("{}\n\n", wrap_to(about, 72, "")));
}
if cmd.is_group() {
for c in &cmd.subcommands {
out.push_str(&format!(
" {}\n {}\n\n",
s::bold(format!("{} {} {}", app_name, cmd.name, c.name)),
wrap_to(&c.about, 60, " ")
));
}
return out;
}
out.push_str(&format!(" {}\n", s::bold(usage_line(app_name, cmd))));
if !cmd.flags.is_empty() {
out.push('\n');
for f in &cmd.flags {
out.push_str(&format!(" {:<28} {}\n", f.invocation(), f.help));
}
}
if long && !cmd.examples.is_empty() {
out.push('\n');
for ex in &cmd.examples {
out.push_str(&format!(" {} {}\n", s::dim("e.g."), ex));
}
}
out
}