[#481] Add @Command(usageHelpWidth = <int>) annotation attribute

Closes #481

RELEASE-NOTES.md

@@ -82,6 +82,7 @@ See the module's [README](https://github.com/remkop/picocli/blob/master/picocli-
 - [#499] add module `picocli-codegen` for tools to generate documentation, configuration, source code and other files from a picocli model
 - [#410] add `ReflectionConfigGenerator` class for GraalVM `native-image`
 - [#513] Enhancement: Simplify AutoCompletion script generator code.
+- [#481] Enhancement: Add `@Command(usageHelpWidth = <int>)` annotation attribute.
 - [#379] Option with split property should not split quoted strings. Thanks to [Markus Kramer](https://github.com/MarkusKramer) for the feature request.
 - [#514] Bugfix/Enhancement: picocli no longer removes opening and closing quotes around arguments by default. This is configurable with `CommandLine::setTrimQuotes`. Thanks to [mshatalov](https://github.com/mshatalov) for the bug report.
 - [#509] Bugfix: Long boolean options with arity 0 should not allow parameters.  Thanks to [Adam Zegelin](https://github.com/zegelin) for the bug report.

src/main/java/picocli/CommandLine.java

@@ -3123,6 +3123,11 @@ private static class NoCompletionCandidates implements Iterable<String> {
          * @since 3.6
          */
         String resourceBundle() default "";
+
+        /** Set the {@link UsageMessageSpec#width(int) usage help message width}. The default is 80.
+         * @since 3.7
+         */
+        int usageHelpWidth() default 80;
     }
     /**
      * <p>
@@ -4135,7 +4140,7 @@ private static int getSysPropertyWidthOrDefault(int defaultWidth) {
              */
             public UsageMessageSpec width(int newValue) {
                 if (newValue < MINIMUM_USAGE_WIDTH) {
-                    throw new IllegalArgumentException("Invalid usage message width " + newValue + ". Minimum value is " + MINIMUM_USAGE_WIDTH);
+                    throw new InitializationException("Invalid usage message width " + newValue + ". Minimum value is " + MINIMUM_USAGE_WIDTH);
                 }
                 width = newValue; return this;
             }
@@ -4305,6 +4310,7 @@ void updateFromCommand(Command cmd, CommandSpec commandSpec) {
                 if (isNonDefault(cmd.footerHeading(), DEFAULT_SINGLE_VALUE))                  {footerHeading = cmd.footerHeading();}
                 if (isNonDefault(cmd.parameterListHeading(), DEFAULT_SINGLE_VALUE))           {parameterListHeading = cmd.parameterListHeading();}
                 if (isNonDefault(cmd.optionListHeading(), DEFAULT_SINGLE_VALUE))              {optionListHeading = cmd.optionListHeading();}
+                if (isNonDefault(cmd.usageHelpWidth(), DEFAULT_USAGE_WIDTH))                  {width(cmd.usageHelpWidth());} // validate
 
                 ResourceBundle rb = empty(cmd.resourceBundle()) ? null : ResourceBundle.getBundle(cmd.resourceBundle());
                 if (rb != null) { messages(new Messages(commandSpec, rb)); } // else preserve superclass bundle

src/test/java/picocli/CommandLineHelpTest.java

@@ -3593,6 +3593,45 @@ public void testInvalidUsageWidthPropertyValue() throws UnsupportedEncodingExcep
         assertEquals(format("[picocli WARN] Invalid picocli.usage.width value 'INVALID'. Using usage width 80.%n"), baos.toString("UTF-8"));
     }
 
+    @Test
+    public void testUsageWidthFromCommandAttribute() {
+        @Command(usageHelpWidth = 60,
+        description = "0123456789012345678901234567890123456789012345678901234567890123456789")
+        class App {}
+        CommandLine cmd = new CommandLine(new App());
+
+        assertEquals(60, cmd.getUsageHelpWidth());
+        assertEquals(60, cmd.getCommandSpec().usageMessage().width());
+    }
+
+    @Test
+    public void testUsageWidthFromSystemPropertyOverridesCommandAttribute() {
+        @Command(usageHelpWidth = 60,
+                description = "0123456789012345678901234567890123456789012345678901234567890123456789")
+        class App {}
+        System.setProperty("picocli.usage.width", "123");
+        try {
+            CommandLine cmd = new CommandLine(new App());
+
+            assertEquals(123, cmd.getUsageHelpWidth());
+            assertEquals(123, cmd.getCommandSpec().usageMessage().width());
+        } finally {
+            System.clearProperty("picocli.usage.width");
+        }
+    }
+
+    @Test
+    public void testInvalidUsageWidthCommandAttribute() throws UnsupportedEncodingException {
+        @Command(usageHelpWidth = 40)
+        class App {}
+        try {
+            new CommandLine(new App());
+            fail("Expected exception");
+        } catch (InitializationException ex) {
+            assertEquals("Invalid usage message width 40. Minimum value is 55", ex.getMessage());
+        };
+    }
+
     @Test
     public void testTooSmallUsageWidthPropertyValue() throws UnsupportedEncodingException {
         PrintStream originalErr = System.err;

src/test/java/picocli/CommandLineModelTest.java

@@ -229,7 +229,7 @@ public void testUsageHelp_width_setter() {
         assertEquals(67, spec.width());
     }
 
-    @Test(expected = IllegalArgumentException.class)
+    @Test(expected = InitializationException.class)
     public void testUsageHelp_width_setterDisallowsValuesBelow55() {
         new UsageMessageSpec().width(54);
     }