Fix for CLI-340

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

@@ -18,6 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 package org.apache.commons.cli;
 
 import java.io.Serializable;
+import java.lang.reflect.Array;
 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.LinkedList;
@@ -505,7 +506,7 @@ public String[] getOptionValues(final String opt) {
      *
      * @param opt the name of the option.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or null if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.5.0
@@ -520,7 +521,7 @@ public <T> T getParsedOptionValue(final char opt) throws ParseException {
      * @param opt the name of the option.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.7.0
@@ -535,7 +536,7 @@ public <T> T getParsedOptionValue(final char opt, final Supplier<T> defaultValue
      * @param opt the name of the option.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.7.0
@@ -549,7 +550,7 @@ public <T> T getParsedOptionValue(final char opt, final T defaultValue) throws P
      *
      * @param option the option.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or null if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.5.0
@@ -564,7 +565,7 @@ public <T> T getParsedOptionValue(final Option option) throws ParseException {
      * @param option the option.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.7.0
@@ -591,7 +592,7 @@ public <T> T getParsedOptionValue(final Option option, final Supplier<T> default
      * @param option the option.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.7.0
@@ -605,7 +606,7 @@ public <T> T getParsedOptionValue(final Option option, final T defaultValue) thr
      *
      * @param optionGroup the option group.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or null if no option in the OptionGroup is set.
      * @throws ParseException if there are problems turning the selected option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.9.0
@@ -620,7 +621,7 @@ public <T> T getParsedOptionValue(final OptionGroup optionGroup) throws ParseExc
      * @param optionGroup the option group.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if no option in the OptionGroup is set.
      * @throws ParseException if there are problems turning the selected option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.9.0
@@ -638,7 +639,7 @@ public <T> T getParsedOptionValue(final OptionGroup optionGroup, final Supplier<
      * @param optionGroup the option group.
      * @param defaultValue the default value to return if an option is not selected.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if no option in the OptionGroup is set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.9.0
@@ -652,7 +653,7 @@ public <T> T getParsedOptionValue(final OptionGroup optionGroup, final T default
      *
      * @param opt the name of the option.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or null if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.2
@@ -667,7 +668,7 @@ public <T> T getParsedOptionValue(final String opt) throws ParseException {
      * @param opt the name of the option.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.7.0
@@ -682,7 +683,7 @@ public <T> T getParsedOptionValue(final String opt, final Supplier<T> defaultVal
      * @param opt the name of the option.
      * @param defaultValue the default value to return if opt is not set.
      * @param <T> The return type for the method.
-     * @return the value parsed into a particular object.
+     * @return the value parsed into a particular object or the defaultValue if the option is not set.
      * @throws ParseException if there are problems turning the option value into the desired type
      * @see PatternOptionBuilder
      * @since 1.7.0
@@ -691,6 +692,202 @@ public <T> T getParsedOptionValue(final String opt, final T defaultValue) throws
         return getParsedOptionValue(resolveOption(opt), defaultValue);
     }
 
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param opt the name of the option.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or null if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final char opt) throws ParseException {
+        return getParsedOptionValues(String.valueOf(opt));
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param opt the name of the option.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or the defaultValue if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final char opt, final Supplier<T[]> defaultValue) throws ParseException {
+        return getParsedOptionValues(String.valueOf(opt), defaultValue);
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param opt the name of the option.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or the defaultValue if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final char opt, final T[] defaultValue) throws ParseException {
+        return getParsedOptionValues(String.valueOf(opt), defaultValue);
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param option the option.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or null if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final Option option) throws ParseException {
+        return getParsedOptionValues(option, () -> null);
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param option the option.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or the defaultValue if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    @SuppressWarnings("unchecked")
+    public <T> T[] getParsedOptionValues(final Option option, final Supplier<T[]> defaultValue) throws ParseException {
+        if (option == null) {
+            return get(defaultValue);
+        }
+        Class<? extends T> clazz = (Class<? extends T>) option.getType();
+        String[] values = getOptionValues(option);
+        if (values == null) {
+            return get(defaultValue);
+        }
+        T[] result = (T[]) Array.newInstance(clazz, values.length);
+        try {
+            for (int i = 0; i < values.length; i++) {
+                result[i] = clazz.cast(option.getConverter().apply(values[i]));
+            }
+            return result;
+        } catch (final Exception t) {
+            throw ParseException.wrap(t);
+        }
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param option the option.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or the defaultValue if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final Option option, final T[] defaultValue) throws ParseException {
+        return getParsedOptionValues(option, () -> defaultValue);
+    }
+
+    /**
+     * Gets a version of this {@code OptionGroup} converted to an array of a particular type.
+     *
+     * @param optionGroup the option group.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or null if no option in the OptionGroup is set.
+     * @throws ParseException if there are problems turning the selected option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final OptionGroup optionGroup) throws ParseException {
+        return getParsedOptionValues(optionGroup, () -> null);
+    }
+
+    /**
+     * Gets a version of this {@code OptionGroup} converted to an array of a particular type.
+     *
+     * @param optionGroup the option group.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or null if no option in the OptionGroup is set.
+     * @throws ParseException if there are problems turning the selected option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final OptionGroup optionGroup, final Supplier<T[]> defaultValue) throws ParseException {
+        if (optionGroup == null || !optionGroup.isSelected()) {
+            return get(defaultValue);
+        }
+        return getParsedOptionValues(optionGroup.getSelected(), defaultValue);
+    }
+
+    /**
+     * Gets a version of this {@code OptionGroup} converted to an array of a particular type.
+     *
+     * @param optionGroup the option group.
+     * @param defaultValue the default value to return if an option is not selected.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or null if no option in the OptionGroup is set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final OptionGroup optionGroup, final T[] defaultValue) throws ParseException {
+        return getParsedOptionValues(optionGroup, () -> defaultValue);
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param opt the name of the option.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or null if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final String opt) throws ParseException {
+        return getParsedOptionValues(resolveOption(opt));
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param opt the name of the option.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or defaultValues if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final String opt, final Supplier<T[]> defaultValue) throws ParseException {
+        return getParsedOptionValues(resolveOption(opt), defaultValue);
+    }
+
+    /**
+     * Gets a version of this {@code Option} converted to an array of a particular type.
+     *
+     * @param opt the name of the option.
+     * @param defaultValue the default value to return if opt is not set.
+     * @param <T> The array type for the return value.
+     * @return the values parsed into an array of objects or defaultValues if the option is not set.
+     * @throws ParseException if there are problems turning the option value into the desired type
+     * @see PatternOptionBuilder
+     * @since 1.10.0
+     */
+    public <T> T[] getParsedOptionValues(final String opt, final T[] defaultValue) throws ParseException {
+        return getParsedOptionValues(resolveOption(opt), defaultValue);
+    }
+
     /**
      * Handles deprecated options.
      *

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

@@ -713,9 +713,9 @@ public String getValue(final String defaultValue) {
     }
 
     /**
-     * Gets the values of this Option as a String array or null if there are no values.
+     * Gets the values of this Option as a String array or an empty array if there are no values.
      *
-     * @return the values of this Option as a String array or null if there are no values.
+     * @return the values of this Option as a String array or an empty array if there are no values.
      */
     public String[] getValues() {
         return hasNoValues() ? null : values.toArray(EMPTY_STRING_ARRAY);
@@ -731,9 +731,9 @@ public char getValueSeparator() {
     }
 
     /**
-     * Gets the values of this Option as a List or null if there are no values.
+     * Gets the values of this Option as a List.  Will return an empty list if there are no values.
      *
-     * @return the values of this Option as a List or null if there are no values.
+     * @return the values of this Option as a List or an empty List if there are no values.
      */
     public List<String> getValuesList() {
         return values;

src/main/java/org/apache/commons/cli/help/HelpFormatter.java

@@ -147,7 +147,7 @@ protected HelpFormatter(final Builder builder) {
      */
     @Override
     public TableDefinition getTableDefinition(final Iterable<Option> options) {
-        // set up the base TextStyle for the columns configured for the Option opt and arg values..
+        // set up the base TextStyle for the columns configured for the Option opt and arg values.
         final TextStyle.Builder builder = TextStyle.builder().setAlignment(TextStyle.Alignment.LEFT).setIndent(DEFAULT_LEFT_PAD).setScalable(false);
         final List<TextStyle> styles = new ArrayList<>();
         styles.add(builder.get());