Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -540,7 +540,10 @@ Groups are the opposite case: `Command::get_groups`, `ArgGroup::get_args` and
through KDL and the clap bridge and are honored by Rust and Go help output.
- [x] **`next_line_help`.** Command-wide block layout survives typed metadata,
KDL, the clap bridge, and both Rust and generated Go help renderers.
- [ ] **`help_template` and `flatten_help`.**
- [x] **`flatten_help`.** Visible subcommands can be expanded into their parent's
usage synopsis and help sections across typed Rust, KDL, the clap bridge,
and Rust and generated Go help.
- [ ] **`help_template`.**
- [x] **`subcommand_help_heading` / `subcommand_value_name`.** Custom subcommand
section labels and synopsis placeholders survive KDL, typed Rust, generated
Go, and the clap bridge and are rendered by both help implementations.
Expand Down
245 changes: 240 additions & 5 deletions argv/src/help.rs
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,9 @@ fn help_structure(
if !page_examples(spec, meta).is_empty() {
headings.push("Examples".to_string());
}
if meta.subcommands.iter().any(|sub| !sub.hide) {
if meta.flatten_help {
flat_help_headings(&path[1.min(path.len())..], meta, &mut headings);
} else if meta.subcommands.iter().any(|sub| !sub.hide) {
headings.push(
meta.subcommand_help_heading
.unwrap_or("Commands")
Expand Down Expand Up @@ -182,6 +184,19 @@ fn help_structure(
(headings, flag_usages, synopsis)
}

fn flat_help_headings(path: &[&str], meta: &CommandMeta<'_>, headings: &mut Vec<String>) {
let mut visible: Vec<_> = meta.subcommands.iter().filter(|sub| !sub.hide).collect();
visible.sort_by_key(|sub| sub.cmd.name);
for sub in visible {
let mut sub_path = path.to_vec();
sub_path.push(sub.cmd.name);
headings.push(sub_path.join(" "));
if sub.flatten_help {
flat_help_headings(&sub_path, sub, headings);
}
}
}

fn styled_help(
page: &str,
style: Style,
Expand Down Expand Up @@ -254,6 +269,14 @@ fn styled_help(
/// assert_eq!(usage_line(&["mise", "use"], &META), "mise use [--force] <TOOL>");
/// ```
pub fn usage_line(path: &[&str], meta: &CommandMeta<'_>) -> String {
usage_line_with_subcommands(path, meta, true)
}

fn usage_line_with_subcommands(
path: &[&str],
meta: &CommandMeta<'_>,
include_subcommands: bool,
) -> String {
let mut out = String::new();
for (i, part) in path.iter().enumerate() {
if i > 0 {
Expand Down Expand Up @@ -299,7 +322,7 @@ pub fn usage_line(path: &[&str], meta: &CommandMeta<'_>) -> String {
}
}

if !meta.cmd.subcommands.is_empty() {
if include_subcommands && !meta.cmd.subcommands.is_empty() {
let name = meta.subcommand_value_name.unwrap_or("SUBCOMMAND");
let _ = write!(out, " <{name}>");
}
Expand All @@ -317,7 +340,27 @@ fn usage_section(out: &mut String, spec: &Spec<'_>, path: &[&str], meta: &Comman
return;
}
}
let _ = writeln!(out, "Usage: {}", usage_line(path, meta));
let mut visible: Vec<_> = meta.subcommands.iter().filter(|sub| !sub.hide).collect();
visible.sort_by_key(|sub| sub.cmd.name);
if meta.flatten_help && !visible.is_empty() {
let mut lines = Vec::new();
if !meta.subcommand_required || meta.cmd.args_conflicts_with_subcommands {
lines.push(usage_line_with_subcommands(path, meta, false));
}
for sub in visible {
let mut sub_path = path.to_vec();
sub_path.push(sub.cmd.name);
lines.push(usage_line(&sub_path, sub));
}
if let Some((first, rest)) = lines.split_first() {
let _ = writeln!(out, "Usage: {first}");
for line in rest {
let _ = writeln!(out, " {line}");
}
}
} else {
let _ = writeln!(out, "Usage: {}", usage_line(path, meta));
}
}

/// How one flag appears in the usage line: `-f --force`, plus its value if it takes one.
Expand Down Expand Up @@ -615,7 +658,9 @@ pub fn short_help(spec: &Spec<'_>, path: &[&str], chain: &[&CommandMeta<'_>]) ->
// The path without the binary, which is what a listed subcommand shows: usage-lib prints
// `tool-alias get <TOOL>` under `mise tool-alias`, the whole path from the root rather
// than the child's own name.
commands_section(&mut out, &path[1.min(path.len())..], meta);
if !meta.flatten_help {
commands_section(&mut out, &path[1.min(path.len())..], meta);
}

// The short page lines its columns up too. It did not: every description began directly
// after the name it belonged to, so nothing in `-h` lined up with anything — and `-h` is
Expand Down Expand Up @@ -737,6 +782,9 @@ pub fn short_help(spec: &Spec<'_>, path: &[&str], chain: &[&CommandMeta<'_>]) ->
|_| None,
|out, (f, usage)| short_entry(out, f, usage.clone()),
);
if meta.flatten_help {
flat_commands_short(&mut out, &path[1.min(path.len())..], meta);
}
examples_section(&mut out, spec, meta);
if let Some(after) = meta.after_help.or(spec.root.after_help) {
let _ = writeln!(out, "\n{after}");
Expand Down Expand Up @@ -816,6 +864,98 @@ fn commands_section(out: &mut String, path: &[&str], meta: &CommandMeta<'_>) {
}
}

fn flat_commands_short(out: &mut String, path: &[&str], meta: &CommandMeta<'_>) {
let mut visible: Vec<_> = meta.subcommands.iter().filter(|sub| !sub.hide).collect();
visible.sort_by_key(|sub| sub.cmd.name);
for sub in visible {
let mut sub_path = path.to_vec();
sub_path.push(sub.cmd.name);
let _ = writeln!(out, "\n{}:", sub_path.join(" "));
if let Some(about) = sub.about.filter(|about| !about.trim().is_empty()) {
let _ = writeln!(out, "{}", about.trim_end());
}

let args: Vec<_> = sub
.args
.iter()
.filter(|arg| !arg.hide && !arg.hide_short_help)
.collect();
let flags: Vec<&FlagMeta<'_>> = sub
.flags
.iter()
.filter(|flag| !flag.flag.global && !flag.hide && !flag.hide_short_help)
.collect();
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
let arg_col = args
.iter()
.map(|arg| arg_usage(arg).chars().count())
.max()
.unwrap_or(0);
let flag_col = flags
.iter()
.map(|flag| column_usage(flag).chars().count())
.max()
.unwrap_or(0);
Comment thread
jdx marked this conversation as resolved.
Resolved
for arg in args {
let usage = arg_usage(arg);
if let Some(help) = arg.help.filter(|help| !help.trim().is_empty()) {
if meta.next_line_help {
let _ = writeln!(out, " {usage}");
write_indented(out, help, 4);
} else {
let _ = write!(out, " {usage:<arg_col$} {help}");
}
} else {
let _ = write!(out, " {usage}");
}
annotations(
out,
if arg.hide_possible_values {
&[]
} else {
arg.choices
},
if arg.hide_env { None } else { arg.env },
if arg.hide_default_value {
&[]
} else {
arg.default
},
);
}
for flag in flags {
let usage = column_usage(flag);
if let Some(help) = flag.help.filter(|help| !help.trim().is_empty()) {
if meta.next_line_help {
let _ = writeln!(out, " {usage}");
write_indented(out, help, 4);
} else {
let _ = write!(out, " {usage:<flag_col$} {help}");
}
} else {
let _ = write!(out, " {usage}");
}
annotations(
out,
if flag.hide_possible_values {
&[]
} else {
flag.choices
},
if flag.hide_env { None } else { flag.env },
if flag.hide_default_value {
&[]
} else {
flag.default
},
);
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
}
if sub.flatten_help {
flat_commands_short(out, &sub_path, sub);
}
out.push('\n');
}
}

/// One section per heading, unheaded first, in the order the headings first appear.
fn groups_section<'m, T: 'm>(
out: &mut String,
Expand Down Expand Up @@ -1044,7 +1184,9 @@ pub fn long_help(spec: &Spec<'_>, path: &[&str], chain: &[&CommandMeta<'_>]) ->
}
usage_section(&mut out, spec, path, meta);

long_commands_section(&mut out, &path[1.min(path.len())..], meta);
if !meta.flatten_help {
long_commands_section(&mut out, &path[1.min(path.len())..], meta);
}

// One column width per section, over its visible entries — the same two the reference
// computes, and separately, so a long flag does not push the arguments out.
Expand Down Expand Up @@ -1145,6 +1287,9 @@ pub fn long_help(spec: &Spec<'_>, path: &[&str], chain: &[&CommandMeta<'_>]) ->
);
},
);
if meta.flatten_help {
flat_commands_long(&mut out, &path[1.min(path.len())..], meta, width);
}

