From a55db4375856321a5272dd751d7a8c3d98b6acc8 Mon Sep 17 00:00:00 2001 From: Tyler Calder Date: Tue, 23 Aug 2022 20:09:16 -0600 Subject: [PATCH] fix: Add possible vals to man for positional args Noticed that possible values would not show up for Positional arguments as well. Decided to add the changes for those as well. --- clap_mangen/src/render.rs | 87 +++++++++++++------ clap_mangen/tests/common.rs | 28 ++++-- .../tests/snapshots/feature_sample.bash.roff | 2 + .../tests/snapshots/possible_values.bash.roff | 17 +++- .../snapshots/special_commands.bash.roff | 2 + .../tests/snapshots/sub_subcommands.bash.roff | 2 + .../tests/snapshots/value_hint.bash.roff | 2 +- 7 files changed, 101 insertions(+), 39 deletions(-) diff --git a/clap_mangen/src/render.rs b/clap_mangen/src/render.rs index 1cd81485..0548cef4 100644 --- a/clap_mangen/src/render.rs +++ b/clap_mangen/src/render.rs @@ -1,5 +1,3 @@ -use std::vec; - use roff::{bold, italic, roman, Inline, Roff}; pub(crate) fn subcommand_heading(cmd: &clap::Command) -> &str { @@ -109,9 +107,9 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) { } let mut body = vec![]; - let mut help_written = false; + let mut arg_help_written = false; if let Some(help) = opt.get_long_help().or_else(|| opt.get_help()) { - help_written = true; + arg_help_written = true; body.push(roman(help)); } @@ -119,39 +117,29 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) { roff.text(header); roff.text(body); - let possibles = &opt.get_possible_values(); - let possibles: Vec<&clap::builder::PossibleValue> = - possibles.iter().filter(|pos| !pos.is_hide_set()).collect(); - - if !(possibles.is_empty() || opt.is_hide_possible_values_set()) { - if help_written { + if let Some((possible_values_text, with_help)) = get_possible_values(opt) { + if arg_help_written { // It looks nice to have a separation between the help and the values roff.text([Inline::LineBreak]); } - // with help for each possible value - - if possibles.iter().any(|p| p.get_help().is_some()) { + if with_help { roff.text([Inline::LineBreak, italic("Possible values:")]); - // Need to indent twice to get it to look right, - // because .TP heading indents, but that indent doesn't - // Carry over to the .IP for the bullets. - // The standard shift size is 7 for terminal devices + // Need to indent twice to get it to look right, because .TP heading indents, but + // that indent doesn't Carry over to the .IP for the bullets. The standard shift + // size is 7 for terminal devices roff.control("RS", ["14"]); - for line in format_possible_values(&possibles) { + for line in possible_values_text { roff.control("IP", ["\\(bu", "2"]); roff.text([roman(line)]); } roff.control("RE", []); - } - - // without help for each possible value - else { - let possible_list = format_possible_values(&possibles); + } else { let possible_value_text: Vec = vec![ Inline::LineBreak, - italic("[possible values: "), - roman(possible_list.join(", ")), + roman("["), + italic("possible values: "), + roman(possible_values_text.join(", ")), roman("]"), ]; roff.text(possible_value_text); @@ -181,8 +169,10 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) { } let mut body = vec![]; + let mut arg_help_written = false; if let Some(help) = pos.get_long_help().or_else(|| pos.get_help()) { body.push(roman(&help.to_string())); + arg_help_written = true; } roff.control("TP", []); @@ -194,6 +184,35 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) { roff.text(env); roff.control("RE", []); } + // If possible options are available + if let Some((possible_values_text, with_help)) = get_possible_values(pos) { + if arg_help_written { + // It looks nice to have a separation between the help and the values + roff.text([Inline::LineBreak]); + } + if with_help { + roff.text([Inline::LineBreak, italic("Possible values:")]); + + // Need to indent twice to get it to look right, because .TP heading indents, but + // that indent doesn't Carry over to the .IP for the bullets. The standard shift + // size is 7 for terminal devices + roff.control("RS", ["14"]); + for line in possible_values_text { + roff.control("IP", ["\\(bu", "2"]); + roff.text([roman(line)]); + } + roff.control("RE", []); + } else { + let possible_value_text: Vec = vec![ + Inline::LineBreak, + roman("["), + italic("possible values: "), + roman(possible_values_text.join(", ")), + roman("]"), + ]; + roff.text(possible_value_text); + } + } } } @@ -282,9 +301,21 @@ fn option_default_values(opt: &clap::Arg) -> Option { None } -fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> Vec { +fn get_possible_values(arg: &clap::Arg) -> Option<(Vec, bool)> { + let possibles = &arg.get_possible_values(); + let possibles: Vec<&clap::builder::PossibleValue> = + possibles.iter().filter(|pos| !pos.is_hide_set()).collect(); + + if !(possibles.is_empty() || arg.is_hide_possible_values_set()) { + return Some(format_possible_values(&possibles)); + } + None +} + +fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> (Vec, bool) { let mut lines = vec![]; - if possibles.iter().any(|p| p.get_help().is_some()) { + let with_help = possibles.iter().any(|p| p.get_help().is_some()); + if with_help { for value in possibles { let val_name = value.get_name(); match value.get_help() { @@ -295,5 +326,5 @@ fn format_possible_values(possibles: &Vec<&clap::builder::PossibleValue>) -> Vec } else { lines.append(&mut possibles.iter().map(|p| p.get_name().to_string()).collect()); } - lines + (lines, with_help) } diff --git a/clap_mangen/tests/common.rs b/clap_mangen/tests/common.rs index 5cafbfc2..96b8e917 100644 --- a/clap_mangen/tests/common.rs +++ b/clap_mangen/tests/common.rs @@ -281,7 +281,7 @@ pub fn assert_matches_path(expected_path: impl AsRef, cmd: clap .matches_path(expected_path, buf); } -pub fn possible_values_command(name: &'static str) -> clap::Command<'static> { +pub fn possible_values_command(name: &'static str) -> clap::Command { clap::Command::new(name) .trailing_var_arg(true) .arg( @@ -292,12 +292,24 @@ pub fn possible_values_command(name: &'static str) -> clap::Command<'static> { ) .arg( clap::Arg::new("method") - .long("method") - .action(clap::ArgAction::Set) - .value_parser([ - PossibleValue::new("fast").help("use the Fast method"), - PossibleValue::new("slow").help("use the slow method"), - PossibleValue::new("normal").help("use normal mode").hide(true) - ]) + .long("method") + .action(clap::ArgAction::Set) + .value_parser([ + PossibleValue::new("fast").help("use the Fast method"), + PossibleValue::new("slow").help("use the slow method"), + PossibleValue::new("normal") + .help("use normal mode") + .hide(true), + ]), + ) + .arg( + clap::Arg::new("positional_choice") + .action(clap::ArgAction::Set) + .help("Pick the Position you want the command to run in") + .value_parser([ + PossibleValue::new("left").help("run left adjusted"), + PossibleValue::new("right"), + PossibleValue::new("center").hide(true), + ]), ) } diff --git a/clap_mangen/tests/snapshots/feature_sample.bash.roff b/clap_mangen/tests/snapshots/feature_sample.bash.roff index e6dc8818..ad89abed 100644 --- a/clap_mangen/tests/snapshots/feature_sample.bash.roff +++ b/clap_mangen/tests/snapshots/feature_sample.bash.roff @@ -23,6 +23,8 @@ some input file .TP [/fIchoice/fR] +.br +[/fIpossible values: /fRfirst, second] .SH SUBCOMMANDS .TP my/-app/-test(1) diff --git a/clap_mangen/tests/snapshots/possible_values.bash.roff b/clap_mangen/tests/snapshots/possible_values.bash.roff index 76f690a1..10f9af3d 100644 --- a/clap_mangen/tests/snapshots/possible_values.bash.roff +++ b/clap_mangen/tests/snapshots/possible_values.bash.roff @@ -4,14 +4,14 @@ .SH NAME my/-app .SH SYNOPSIS -/fBmy/-app/fR [/fB/-/-choice/fR] [/fB/-/-method/fR] [/fB/-h/fR|/fB/-/-help/fR] +/fBmy/-app/fR [/fB/-/-choice/fR] [/fB/-/-method/fR] [/fB/-h/fR|/fB/-/-help/fR] [/fIpositional_choice/fR] .SH DESCRIPTION .SH OPTIONS .TP /fB/-/-choice/fR .br -/fI[possible values: /fRbash, fish, zsh] +[/fIpossible values: /fRbash, fish, zsh] .TP /fB/-/-method/fR @@ -26,3 +26,16 @@ slow: use the slow method .TP /fB/-h/fR, /fB/-/-help/fR Print help information +.TP +[/fIpositional_choice/fR] +Pick the Position you want the command to run in +.br + +.br +/fIPossible values:/fR +.RS 14 +.IP /(bu 2 +left: run left adjusted +.IP /(bu 2 +right +.RE diff --git a/clap_mangen/tests/snapshots/special_commands.bash.roff b/clap_mangen/tests/snapshots/special_commands.bash.roff index f5b2f059..0cf113f8 100644 --- a/clap_mangen/tests/snapshots/special_commands.bash.roff +++ b/clap_mangen/tests/snapshots/special_commands.bash.roff @@ -23,6 +23,8 @@ some input file .TP [/fIchoice/fR] +.br +[/fIpossible values: /fRfirst, second] .SH SUBCOMMANDS .TP my/-app/-test(1) diff --git a/clap_mangen/tests/snapshots/sub_subcommands.bash.roff b/clap_mangen/tests/snapshots/sub_subcommands.bash.roff index a1a713aa..f2a22e9d 100644 --- a/clap_mangen/tests/snapshots/sub_subcommands.bash.roff +++ b/clap_mangen/tests/snapshots/sub_subcommands.bash.roff @@ -23,6 +23,8 @@ some input file .TP [/fIchoice/fR] +.br +[/fIpossible values: /fRfirst, second] .SH SUBCOMMANDS .TP my/-app/-test(1) diff --git a/clap_mangen/tests/snapshots/value_hint.bash.roff b/clap_mangen/tests/snapshots/value_hint.bash.roff index 94e76c20..2b9ad889 100644 --- a/clap_mangen/tests/snapshots/value_hint.bash.roff +++ b/clap_mangen/tests/snapshots/value_hint.bash.roff @@ -11,7 +11,7 @@ my/-app /fB/-/-choice/fR .br -/fI[possible values: /fRbash, fish, zsh] +[/fIpossible values: /fRbash, fish, zsh] .TP /fB/-/-unknown/fR