diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index aaaa65403..b826e8e01 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -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). diff --git a/src/main/java/picocli/CommandLine.java b/src/main/java/picocli/CommandLine.java index e0604ff0d..1204d990c 100644 --- a/src/main/java/picocli/CommandLine.java +++ b/src/main/java/picocli/CommandLine.java @@ -2735,7 +2735,7 @@ public String optionList(Layout layout, Comparator 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. diff --git a/src/test/java/picocli/CommandLineHelpTest.java b/src/test/java/picocli/CommandLineHelpTest.java index 9b0a5f490..58cd891a1 100644 --- a/src/test/java/picocli/CommandLineHelpTest.java +++ b/src/test/java/picocli/CommandLineHelpTest.java @@ -664,21 +664,21 @@ 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 b; - @Parameters(arity = "1..*") + @Parameters(arity = "1..*", description = "c description") String[] c; - @Parameters(arity = "2..*") + @Parameters(arity = "2..*", description = "d description") List d; } String expected = String.format("" + "Usage:
[APARAM]... []... ... ...%n" + - " APARAM%n" + - " %n" + - " %n" + - " %n"); + " [APARAM]... APARAM description%n" + + " []... b description%n" + + " ... c description%n" + + " ... d description%n"); //CommandLine.usage(new Args(), System.out); assertEquals(expected, usageString(new Args(), Help.Ansi.OFF)); } @@ -686,22 +686,24 @@ class Args { @Test public void testUsageRangeArityParameterArray() throws UnsupportedEncodingException { class Args { - @Parameters(paramLabel = "PARAMA", arity = "0..1") + @Parameters(paramLabel = "PARAMA", arity = "0..1", description = "PARAMA description") List 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:
[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)); } @@ -709,21 +711,21 @@ class Args { @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:
[]... %n" + - " %n" + - " %n" + - " %n" + - " %n"); + " b description (arity=0)%n" + + " []... a description (default arity)%n" + + " b description (arity=1)%n" + + " b description (arity=2)%n"); //CommandLine.usage(new Args(), System.out); assertEquals(expected, usageString(new Args(), Help.Ansi.OFF)); } @@ -733,7 +735,7 @@ public void testUsageVariableArityParametersMap() throws UnsupportedEncodingExce class Args { @Parameters() Map a; - @Parameters(arity = "0..*", type = {Integer.class, Integer.class}) + @Parameters(arity = "0..*", description = "a description (arity=0..*)") Map b; @Parameters(paramLabel = "KEY=VALUE", arity = "1..*", type = {String.class, TimeUnit.class}) Map c; @@ -743,10 +745,11 @@ class Args { String expected = String.format("" + "Usage:
[]... []... KEY=VALUE...%n" + " ...%n" + - " %n" + - " %n" + - " KEY=VALUE%n" + - " description%n"); + " []...%n" + + " []... a description (arity=0..*)%n" + + " KEY=VALUE...%n" + + " ...%n" + + " description%n"); //CommandLine.usage(new Args(), System.out); assertEquals(expected, usageString(new Args(), Help.Ansi.OFF)); } @@ -766,10 +769,12 @@ class Args { String expected = String.format("" + "Usage:
[] [] %n" + " [ []] K=V K=V [K=V [K=V]]%n" + - " a description%n" + - " b description%n" + - " c description%n" + - " K=V d description%n"); + " [] a description%n" + + " []%n" + + " b description%n" + + " [ []]%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)); } @@ -779,7 +784,7 @@ public void testUsageFixedArityParametersMap() throws UnsupportedEncodingExcepti class Args { @Parameters(type = {Short.class, Field.class}, description = "a description") Map 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") @@ -789,10 +794,10 @@ class Args { } String expected = String.format("" + "Usage:
[]... %n" + - " b description%n" + - " a description%n" + + " b description (arity=0)%n" + + " []... a description%n" + " c description%n" + - " d description%n"); + " d description%n"); //CommandLine.usage(new Args(), System.out); assertEquals(expected, usageString(new Args(), Help.Ansi.OFF)); } @@ -1737,12 +1742,13 @@ class App { String actual = usageString(new App(), Help.Ansi.OFF); String expected = String.format( "Usage:
[]%n" + - " []...%n" + - " source host%n" + - " source port%n" + - " destination host%n" + - " destination port range%n" + - " files to transfer%n" + " []...%n" + + " source host%n" + + " source port%n" + + " destination host%n" + + " []%n" + + " destination port range%n" + + " []... files to transfer%n" ); assertEquals(expected, actual); } @@ -2300,7 +2306,8 @@ class App { String expected = String.format("" + "Usage:
[-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" + diff --git a/src/test/java/picocli/Demo.java b/src/test/java/picocli/Demo.java index 7e820c288..fd9b1d769 100644 --- a/src/test/java/picocli/Demo.java +++ b/src/test/java/picocli/Demo.java @@ -587,7 +587,7 @@ public void testUsageSubCommandCommit() { "message from the user describing the changes.%n" + "%n" + "Parameters:%n" + - " the files to commit%n" + + " []... the files to commit%n" + "%n" + "Options:%n" + " -a, --all Tell the command to automatically stage files%n" + @@ -631,7 +631,7 @@ public void testUsageSubCommandCommit() { "message from the user describing the changes.%n" + "%n" + "@|bold,underline Parameters:|@%n" + - " @|yellow |@ the files to commit%n" + + " [@|yellow |@]... the files to commit%n" + "%n" + "@|bold,underline Options:|@%n" + " @|yellow -a|@, @|yellow --all|@ Tell the command to automatically stage files%n" +