[cli-221] checkstyle fixes, option attribute renamed, documentation fixes

Author: JoergBudi

src/main/java/org/apache/commons/cli/DefaultParser.java

@@ -609,7 +609,7 @@ private void handleToken(final String token) throws ParseException {
                 skipParsing = true;
             } else if (currentOption != null && currentOption.acceptsArg() && isArgument(token)) {
                 currentOption.processValue(stripLeadingAndTrailingQuotesDefaultOn(token));
-                if (currentOption.areValuesAsList()) {
+                if (currentOption.isValueSeparatorUsedForSingleArgument()) {
                     currentOption = null;
                 }
             } else if (token.startsWith("--")) {

src/main/java/org/apache/commons/cli/Option.java

@@ -103,7 +103,7 @@ private static Class<?> toType(final Class<?> type) {
         private char valueSeparator;
 
         /** multiple values are within a single argument separated by valueSeparator char */
-        private boolean valuesAsList;
+        private boolean valueSeparatorUsedForSingleArgument;
 
         /**
          * Constructs a new {@code Builder} with the minimum required parameters for an {@code Option} instance.
@@ -318,7 +318,7 @@ public Builder valueSeparator() {
         }
 
         /**
-         * The Option will use {@code sep} as a means to separate java-property-style argument values
+         * The Option will use {@code sep} as a means to separate java-property-style argument values.
          *
          * Method is mutually exclusive to listValueSeparator() method.
          * <p>
@@ -336,7 +336,7 @@ public Builder valueSeparator() {
          * String propertyValue = line.getOptionValues("D")[1]; // will be "value"
          * </pre>
          *
-         * In the above example (unlimited args), followup arguments are interpreted
+         * In the above example, followup arguments are interpreted
          * to be additional values to this option, needs to be terminated with -- so that
          * others options or args can follow.
          *
@@ -359,26 +359,28 @@ public Builder listValueSeparator() {
         }
 
         /**
-         * defines the separator used to separate a list of values passed in a single arg
+         * defines the separator used to split a list of values passed in a single argument.
+         *
+         * Method is mutually exclusive to valueSeparator() method. In the resulting option,
+         * isValueSeparatorUsedForSingleArgument() will return true.
          *
-         * Method is mutually exclusive to valueSeparator() method.
          * <p>
          * <strong>Example:</strong>
          * </p>
          *
          * <pre>
-         * final Option colors = Option.builder().option("c").longOpt("colors").hasArgs().listValueSeparator('|').build();
+         * final Option colors = Option.builder().option("c").hasArgs().listValueSeparator('|').build();
          * final Options options = new Options();
          * options.addOption(colors);
          *
          * final String[] args = {"-c", "red|blue|yellow", "b,c"};
          * final DefaultParser parser = new DefaultParser();
          * final CommandLine commandLine = parser.parse(options, args, null, true);
-         * String [] colorValues = commandLine.getOptionValues(colors);
+         * final String [] colorValues = commandLine.getOptionValues(colors);
          * // colorValues[0] will be "red"
          * // colorValues[1] will be "blue"
          * // colorValues[2] will be "yellow"
-         * String arguments = commandLine.getArgs()[0]; // will be b,c
+         * final String arguments = commandLine.getArgs()[0]; // will be b,c
          *
          * </pre>
          *
@@ -388,7 +390,7 @@ public Builder listValueSeparator() {
          */
         public Builder listValueSeparator(final char listValueSeparator) {
             this.valueSeparator = listValueSeparator;
-            this.valuesAsList = true;
+            this.valueSeparatorUsedForSingleArgument = true;
             return this;
         }
     }
@@ -472,7 +474,7 @@ public static Builder builder(final String option) {
     private char valueSeparator;
 
     /** multiple values are within a single argument separated by valueSeparator char */
-    private boolean valuesAsList;
+    private boolean valueSeparatorUsedForSingleArgument;
 
     /**
      * Private constructor used by the nested Builder class.
@@ -492,7 +494,7 @@ private Option(final Builder builder) {
         this.type = builder.type;
         this.valueSeparator = builder.valueSeparator;
         this.converter = builder.converter;
-        this.valuesAsList = builder.valuesAsList;
+        this.valueSeparatorUsedForSingleArgument = builder.valueSeparatorUsedForSingleArgument;
     }
 
     /**
@@ -877,13 +879,24 @@ public boolean isRequired() {
     }
 
     /**
-     * Tests whether multiple values are expected in a single argument separated by a separation character
+     * Tests whether multiple values are expected in a single argument split by a separation character
+     *
+     * @return boolean true when the builder's listValueSeparator() method was used. Multiple values are expected in a single argument and
+     *                 are split by a separation character.
+     * @since 1.10.0
+     */
+    public boolean isValueSeparatorUsedForSingleArgument() {
+        return valueSeparatorUsedForSingleArgument;
+    }
+
+    /**
+     * Set this to true to use the valueSeparator only on a single argument. See also builder's listValueSeparator() method.
      *
-     * @return boolean true when multiple values are expected in a single separated by a separation character
+     * @param valueSeparatorUsedForSingleArgument the new value for this property
      * @since 1.10.0
      */
-    public boolean areValuesAsList() {
-        return valuesAsList;
+    public void setValueSeparatorUsedForSingleArgument(final boolean valueSeparatorUsedForSingleArgument) {
+        this.valueSeparatorUsedForSingleArgument = valueSeparatorUsedForSingleArgument;
     }
 
     /**

src/test/java/org/apache/commons/cli/DefaultParserTest.java

@@ -339,8 +339,8 @@ void listValueSeparatorTest() throws ParseException {
         final String[] args = {"-c", "red|blue|yellow", "b,c"};
         final DefaultParser parser = new DefaultParser();
         final CommandLine commandLine = parser.parse(options, args, null, true);
-        String [] colorValues = commandLine.getOptionValues(colors);
-        assertEquals(3, colorValues.length );
+        final String [] colorValues = commandLine.getOptionValues(colors);
+        assertEquals(3, colorValues.length);
         assertEquals("red", colorValues[0]);
         assertEquals("blue", colorValues[1]);
         assertEquals("yellow", colorValues[2]);
@@ -350,18 +350,18 @@ void listValueSeparatorTest() throws ParseException {
     @ParameterizedTest
     @ValueSource(strings = {
             "--colors=red,blue,yellow b",
-            "--colors red,blue,yellow b" ,
-            "-c=red,blue,yellow b" ,
-            "-c red,blue,yellow b" })
-    void listValueSeparatorDefaultTest(String args) throws ParseException {
+            "--colors red,blue,yellow b",
+            "-c=red,blue,yellow b",
+            "-c red,blue,yellow b"})
+    void listValueSeparatorDefaultTest(final String args) throws ParseException {
         final Option colors = Option.builder().option("c").longOpt("colors").hasArgs().listValueSeparator().build();
         final Options options = new Options();
         options.addOption(colors);
 
         final DefaultParser parser = new DefaultParser();
         final CommandLine commandLine = parser.parse(options, args.split(" "), null, true);
-        String [] colorValues = commandLine.getOptionValues(colors);
-        assertEquals(3, colorValues.length );
+        final String [] colorValues = commandLine.getOptionValues(colors);
+        assertEquals(3, colorValues.length);
         assertEquals("red", colorValues[0]);
         assertEquals("blue", colorValues[1]);
         assertEquals("yellow", colorValues[2]);
@@ -386,7 +386,7 @@ void listValueSeparatorSeriesDoesntMatter(final String args) throws ParseExcepti
         final CommandLine commandLine = parser.parse(options, args.split(" "), null, false);
         final String [] colorValues = commandLine.getOptionValues(colors);
         final String fooValue = commandLine.getOptionValue(foo);
-        assertEquals(3, colorValues.length );
+        assertEquals(3, colorValues.length);
         assertEquals("red", colorValues[0]);
         assertEquals("blue", colorValues[1]);
         assertEquals("yellow", colorValues[2]);

src/test/java/org/apache/commons/cli/OptionTest.java

@@ -348,24 +348,30 @@ void testTypeObject() {
     @Test
     void testDefaultValueSeparator() {
         final Option option = Option.builder().option("a").hasArgs().valueSeparator().build();
-        assertFalse(option.areValuesAsList());
+        assertFalse(option.isValueSeparatorUsedForSingleArgument());
         assertTrue(option.hasValueSeparator());
-        assertEquals('=',option.getValueSeparator());
+        assertEquals('=', option.getValueSeparator());
     }
 
     @Test
-    void testDefaultValueAsList() {
+    void testDefaultListValueSeparator() {
         final Option option = Option.builder().option("a").hasArgs().listValueSeparator().build();
-        assertTrue(option.areValuesAsList());
+        assertTrue(option.isValueSeparatorUsedForSingleArgument());
         assertTrue(option.hasValueSeparator());
-        assertEquals(',',option.getValueSeparator());
+        assertEquals(',', option.getValueSeparator());
     }
-    
+
     @Test
-    void testValueAsList() {
+    void testListValueSeparator() {
         final Option option = Option.builder().option("a").hasArgs().listValueSeparator('|').build();
-        assertTrue(option.areValuesAsList());
+        assertTrue(option.isValueSeparatorUsedForSingleArgument());
+        assertTrue(option.hasValueSeparator());
+        assertEquals('|', option.getValueSeparator());
+
+        option.setValueSeparatorUsedForSingleArgument(false);
+        assertFalse(option.isValueSeparatorUsedForSingleArgument());
         assertTrue(option.hasValueSeparator());
-        assertEquals('|',option.getValueSeparator());
+        assertEquals('|', option.getValueSeparator());
+
     }
 }