Skip to content

Commit

Permalink
#198 Usage help parameter list details should indicate arity for posi…
Browse files Browse the repository at this point in the history 
…tional parameters

Closes #198
  • Loading branch information
@remkop
remkop committed Oct 5, 2017
1 parent 0e7508c commit b67a175
Show file tree
Hide file tree
Showing 4 changed files with 56 additions and 48 deletions.
3 changes: 2 additions & 1 deletion RELEASE-NOTES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,8 @@ class Args {
- #191 Bugfix: Arity should not limit the total number of values put in an array or collection. Thanks to [RobertZenz](https://github.com/RobertZenz).
- #186 Bugfix: Confusing usage message for collection options. Thanks to [AlexFalappa](https://github.com/AlexFalappa).
- #181 Bugfix: Incorrect help message was displayed for short options with paramLabel when arity > 1
- #194 Bugfix: Usage help should show split regex for option/parameters
- #194 Enhancement: Usage help should show split regex for option/parameters
- #198 Enhancement: Usage help parameter list details should indicate arity for positional parameters
- #195 Enhancement: Usage help should show Map types if paramLabel not specified
- #185 Enhancement: Exception message text for missing options should not use field names but be more descriptive and consistent with usage help. Thanks to [AlexFalappa](https://github.com/AlexFalappa).
- #184 Doc: Improved CommandLine.setSeparator javadoc to clarify that this affects parsing only and link to the `@Command` `separator` annotation attribute. Thanks to [defnull](https://github.com/defnull).
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/picocli/CommandLine.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2735,7 +2735,7 @@ public String optionList(Layout layout, Comparator<Field> optionSort, IParamLabe
* @return the section of the usage help message that lists the parameters
*/
public String parameterList() {
return parameterList(createDefaultLayout(), createMinimalParamLabelRenderer());
return parameterList(createDefaultLayout(), createDefaultParamLabelRenderer());
}
/**
* Returns the section of the usage help message that lists the parameters with their descriptions.
Expand Down
95 changes: 51 additions & 44 deletions src/test/java/picocli/CommandLineHelpTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -664,66 +664,68 @@ public void testUsageVariableArityParametersArray() throws UnsupportedEncodingEx
// if option is required at least once and can be specified multiple times:
// -f=ARG [-f=ARG]...
class Args {
@Parameters(paramLabel = "APARAM")
@Parameters(paramLabel = "APARAM", description = "APARAM description")
String[] a;
@Parameters(arity = "0..*")
@Parameters(arity = "0..*", description = "b description")
List<String> b;
@Parameters(arity = "1..*")
@Parameters(arity = "1..*", description = "c description")
String[] c;
@Parameters(arity = "2..*")
@Parameters(arity = "2..*", description = "d description")
List<String> d;
}
String expected = String.format("" +
"Usage: <main class> [APARAM]... [<b>]... <c>... <d> <d>...%n" +
" APARAM%n" +
" <b>%n" +
" <c>%n" +
" <d>%n");
" [APARAM]... APARAM description%n" +
" [<b>]... b description%n" +
" <c>... c description%n" +
" <d> <d>... d description%n");
//CommandLine.usage(new Args(), System.out);
assertEquals(expected, usageString(new Args(), Help.Ansi.OFF));
}

@Test
public void testUsageRangeArityParameterArray() throws UnsupportedEncodingException {
class Args {
@Parameters(paramLabel = "PARAMA", arity = "0..1")
@Parameters(paramLabel = "PARAMA", arity = "0..1", description = "PARAMA description")
List<String> a;
@Parameters(paramLabel = "PARAMB", arity = "1..2")
@Parameters(paramLabel = "PARAMB", arity = "1..2", description = "PARAMB description")
String[] b;
@Parameters(paramLabel = "PARAMC", arity = "1..3")
@Parameters(paramLabel = "PARAMC", arity = "1..3", description = "PARAMC description")
String[] c;
@Parameters(paramLabel = "PARAMD", arity = "2..4")
@Parameters(paramLabel = "PARAMD", arity = "2..4", description = "PARAMD description")
String[] d;
}
String expected = String.format("" +
"Usage: <main class> [PARAMA] PARAMB [PARAMB] PARAMC [PARAMC [PARAMC]] PARAMD%n" +
" PARAMD [PARAMD [PARAMD]]%n" +
" PARAMA%n" +
" PARAMB%n" +
" PARAMC%n" +
" PARAMD%n");
" [PARAMA] PARAMA description%n" +
" PARAMB [PARAMB] PARAMB description%n" +
" PARAMC [PARAMC [PARAMC]]%n" +
" PARAMC description%n" +
" PARAMD PARAMD [PARAMD [PARAMD]]%n" +
" PARAMD description%n");
//CommandLine.usage(new Args(), System.out);
assertEquals(expected, usageString(new Args(), Help.Ansi.OFF));
}

@Test
public void testUsageFixedArityParametersArray() throws UnsupportedEncodingException {
class Args {
@Parameters()
@Parameters(description = "a description (default arity)")
String[] a;
@Parameters(arity = "0")
@Parameters(arity = "0", description = "b description (arity=0)")
String[] b;
@Parameters(arity = "1")
@Parameters(arity = "1", description = "b description (arity=1)")
String[] c;
@Parameters(arity = "2")
@Parameters(arity = "2", description = "b description (arity=2)")
String[] d;
}
String expected = String.format("" +
"Usage: <main class> [<a>]... <c> <d> <d>%n" +
" <b>%n" +
" <a>%n" +
" <c>%n" +
" <d>%n");
" b description (arity=0)%n" +
" [<a>]... a description (default arity)%n" +
" <c> b description (arity=1)%n" +
" <d> <d> b description (arity=2)%n");
//CommandLine.usage(new Args(), System.out);
assertEquals(expected, usageString(new Args(), Help.Ansi.OFF));
}
Expand All @@ -733,7 +735,7 @@ public void testUsageVariableArityParametersMap() throws UnsupportedEncodingExce
class Args {
@Parameters()
Map<String, String> a;
@Parameters(arity = "0..*", type = {Integer.class, Integer.class})
@Parameters(arity = "0..*", description = "a description (arity=0..*)")
Map<Integer, Integer> b;
@Parameters(paramLabel = "KEY=VALUE", arity = "1..*", type = {String.class, TimeUnit.class})
Map<String, TimeUnit> c;
Expand All @@ -743,10 +745,11 @@ class Args {
String expected = String.format("" +
"Usage: <main class> [<String=String>]... [<Integer=Integer>]... KEY=VALUE...%n" +
" <String=URL> <String=URL>...%n" +
" <String=String>%n" +
" <Integer=Integer>%n" +
" KEY=VALUE%n" +
" <String=URL> description%n");
" [<String=String>]...%n" +
" [<Integer=Integer>]... a description (arity=0..*)%n" +
" KEY=VALUE...%n" +
" <String=URL> <String=URL>...%n" +
" description%n");
//CommandLine.usage(new Args(), System.out);
assertEquals(expected, usageString(new Args(), Help.Ansi.OFF));
}
Expand All @@ -766,10 +769,12 @@ class Args {
String expected = String.format("" +
"Usage: <main class> [<UUID=URL>] <Long=UUID> [<Long=UUID>] <String=String>%n" +
" [<String=String> [<String=String>]] K=V K=V [K=V [K=V]]%n" +
" <UUID=URL> a description%n" +
" <Long=UUID> b description%n" +
" <String=String> c description%n" +
" K=V d description%n");
" [<UUID=URL>] a description%n" +
" <Long=UUID> [<Long=UUID>]%n" +
" b description%n" +
" <String=String> [<String=String> [<String=String>]]%n" +
" c description%n" +
" K=V K=V [K=V [K=V]] d description%n");
//CommandLine.usage(new Args(), System.out);
assertEquals(expected, usageString(new Args(), Help.Ansi.OFF));
}
Expand All @@ -779,7 +784,7 @@ public void testUsageFixedArityParametersMap() throws UnsupportedEncodingExcepti
class Args {
@Parameters(type = {Short.class, Field.class}, description = "a description")
Map<Short, Field> a;
@Parameters(arity = "0", type = {UUID.class, Long.class}, description = "b description")
@Parameters(arity = "0", type = {UUID.class, Long.class}, description = "b description (arity=0)")
@SuppressWarnings("unchecked")
Map b;
@Parameters(arity = "1", description = "c description")
Expand All @@ -789,10 +794,10 @@ class Args {
}
String expected = String.format("" +
"Usage: <main class> [<Short=Field>]... <Long=File> <URI=URL> <URI=URL>%n" +
" <UUID=Long> b description%n" +
" <Short=Field> a description%n" +
" b description (arity=0)%n" +
" [<Short=Field>]... a description%n" +
" <Long=File> c description%n" +
" <URI=URL> d description%n");
" <URI=URL> <URI=URL> d description%n");
//CommandLine.usage(new Args(), System.out);
assertEquals(expected, usageString(new Args(), Help.Ansi.OFF));
}
Expand Down Expand Up @@ -1737,12 +1742,13 @@ class App {
String actual = usageString(new App(), Help.Ansi.OFF);
String expected = String.format(
"Usage: <main class> <host1> <port1> <host2> <port2range> [<port2range>]%n" +
" [<files>]...%n" +
" <host1> source host%n" +
" <port1> source port%n" +
" <host2> destination host%n" +
" <port2range> destination port range%n" +
" <files> files to transfer%n"
" [<files>]...%n" +
" <host1> source host%n" +
" <port1> source port%n" +
" <host2> destination host%n" +
" <port2range> [<port2range>]%n" +
" destination port range%n" +
" [<files>]... files to transfer%n"
);
assertEquals(expected, actual);
}
Expand Down Expand Up @@ -2300,7 +2306,8 @@ class App {
String expected = String.format("" +
"Usage: <main class> [-P=TIMEUNIT=VALUE[,TIMEUNIT=VALUE]...]... FIXTAG=VALUE%n" +
" [\\|FIXTAG=VALUE]... FIXTAG=VALUE[\\|FIXTAG=VALUE]...%n" +
" FIXTAG=VALUE Exactly two lists of vertical bar '|'-separated%n" +
" FIXTAG=VALUE[\\|FIXTAG=VALUE]... FIXTAG=VALUE[\\|FIXTAG=VALUE]...%n" +
" Exactly two lists of vertical bar '|'-separated%n" +
" FIXTAG=VALUE pairs.%n" +
" -P, -map=TIMEUNIT=VALUE[,TIMEUNIT=VALUE]...%n" +
" Any number of TIMEUNIT=VALUE pairs. These may be%n" +
Expand Down
4 changes: 2 additions & 2 deletions src/test/java/picocli/Demo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -587,7 +587,7 @@ public void testUsageSubCommandCommit() {
"message from the user describing the changes.%n" +
"%n" +
"Parameters:%n" +
" <files> the files to commit%n" +
" [<files>]... the files to commit%n" +
"%n" +
"Options:%n" +
" -a, --all Tell the command to automatically stage files%n" +
Expand Down Expand Up @@ -631,7 +631,7 @@ public void testUsageSubCommandCommit() {
"message from the user describing the changes.%n" +
"%n" +
"@|bold,underline Parameters:|@%n" +
" @|yellow <files>|@ the files to commit%n" +
" [@|yellow <files>|@]... the files to commit%n" +
"%n" +
"@|bold,underline Options:|@%n" +
" @|yellow -a|@, @|yellow --all|@ Tell the command to automatically stage files%n" +
Expand Down

0 comments on commit b67a175

Please sign in to comment.