let examples = page_examples(spec, meta);
if !examples.is_empty() {
Expand Down Expand Up @@ -1332,6 +1477,96 @@ fn long_commands_section(out: &mut String, path: &[&str], meta: &CommandMeta<'_>
);
}

fn flat_commands_long(out: &mut String, path: &[&str], meta: &CommandMeta<'_>, width: usize) {
let mut visible: Vec<_> = meta.subcommands.iter().filter(|sub| !sub.hide).collect();
visible.sort_by_key(|sub| sub.cmd.name);
for sub in visible {
let mut sub_path = path.to_vec();
sub_path.push(sub.cmd.name);
let _ = writeln!(out, "\n{}:", sub_path.join(" "));
if let Some(about) = sub
.long_about
.or(sub.about)
.filter(|about| !about.trim().is_empty())
{
let _ = writeln!(out, "{}", about.trim_end());
}

let args: Vec<_> = sub
.args
.iter()
.filter(|arg| !arg.hide && !arg.hide_long_help)
.collect();
let flags: Vec<&FlagMeta<'_>> = sub
.flags
.iter()
.filter(|flag| !flag.flag.global && !flag.hide && !flag.hide_long_help)
.collect();
let arg_col = args
.iter()
.map(|arg| arg_usage(arg).chars().count())
.max()
.unwrap_or(0);
let flag_col = flags
.iter()
.map(|flag| column_usage(flag).chars().count())
.max()
.unwrap_or(0);
for arg in args {
entry(
out,
&arg_usage(arg),
arg.long_help.or(arg.help),
arg_col,
width,
meta.next_line_help,
);
long_annotations(
out,
if arg.hide_possible_values {
&[]
} else {
arg.choices
},
if arg.hide_env { None } else { arg.env },
if arg.hide_default_value {
&[]
} else {
arg.default
},
);
}
for flag in flags {
entry(
out,
&column_usage(flag),
flag.long_help.or(flag.help),
flag_col,
width,
meta.next_line_help,
);
long_annotations(
out,
if flag.hide_possible_values {
&[]
} else {
flag.choices
},
if flag.hide_env { None } else { flag.env },
if flag.hide_default_value {
&[]
} else {
flag.default
},
);
}
if sub.flatten_help {
flat_commands_long(out, &sub_path, sub, width);
}
out.push('\n');
}
}

