Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-12 13:52:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

fix(help): Consistently use [] for positionals

Browse source 
In the usaeg we use `[]` but in the arg list we use `<>`.
This commit is contained in:
Ed Page 2022-08-29 15:09:06 -05:00
parent 29238551ab
commit 02db3043e2
34 changed files with 122 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
clap_complete/tests/snapshots/aliases.bash
View file

@ -19,7 +19,7 @@ _my-app() {
case "${cmd}" in
my__app)
opts="-F -f -O -o -h -V --flg --flag --opt --option --help --version <positional>"
opts="-F -f -O -o -h -V --flg --flag --opt --option --help --version [positional]"
if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
return 0

2
clap_complete/tests/snapshots/feature_sample.bash
View file

@ -25,7 +25,7 @@ _my-app() {
case "${cmd}" in
my__app)
opts="-C -c -h -V --conf --config --help --version <file> first second test help"
opts="-C -c -h -V --conf --config --help --version [file] first second test help"
if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
return 0

4
clap_complete/tests/snapshots/special_commands.bash
View file

@ -34,7 +34,7 @@ _my-app() {
case "${cmd}" in
my__app)
opts="-C -c -h -V --conf --config --help --version <file> first second test some_cmd some-cmd-with-hyphens some-hidden-cmd help"
opts="-C -c -h -V --conf --config --help --version [file] first second test some_cmd some-cmd-with-hyphens some-hidden-cmd help"
if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
return 0
@ -160,7 +160,7 @@ _my-app() {
return 0
;;
my__app__some_cmd)
opts="-h -V --config --help --version <path>..."
opts="-h -V --config --help --version [path]..."
if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
return 0

2
clap_complete/tests/snapshots/sub_subcommands.bash
View file

@ -31,7 +31,7 @@ _my-app() {
case "${cmd}" in
my__app)
opts="-C -c -h -V --conf --config --help --version <file> first second test some_cmd help"
opts="-C -c -h -V --conf --config --help --version [file] first second test some_cmd help"
if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
return 0

2
clap_complete/tests/snapshots/value_hint.bash
View file

@ -19,7 +19,7 @@ _my-app() {
case "${cmd}" in
my__app)
opts="-p -f -d -e -c -u -H -h --choice --unknown --other --path --file --dir --exe --cmd-name --cmd --user --host --url --email --help <command_with_args>..."
opts="-p -f -d -e -c -u -H -h --choice --unknown --other --path --file --dir --exe --cmd-name --cmd --user --host --url --email --help [command_with_args]..."
if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
return 0

2
examples/escaped-positional-derive.md
View file

@ -12,7 +12,7 @@ Usage:
escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
Arguments:
<SLOP>...
[SLOP]...
Options:
-f

2
examples/escaped-positional.md
View file

@ -12,7 +12,7 @@ Usage:
escaped-positional[EXE] [OPTIONS] [-- <SLOP>...]
Arguments:
<SLOP>...
[SLOP]...
Options:
-f

2
examples/git-derive.md
View file

@ -111,7 +111,7 @@ Usage:
git-derive[EXE] stash pop [STASH]
Arguments:
<STASH>
[STASH]
Options:
-h, --help Print help information

2
examples/git.md
View file

@ -109,7 +109,7 @@ Usage:
git[EXE] stash pop [STASH]
Arguments:
<STASH>
[STASH]
Options:
-h, --help Print help information

2
examples/pacman.md
View file

@ -59,7 +59,7 @@ Usage:
pacman[EXE] {sync|--sync|-S} [OPTIONS] [--] [package]...
Arguments:
<package>... packages
[package]... packages
Options:
-s, --search <search>... search remote repositories for matching strings

2
examples/tutorial_builder/01_quick.md
View file

@ -11,7 +11,7 @@ Subcommands:
help Print this message or the help of the given subcommand(s)
Arguments:
<name> Optional name to operate on
[name] Optional name to operate on
Options:
-c, --config <FILE> Sets a custom config file

2
examples/tutorial_builder/03_03_positional.md
View file

@ -7,7 +7,7 @@ Usage:
03_03_positional[EXE] [name]
Arguments:
<name>
[name]
Options:
-h, --help Print help information

