diff --git a/src/main/java/org/apache/commons/cli/CommandLine.java b/src/main/java/org/apache/commons/cli/CommandLine.java index 00defd1ab..9a8e56b7f 100644 --- a/src/main/java/org/apache/commons/cli/CommandLine.java +++ b/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 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 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 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 getParsedOptionValue(final char opt, final Supplier defaultValue * @param opt the name of the option. * @param defaultValue the default value to return if opt is not set. * @param 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 getParsedOptionValue(final char opt, final T defaultValue) throws P * * @param option the option. * @param 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 getParsedOptionValue(final Option option) throws ParseException { * @param option the option. * @param defaultValue the default value to return if opt is not set. * @param 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 getParsedOptionValue(final Option option, final Supplier default * @param option the option. * @param defaultValue the default value to return if opt is not set. * @param 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 getParsedOptionValue(final Option option, final T defaultValue) thr * * @param optionGroup the option group. * @param 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 getParsedOptionValue(final OptionGroup optionGroup) throws ParseExc * @param optionGroup the option group. * @param defaultValue the default value to return if opt is not set. * @param 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 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 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 getParsedOptionValue(final OptionGroup optionGroup, final T default * * @param opt the name of the option. * @param 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 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 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 getParsedOptionValue(final String opt, final Supplier defaultVal * @param opt the name of the option. * @param defaultValue the default value to return if opt is not set. * @param 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 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 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[] 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 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[] getParsedOptionValues(final char opt, final Supplier 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 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[] 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 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[] 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 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[] getParsedOptionValues(final Option option, final Supplier defaultValue) throws ParseException { + if (option == null) { + return get(defaultValue); + } + Class clazz = (Class) 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 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[] 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 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[] 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 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[] getParsedOptionValues(final OptionGroup optionGroup, final Supplier 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 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[] 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 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[] 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 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[] getParsedOptionValues(final String opt, final Supplier 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 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[] getParsedOptionValues(final String opt, final T[] defaultValue) throws ParseException { + return getParsedOptionValues(resolveOption(opt), defaultValue); + } + /** * Handles deprecated options. * diff --git a/src/main/java/org/apache/commons/cli/Option.java b/src/main/java/org/apache/commons/cli/Option.java index d2c6f5c7b..b4fb0be17 100644 --- a/src/main/java/org/apache/commons/cli/Option.java +++ b/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 getValuesList() { return values; diff --git a/src/main/java/org/apache/commons/cli/help/HelpFormatter.java b/src/main/java/org/apache/commons/cli/help/HelpFormatter.java index 63cf40592..149a3345f 100644 --- a/src/main/java/org/apache/commons/cli/help/HelpFormatter.java +++ b/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