/// The path and metadata for a command, found by identity within a spec.
///
/// [`Error::Help`](crate::Error::Help) carries the `Command` the request was about, because the
Expand Down
9 changes: 9 additions & 0 deletions argv/src/spec.rs
Original file line number Diff line number Diff line change
Expand Up @@ -726,6 +726,8 @@ pub struct CommandMeta<'a> {
pub subcommand_value_name: Option<&'a str>,
/// Put each argument, flag, and subcommand description on the following line.
pub next_line_help: bool,
/// Expand each visible subcommand's summary and arguments into this command's help page.
pub flatten_help: bool,
/// Fixed help width. Zero disables wrapping.
pub term_width: Option<usize>,
/// Maximum detected terminal width when `term_width` is unset. Zero disables the cap.
Expand Down Expand Up @@ -770,6 +772,7 @@ impl CommandMeta<'_> {
subcommand_help_heading: None,
subcommand_value_name: None,
next_line_help: false,
flatten_help: false,
term_width: None,
max_term_width: None,
args_override_self: true,
Expand Down Expand Up @@ -1221,6 +1224,9 @@ impl Spec<'_> {
if self.root.next_line_help {
writeln!(out, "next_line_help #true")?;
}
if self.root.flatten_help {
writeln!(out, "flatten_help #true")?;
}
if let Some(width) = self.root.term_width {
writeln!(out, "term_width {width}")?;
}
Expand Down Expand Up @@ -1473,6 +1479,9 @@ fn write_command<'a>(
if meta.next_line_help {
out.push_str(" next_line_help=#true");
}
if meta.flatten_help {
out.push_str(" flatten_help=#true");
}
if let Some(width) = meta.term_width {
write!(out, " term_width={width}")?;
}
Expand Down
7 changes: 0 additions & 7 deletions clap_usage/src/report.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@ pub enum FidelityFeature {
NonUtf8Default,
ValueArity,
DistinctValueNames,
FlattenHelp,
NextLineHelp,
DisableHelpFlag,
DisableHelpSubcommand,
DisableVersionFlag,
Expand Down Expand Up @@ -75,11 +73,6 @@ fn visit(cmd: &Command, ancestors: &[String], losses: &mut BTreeSet<FidelityLoss
}
};

command_loss(
cmd.is_flatten_help_set(),
FidelityFeature::FlattenHelp,
"flatten_help",
);
command_loss(
cmd.is_disable_help_flag_set(),
FidelityFeature::DisableHelpFlag,
Expand Down
Loading