2
examples/tutorial_builder/03_03_positional_mult.md
View file

@ -7,7 +7,7 @@ Usage:
03_03_positional_mult[EXE] [name]...
Arguments:
<name>...
[name]...
Options:
-h, --help Print help information

2
examples/tutorial_builder/03_04_subcommands.md
View file

@ -22,7 +22,7 @@ Usage:
03_04_subcommands[EXE] add [NAME]
Arguments:
<NAME>
[NAME]
Options:
-h, --help Print help information

2
examples/tutorial_builder/03_05_default_values.md
View file

@ -7,7 +7,7 @@ Usage:
03_05_default_values[EXE] [NAME]
Arguments:
<NAME> [default: alice]
[NAME] [default: alice]
Options:
-h, --help Print help information

2
examples/tutorial_builder/04_03_relations.md
View file

@ -7,7 +7,7 @@ Usage:
04_03_relations[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
Arguments:
<INPUT_FILE> some regular input
[INPUT_FILE] some regular input
Options:
--set-ver <VER> set version manually

2
examples/tutorial_builder/04_04_custom.md
View file

@ -7,7 +7,7 @@ Usage:
04_04_custom[EXE] [OPTIONS] [INPUT_FILE]
Arguments:
<INPUT_FILE> some regular input
[INPUT_FILE] some regular input
Options:
--set-ver <VER> set version manually

2
examples/tutorial_derive/01_quick.md
View file

@ -11,7 +11,7 @@ Subcommands:
help Print this message or the help of the given subcommand(s)
Arguments:
<NAME> Optional name to operate on
[NAME] Optional name to operate on
Options:
-c, --config <FILE> Sets a custom config file

2
examples/tutorial_derive/03_03_positional.md
View file

@ -7,7 +7,7 @@ Usage:
03_03_positional_derive[EXE] [NAME]
Arguments:
<NAME>
[NAME]
Options:
-h, --help Print help information

2
examples/tutorial_derive/03_03_positional_mult.md
View file

@ -7,7 +7,7 @@ Usage:
03_03_positional_mult_derive[EXE] [NAME]...
Arguments:
<NAME>...
[NAME]...
Options:
-h, --help Print help information

2
examples/tutorial_derive/03_04_subcommands.md
View file

@ -22,7 +22,7 @@ Usage:
03_04_subcommands_derive[EXE] add [NAME]
Arguments:
<NAME>
[NAME]
Options:
-h, --help Print help information

2
examples/tutorial_derive/03_05_default_values.md
View file

@ -7,7 +7,7 @@ Usage:
03_05_default_values_derive[EXE] [NAME]
Arguments:
<NAME> [default: alice]
[NAME] [default: alice]
Options:
-h, --help Print help information

2
examples/tutorial_derive/04_03_relations.md
View file

@ -7,7 +7,7 @@ Usage:
04_03_relations_derive[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
Arguments:
<INPUT_FILE> some regular input
[INPUT_FILE] some regular input
Options:
--set-ver <VER> set version manually

2
examples/tutorial_derive/04_04_custom.md
View file

@ -7,7 +7,7 @@ Usage:
04_04_custom_derive[EXE] [OPTIONS] [INPUT_FILE]
Arguments:
<INPUT_FILE> some regular input
[INPUT_FILE] some regular input
Options:
--set-ver <VER> set version manually

53
src/builder/arg.rs
View file

@ -3970,7 +3970,7 @@ impl Arg {
}
}
pub(crate) fn stylized(&self) -> StyledStr {
pub(crate) fn stylized(&self, required: Option<bool>) -> StyledStr {
let mut styled = StyledStr::new();
// Write the name such --long or -l
if let Some(l) = self.get_long() {
@ -3980,11 +3980,11 @@ impl Arg {
styled.literal("-");
styled.literal(s);
}
styled.extend(self.stylize_arg_suffix().into_iter());
styled.extend(self.stylize_arg_suffix(required).into_iter());
styled
}
pub(crate) fn stylize_arg_suffix(&self) -> StyledStr {
pub(crate) fn stylize_arg_suffix(&self, required: Option<bool>) -> StyledStr {
let mut styled = StyledStr::new();
let mut need_closing_bracket = false;
@ -4005,7 +4005,8 @@ impl Arg {
}
}
if self.is_takes_value_set() || self.is_positional() {
let arg_val = self.render_arg_val();
let required = required.unwrap_or_else(|| self.is_required_set());
let arg_val = self.render_arg_val(required);
styled.placeholder(arg_val);
} else if matches!(*self.get_action(), ArgAction::Count) {
styled.placeholder("...");
@ -4018,7 +4019,7 @@ impl Arg {
}
/// Write the values such as <name1> <name2>
fn render_arg_val(&self) -> String {
fn render_arg_val(&self, required: bool) -> String {
let mut rendered = String::new();
let num_vals = self.get_num_args().expect(INTERNAL_ERROR_MSG);
@ -4036,7 +4037,7 @@ impl Arg {
debug_assert!(self.is_takes_value_set());
for (n, val_name) in val_names.iter().enumerate() {
let arg_name = if self.is_positional() && num_vals.min_values() == 0 {
let arg_name = if self.is_positional() && (num_vals.min_values() == 0 || !required) {
format!("[{}]", val_name)
} else {
format!("<{}>", val_name)
@ -4098,7 +4099,7 @@ impl Eq for Arg {}
impl Display for Arg {
fn fmt(&self, f: &mut Formatter) -> fmt::Result {
self.stylized().fmt(f)
self.stylized(None).fmt(f)
}
}
@ -4372,6 +4373,14 @@ mod test {
let mut p = Arg::new("pos").index(1).num_args(1..);
p._build();
assert_eq!(p.to_string(), "[pos]...");
}
#[test]
fn positional_display_multiple_values_required() {
let mut p = Arg::new("pos").index(1).num_args(1..).required(true);
p._build();
assert_eq!(p.to_string(), "<pos>...");
}
@ -4388,6 +4397,14 @@ mod test {
let mut p = Arg::new("pos").index(1).num_args(1..);
p._build();
assert_eq!(p.to_string(), "[pos]...");
}
#[test]
fn positional_display_one_or_more_values_required() {
let mut p = Arg::new("pos").index(1).num_args(1..).required(true);
p._build();
assert_eq!(p.to_string(), "<pos>...");
}
@ -4407,6 +4424,17 @@ mod test {
let mut p = Arg::new("pos").index(1).action(ArgAction::Append);
p._build();
assert_eq!(p.to_string(), "[pos]...");
}
#[test]
fn positional_display_multiple_occurrences_required() {
let mut p = Arg::new("pos")
.index(1)
.action(ArgAction::Append)
.required(true);
p._build();
assert_eq!(p.to_string(), "<pos>...");
}
@ -4423,6 +4451,17 @@ mod test {
let mut p = Arg::new("pos").index(1).value_names(["file1", "file2"]);
p._build();
assert_eq!(p.to_string(), "[file1] [file2]");
}
#[test]
fn positional_display_val_names_required() {
let mut p = Arg::new("pos")
.index(1)
.value_names(["file1", "file2"])
.required(true);
p._build();
assert_eq!(p.to_string(), "<file1> <file2>");
}

2
src/output/help.rs
View file

@ -447,7 +447,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
self.none(TAB);
self.short(arg);
self.long(arg);
self.writer.extend(arg.stylize_arg_suffix().into_iter());
self.writer.extend(arg.stylize_arg_suffix(None).into_iter());
self.align_to_about(arg, next_line_help, longest);
let about = if self.use_long {

7
src/output/usage.rs
View file

@ -418,10 +418,11 @@ impl<'cmd> Usage<'cmd> {
if !is_present {
if arg.is_positional() {
if incl_last || !arg.is_last_set() {
required_positionals.insert((arg.index.unwrap(), arg.stylized()));
required_positionals
.insert((arg.index.unwrap(), arg.stylized(Some(true))));
}
} else {
required_opts.insert(arg.stylized());
required_opts.insert(arg.stylized(Some(true)));
}
}
} else {
@ -445,7 +446,7 @@ impl<'cmd> Usage<'cmd> {
group_members
.iter()
.flat_map(|id| self.cmd.find(id))
.map(|arg| arg.stylized()),
.map(|arg| arg.stylized(Some(true))),
);
}
}

8
tests/builder/app_settings.rs
View file

@ -20,9 +20,9 @@ Usage:
clap-test [arg1] [arg2] [arg3]
Arguments:
<arg1> some
<arg2> some
<arg3> some
[arg1] some
[arg2] some
[arg3] some
Options:
-h, --help Print help information
@ -292,7 +292,7 @@ Usage:
test [OPTIONS] [arg1]
Arguments:
<arg1> some pos arg
[arg1] some pos arg
Options:
-o, --opt <opt> some option

4
tests/builder/default_missing_vals.rs
View file

@ -260,7 +260,7 @@ fn delimited_missing_value() {
#[cfg(debug_assertions)]
#[test]
#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: \"value\" isn't a valid value for '<arg>'"]
#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: \"value\" isn't a valid value for '[arg]'"]
fn default_missing_values_are_possible_values() {
use clap::{Arg, Command};
@ -275,7 +275,7 @@ fn default_missing_values_are_possible_values() {
#[cfg(debug_assertions)]
#[test]
#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: Invalid value \"value\" for '<arg>"]
#[should_panic = "Argument `arg`'s default_missing_value=\"value\" failed validation: error: Invalid value \"value\" for '[arg]"]
fn default_missing_values_are_valid() {
use clap::{Arg, Command};

6
tests/builder/default_vals.rs
View file

@ -794,7 +794,7 @@ fn required_args_with_default_values() {
#[cfg(debug_assertions)]
#[test]
#[should_panic = "Argument `arg`'s default_value=\"value\" failed validation: error: \"value\" isn't a valid value for '<arg>'"]
#[should_panic = "Argument `arg`'s default_value=\"value\" failed validation: error: \"value\" isn't a valid value for '[arg]'"]
fn default_values_are_possible_values() {
use clap::{Arg, Command};
@ -809,7 +809,7 @@ fn default_values_are_possible_values() {
#[cfg(debug_assertions)]
#[test]
#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '<arg>"]
#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '[arg]"]
fn invalid_default_values() {
use clap::{Arg, Command};
@ -838,7 +838,7 @@ fn valid_delimited_default_values() {
#[cfg(debug_assertions)]
#[test]
#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '<arg>"]
#[should_panic = "Argument `arg`'s default_value=\"one\" failed validation: error: Invalid value \"one\" for '[arg]"]
fn invalid_delimited_default_values() {
use clap::{Arg, Command};

4
tests/builder/groups.rs
View file

@ -12,7 +12,7 @@ For more information try --help
";
static REQ_GROUP_CONFLICT_USAGE: &str =
"error: The argument '--delete' cannot be used with '<base>'
"error: The argument '--delete' cannot be used with '[base]'
Usage:
clap-test <base|--delete>
@ -267,7 +267,7 @@ Usage:
prog <A>
Arguments:
<A>
[A]
Options:
-h, --help Print help information

62
tests/builder/help.rs
View file

@ -123,8 +123,8 @@ Usage:
flamegraph [OPTIONS] [BINFILE] [-- <ARGS>...]
Arguments:
<BINFILE> The path of the binary to be profiled. for a binary.
<ARGS>... Any arguments you wish to pass to the being profiled.
[BINFILE] The path of the binary to be profiled. for a binary.
[ARGS]... Any arguments you wish to pass to the being profiled.
Options:
-v, --verbose Prints out more stuff.
@ -212,9 +212,9 @@ Subcommands:
help Print this message or the help of the given subcommand(s)
Arguments:
<positional> tests positionals
<positional2> tests positionals with exclusions
<positional3>... tests specific values [possible values: vi, emacs]
[positional] tests positionals
[positional2] tests positionals with exclusions
[positional3]... tests specific values [possible values: vi, emacs]
Options:
-o, --option <opt>... tests options
@ -549,7 +549,7 @@ Usage:
clap-test subcmd [OPTIONS] [--] [scpositional]
Arguments:
<scpositional> tests positionals
[scpositional] tests positionals
Options:
-o, --option <scoption>... tests options
@ -801,7 +801,7 @@ Usage:
ctest [mode]
Arguments:
<mode> x, max, maximum 20 characters, contains
[mode] x, max, maximum 20 characters, contains
symbols.
l, long Copy-friendly, 14
characters, contains symbols.
@ -965,8 +965,8 @@ Usage:
myapp [OPTIONS] [--] [ARGS]
Arguments:
<arg1> some option
<arg2>... some option
[arg1] some option
[arg2]... some option
Options:
-s, --some <some> some option
@ -1024,7 +1024,7 @@ Usage:
myapp [arg1]
Arguments:
<arg1>
[arg1]
some option
Options:
@ -1108,7 +1108,7 @@ Subcommands:
help Print this message or the help of the given subcommand(s)
Arguments:
<PATH> help
[PATH] help
Options:
-o, --opt <FILE> tests options
@ -1160,7 +1160,7 @@ Subcommands:
help Print this message or the help of the given subcommand(s)
Arguments:
<PATH> help
[PATH] help
Options:
-f, --flag testing flags
@ -1187,7 +1187,7 @@ Usage:
prog [OPTIONS] [PATH]
Arguments:
<PATH> some
[PATH] some
Options:
-f, --flag testing flags
@ -1337,8 +1337,8 @@ Usage:
Arguments:
<TARGET> some
<CORPUS> some
<ARGS>... some
[CORPUS] some
[ARGS]... some
Options:
-h, --help Print help information
@ -1368,7 +1368,7 @@ Usage:
Arguments:
<TARGET> some
<CORPUS> some
[CORPUS] some
<ARGS>... some
Options:
@ -1405,7 +1405,7 @@ Subcommands:
Arguments:
<TARGET> some
<CORPUS> some
[CORPUS] some
<ARGS>... some
Options:
@ -1444,8 +1444,8 @@ Subcommands:
Arguments:
<TARGET> some
<CORPUS> some
<ARGS>... some
[CORPUS] some
[ARGS]... some
Options:
-h, --help Print help information
@ -1851,7 +1851,7 @@ Usage:
demo [OPTIONS] [FILES]...
Arguments:
<FILES>...
[FILES]...
Options:
-f
@ -1885,8 +1885,8 @@ Usage:
ctest <arg1|arg2>
Arguments:
<arg1>
<arg2>
[arg1]
[arg2]
Options:
-h, --help Print help information
@ -2274,8 +2274,8 @@ Usage:
deno <pos1|--option1> [pos2]
Arguments:
<pos1>
<pos2>
[pos1]
[pos2]
Options:
--option1
@ -2306,14 +2306,14 @@ Usage:
test [ARGS]
Arguments:
<gear> Which gear
[gear] Which gear
Options:
-h, --help Print help information
-V, --version Print version information
NETWORKING:
<speed> How fast
[speed] How fast
";
#[test]
@ -2355,7 +2355,7 @@ Usage:
test [speed]
NETWORKING:
<speed> How fast
[speed] How fast
";
#[test]
@ -2413,7 +2413,7 @@ Usage:
test [arg1] <arg2>
Arguments:
<arg1>
[arg1]
<arg2>
Options:
@ -2439,9 +2439,9 @@ Usage:
test [ARGS]
Arguments:
<foo>
<bar>
<baz>...
[foo]
[bar]
[baz]...
Options:
-h, --help Print help information

2
tests/builder/hidden_args.rs
View file

@ -197,7 +197,7 @@ Usage:
test [another]
Arguments:
<another> another pos
[another] another pos
Options:
-h, --help Print help information

6
tests/builder/subcommands.rs
View file

@ -580,7 +580,7 @@ Usage:
foo bar [value]
Arguments:
<value>
[value]
Options:
-h, --help Print help information
@ -603,7 +603,7 @@ Usage:
foo bar [value]
Arguments:
<value>
[value]
Options:
-h, --help Print help information
@ -626,7 +626,7 @@ Usage:
foo bar [value]
Arguments:
<value>
[value]
Options:
-h, --help Print help information