[#625] rename synopsisSubcommands to synopsisSubcommandLabel

RELEASE-NOTES.md

@@ -42,7 +42,7 @@ The option description may contain the `${FALLBACK-VALUE}` variable which will b
 
 ## <a name="4.0.0-rc-1-fixes"></a> Fixed issues
 - [#280] API: `@Option(fallbackValue = "...")` for options with optional parameter: assign this value when the option was specified on the command line without parameter. Thanks to [Paolo Di Tommaso](https://github.com/pditommaso) and [marinier](https://github.com/marinier) for the suggestion and in-depth discussion.
-- [#625] API: `@Command(synopsisSubcommands = "...")` to allow customization of the subcommands part of the synopsis: by default this is `[COMMAND]`. Thanks to [Sebastian Thomschke](https://github.com/sebthom) and [AlcaYezz](https://github.com/AlcaYezz) for the feature request and subsequent discussion.
+- [#625] API: `@Command(synopsisSubcommandLabel = "...")` to allow customization of the subcommands part of the synopsis: by default this is `[COMMAND]`. Thanks to [Sebastian Thomschke](https://github.com/sebthom) and [AlcaYezz](https://github.com/AlcaYezz) for the feature request and subsequent discussion.
 - [#721] API: Add public method Text.getCJKAdjustedLength().
 - [#717] Negatable options change: avoid unmappable character `±` for synopsis: it renders as scrambled characters in encoding ASCII and in some terminals.
 - [#719] Bugfix: options with variable arity should stop consuming arguments on custom end-of-options delimiter.

src/main/java/picocli/CommandLine.java

@@ -3999,7 +3999,7 @@ private static class NoCompletionCandidates implements Iterable<String> {
          * {@code "[COMMAND]"}. Ignored if this command has no {@linkplain #subcommands() subcommands}.
          * @since 4.0
          */
-        String synopsisSubcommands() default "[COMMAND]";
+        String synopsisSubcommandLabel() default "[COMMAND]";
 
         /** Set the heading preceding the description section.
          * <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
@@ -5975,7 +5975,7 @@ public static class UsageMessageSpec {
             private Character requiredOptionMarker;
             private String headerHeading;
             private String synopsisHeading;
-            private String synopsisSubcommands;
+            private String synopsisSubcommandLabel;
             private String descriptionHeading;
             private String parameterListHeading;
             private String optionListHeading;
@@ -6184,8 +6184,8 @@ private String[] arr(String[] localized, String[] value, String[] defaultValue)
             /** Returns the optional heading preceding the synopsis. Initialized from {@link Command#synopsisHeading()}, {@code "Usage: "} by default. */
             public String synopsisHeading() { return str(resourceStr("usage.synopsisHeading"), synopsisHeading, DEFAULT_SYNOPSIS_HEADING); }
 
-            /** Returns the String representing the subcommands in the synopsis. Initialized from {@link Command#synopsisSubcommands()}, {@code "[COMMANDS]"} by default. */
-            public String synopsisSubcommands() { return str(resourceStr("usage.synopsisSubcommands"), synopsisSubcommands, DEFAULT_SYNOPSIS_SUBCOMMANDS); }
+            /** Returns the String representing the subcommands in the synopsis. Initialized from {@link Command#synopsisSubcommandLabel()}, {@code "[COMMANDS]"} by default. */
+            public String synopsisSubcommandLabel() { return str(resourceStr("usage.synopsisSubcommandLabel"), synopsisSubcommandLabel, DEFAULT_SYNOPSIS_SUBCOMMANDS); }
 
             /** Returns whether the synopsis line(s) should show an abbreviated synopsis without detailed option names. */
             public boolean abbreviateSynopsis() { return (abbreviateSynopsis == null) ? DEFAULT_ABBREVIATE_SYNOPSIS : abbreviateSynopsis; }
@@ -6293,7 +6293,7 @@ public static Map<String, String> keyValuesMap(String... entries) {
 
             /** Sets the String representing the subcommands in the synopsis.
              * @return this UsageMessageSpec for method chaining */
-            public UsageMessageSpec synopsisSubcommands(String newValue) {synopsisSubcommands = newValue; return this;}
+            public UsageMessageSpec synopsisSubcommandLabel(String newValue) {synopsisSubcommandLabel = newValue; return this;}
 
             /** Sets whether the synopsis line(s) should show an abbreviated synopsis without detailed option names.
              * @return this UsageMessageSpec for method chaining */
@@ -6396,7 +6396,7 @@ void updateFromCommand(Command cmd, CommandSpec commandSpec, boolean loadResourc
                     }
                 }
                 if (isNonDefault(cmd.synopsisHeading(), DEFAULT_SYNOPSIS_HEADING))            {synopsisHeading = cmd.synopsisHeading();}
-                if (isNonDefault(cmd.synopsisSubcommands(), DEFAULT_SYNOPSIS_SUBCOMMANDS))    {synopsisSubcommands = cmd.synopsisSubcommands();}
+                if (isNonDefault(cmd.synopsisSubcommandLabel(), DEFAULT_SYNOPSIS_SUBCOMMANDS)){synopsisSubcommandLabel = cmd.synopsisSubcommandLabel();}
                 if (isNonDefault(cmd.commandListHeading(), DEFAULT_COMMAND_LIST_HEADING))     {commandListHeading = cmd.commandListHeading();}
                 if (isNonDefault(cmd.requiredOptionMarker(), DEFAULT_REQUIRED_OPTION_MARKER)) {requiredOptionMarker = cmd.requiredOptionMarker();}
                 if (isNonDefault(cmd.abbreviateSynopsis(), DEFAULT_ABBREVIATE_SYNOPSIS))      {abbreviateSynopsis = cmd.abbreviateSynopsis();}
@@ -6418,7 +6418,7 @@ void updateFromCommand(Command cmd, CommandSpec commandSpec, boolean loadResourc
             }
             void initFromMixin(UsageMessageSpec mixin, CommandSpec commandSpec) {
                 if (initializable(synopsisHeading, mixin.synopsisHeading(), DEFAULT_SYNOPSIS_HEADING))                 {synopsisHeading = mixin.synopsisHeading();}
-                if (initializable(synopsisSubcommands, mixin.synopsisSubcommands(), DEFAULT_SYNOPSIS_SUBCOMMANDS))                 {synopsisHeading = mixin.synopsisHeading();}
+                if (initializable(synopsisSubcommandLabel, mixin.synopsisSubcommandLabel(), DEFAULT_SYNOPSIS_SUBCOMMANDS)) {synopsisHeading = mixin.synopsisHeading();}
                 if (initializable(commandListHeading, mixin.commandListHeading(), DEFAULT_COMMAND_LIST_HEADING))       {commandListHeading = mixin.commandListHeading();}
                 if (initializable(requiredOptionMarker, mixin.requiredOptionMarker(), DEFAULT_REQUIRED_OPTION_MARKER)) {requiredOptionMarker = mixin.requiredOptionMarker();}
                 if (initializable(abbreviateSynopsis, mixin.abbreviateSynopsis(), DEFAULT_ABBREVIATE_SYNOPSIS))        {abbreviateSynopsis = mixin.abbreviateSynopsis();}
@@ -6451,7 +6451,7 @@ void initFrom(UsageMessageSpec settings, CommandSpec commandSpec) {
                 requiredOptionMarker = settings.requiredOptionMarker;
                 headerHeading = settings.headerHeading;
                 synopsisHeading = settings.synopsisHeading;
-                synopsisSubcommands = settings.synopsisSubcommands;
+                synopsisSubcommandLabel = settings.synopsisSubcommandLabel;
                 descriptionHeading = settings.descriptionHeading;
                 parameterListHeading = settings.parameterListHeading;
                 optionListHeading = settings.optionListHeading;
@@ -12183,7 +12183,7 @@ public String abbreviatedSynopsis() {
 
             // only show if object has subcommands
             if (!commandSpec.subcommands().isEmpty()) {
-                sb.append(" ").append(commandSpec.usageMessage().synopsisSubcommands());
+                sb.append(" ").append(commandSpec.usageMessage().synopsisSubcommandLabel());
             }
 
             return colorScheme.commandText(commandSpec.qualifiedName()).toString()
@@ -12320,12 +12320,12 @@ protected Text createDetailedSynopsisPositionalsText(Collection<ArgSpec> done) {
 
         /** Returns a Text object containing a partial detailed synopsis showing only the subcommands, starting with a {@code " "} space.
          * Follows the unix convention of showing optional elements in square brackets ({@code [ ]}).
-         * @return this implementation returns " " + {@link UsageMessageSpec#synopsisSubcommands()} if this command has subcommands, an empty Text otherwise.
+         * @return this implementation returns " " + {@link UsageMessageSpec#synopsisSubcommandLabel()} if this command has subcommands, an empty Text otherwise.
          * @since 3.9 */
         protected Text createDetailedSynopsisCommandText() {
             Text commandText = ansi().new Text(0);
             if (!commandSpec.subcommands().isEmpty()) {
-                return commandText.concat(" ").concat(commandSpec.usageMessage().synopsisSubcommands());
+                return commandText.concat(" ").concat(commandSpec.usageMessage().synopsisSubcommandLabel());
             }
             return commandText;
         }

src/test/java/picocli/SubcommandTests.java

@@ -1922,7 +1922,7 @@ class TopLevel {}
 
     // https://github.com/remkop/picocli/issues/625
     static class MandatorySubcommand625 {
-        @Command(name = "top", subcommands = Sub.class, synopsisSubcommands = "COMMAND")
+        @Command(name = "top", subcommands = Sub.class, synopsisSubcommandLabel = "COMMAND")
         static class Top implements Runnable {
             @CommandLine.Spec
             CommandSpec spec;