This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-cli.git
commit 472bdd590a521e975c17a38f254634c4495442a9 Author: Gary D. Gregory <[email protected]> AuthorDate: Tue Oct 7 08:57:31 2025 -0400 Javadoc Reduce vertical whitespace --- .../commons/cli/AlreadySelectedException.java | 10 ++-- .../commons/cli/AmbiguousOptionException.java | 8 +-- .../java/org/apache/commons/cli/BasicParser.java | 8 +-- .../org/apache/commons/cli/CommandLineParser.java | 33 +++++------ .../java/org/apache/commons/cli/Converter.java | 2 +- .../java/org/apache/commons/cli/DefaultParser.java | 44 ++++++++------- .../java/org/apache/commons/cli/GnuParser.java | 8 +-- .../java/org/apache/commons/cli/OptionBuilder.java | 59 ++++++++++---------- .../org/apache/commons/cli/OptionValidator.java | 2 +- .../org/apache/commons/cli/ParseException.java | 14 ++--- src/main/java/org/apache/commons/cli/Parser.java | 38 ++++++------- .../apache/commons/cli/PatternOptionBuilder.java | 6 +- .../java/org/apache/commons/cli/PosixParser.java | 19 ++----- .../java/org/apache/commons/cli/TypeHandler.java | 64 +++++++++++----------- .../commons/cli/UnrecognizedOptionException.java | 8 +-- 15 files changed, 154 insertions(+), 169 deletions(-) diff --git a/src/main/java/org/apache/commons/cli/AlreadySelectedException.java b/src/main/java/org/apache/commons/cli/AlreadySelectedException.java index ec8fdfcc..7603eac5 100644 --- a/src/main/java/org/apache/commons/cli/AlreadySelectedException.java +++ b/src/main/java/org/apache/commons/cli/AlreadySelectedException.java @@ -36,8 +36,8 @@ public class AlreadySelectedException extends ParseException { /** * Constructs a new {@code AlreadySelectedException} for the specified option group. * - * @param optionGroup the option group already selected - * @param option the option that triggered the exception + * @param optionGroup the option group already selected. + * @param option the option that triggered the exception. * @since 1.2 */ public AlreadySelectedException(final OptionGroup optionGroup, final Option option) { @@ -48,7 +48,7 @@ public class AlreadySelectedException extends ParseException { /** * Constructs a new {@code AlreadySelectedException} with the specified detail message. * - * @param message the detail message + * @param message the detail message. */ public AlreadySelectedException(final String message) { this(message, null, null); @@ -63,7 +63,7 @@ public class AlreadySelectedException extends ParseException { /** * Gets the option that was added to the group and triggered the exception. * - * @return the related option + * @return the related option. * @since 1.2 */ public Option getOption() { @@ -73,7 +73,7 @@ public class AlreadySelectedException extends ParseException { /** * Gets the option group where another option has been selected. * - * @return the related option group + * @return the related option group. * @since 1.2 */ public OptionGroup getOptionGroup() { diff --git a/src/main/java/org/apache/commons/cli/AmbiguousOptionException.java b/src/main/java/org/apache/commons/cli/AmbiguousOptionException.java index 0e2999eb..d38a81cc 100644 --- a/src/main/java/org/apache/commons/cli/AmbiguousOptionException.java +++ b/src/main/java/org/apache/commons/cli/AmbiguousOptionException.java @@ -42,7 +42,6 @@ public class AmbiguousOptionException extends UnrecognizedOptionException { final StringBuilder buf = new StringBuilder("Ambiguous option: '"); buf.append(option); buf.append("' (could be: "); - final Iterator<String> it = matchingOptions.iterator(); while (it.hasNext()) { buf.append(Char.APOS); @@ -53,7 +52,6 @@ public class AmbiguousOptionException extends UnrecognizedOptionException { } } buf.append(")"); - return buf.toString(); } @@ -63,8 +61,8 @@ public class AmbiguousOptionException extends UnrecognizedOptionException { /** * Constructs a new AmbiguousOptionException. * - * @param option the partial option name - * @param matchingOptions the options matching the name + * @param option the partial option name. + * @param matchingOptions the options matching the name. */ public AmbiguousOptionException(final String option, final Collection<String> matchingOptions) { super(createMessage(option, matchingOptions), option); @@ -74,7 +72,7 @@ public class AmbiguousOptionException extends UnrecognizedOptionException { /** * Gets the options matching the partial name. * - * @return a collection of options matching the name + * @return a collection of options matching the name. */ public Collection<String> getMatchingOptions() { return matchingOptions; diff --git a/src/main/java/org/apache/commons/cli/BasicParser.java b/src/main/java/org/apache/commons/cli/BasicParser.java index 643b1956..5db74f44 100644 --- a/src/main/java/org/apache/commons/cli/BasicParser.java +++ b/src/main/java/org/apache/commons/cli/BasicParser.java @@ -21,7 +21,7 @@ package org.apache.commons.cli; * The class BasicParser provides a very simple implementation of the {@link Parser#flatten(Options,String[],boolean) * flatten} method. * - * @deprecated since 1.3, use the {@link DefaultParser} instead + * @deprecated since 1.3, use the {@link DefaultParser} instead. */ @Deprecated public class BasicParser extends Parser { @@ -43,14 +43,14 @@ public class BasicParser extends Parser { * <strong>Note:</strong> {@code options} and {@code stopAtNonOption} are not used in this {@code flatten} method. * </p> * - * @param options The command line {@link Options} - * @param arguments The command line arguments to be parsed + * @param options The command line {@link Options}. + * @param arguments The command line arguments to be parsed. * @param stopAtNonOption Specifies whether to stop flattening when an non option is found. * @return The {@code arguments} String array. */ @Override protected String[] flatten(@SuppressWarnings("unused") final Options options, final String[] arguments, - @SuppressWarnings("unused") final boolean stopAtNonOption) { + @SuppressWarnings("unused") final boolean stopAtNonOption) { // just echo the arguments return arguments; } diff --git a/src/main/java/org/apache/commons/cli/CommandLineParser.java b/src/main/java/org/apache/commons/cli/CommandLineParser.java index 56c79950..08f04922 100644 --- a/src/main/java/org/apache/commons/cli/CommandLineParser.java +++ b/src/main/java/org/apache/commons/cli/CommandLineParser.java @@ -26,9 +26,9 @@ public interface CommandLineParser { /** * Parses the arguments according to the specified options. * - * @param options the specified Options - * @param arguments the command line arguments - * @return the list of atomic option and value tokens + * @param options the specified Options. + * @param arguments the command line arguments. + * @return the list of atomic option and value tokens. * @throws ParseException if there are any problems encountered while parsing the command line tokens. */ CommandLine parse(Options options, String[] arguments) throws ParseException; @@ -36,10 +36,10 @@ public interface CommandLineParser { /** * Parses the arguments according to the specified options and properties. * - * @param options the specified Options - * @param arguments the command line arguments - * @param properties command line option name-value pairs - * @return the list of atomic option and value tokens + * @param options the specified Options. + * @param arguments the command line arguments. + * @param properties command line option name-value pairs. + * @return the list of atomic option and value tokens. * @throws ParseException if there are any problems encountered while parsing the command line tokens. */ /* @@ -51,13 +51,13 @@ public interface CommandLineParser { /** * Parses the arguments according to the specified options. * - * @param options the specified Options - * @param arguments the command line arguments + * @param options the specified Options. + * @param arguments the command line arguments. * @param stopAtNonOption if {@code true} an unrecognized argument stops the parsing and the remaining arguments * are added to the {@link CommandLine}s args list. If {@code false} an unrecognized argument triggers a * ParseException. * - * @return the list of atomic option and value tokens + * @return the list of atomic option and value tokens. * @throws ParseException if there are any problems encountered while parsing the command line tokens. */ CommandLine parse(Options options, String[] arguments, boolean stopAtNonOption) throws ParseException; @@ -65,19 +65,14 @@ public interface CommandLineParser { /** * Parses the arguments according to the specified options and properties. * - * @param options the specified Options - * @param arguments the command line arguments - * @param properties command line option name-value pairs + * @param options the specified Options. + * @param arguments the command line arguments. + * @param properties command line option name-value pairs. * @param stopAtNonOption if {@code true} an unrecognized argument stops the parsing and the remaining arguments * are added to the {@link CommandLine}s args list. If {@code false} an unrecognized argument triggers a * ParseException. * - * @return the list of atomic option and value tokens + * @return the list of atomic option and value tokens. * @throws ParseException if there are any problems encountered while parsing the command line tokens. */ - /* - * To maintain binary compatibility, this is commented out. It is still in the abstract Parser class, so most users will - * still reap the benefit. CommandLine parse(Options options, String[] arguments, Properties properties, boolean - * stopAtNonOption) throws ParseException; - */ } diff --git a/src/main/java/org/apache/commons/cli/Converter.java b/src/main/java/org/apache/commons/cli/Converter.java index 25e21199..7e92c32f 100644 --- a/src/main/java/org/apache/commons/cli/Converter.java +++ b/src/main/java/org/apache/commons/cli/Converter.java @@ -81,7 +81,7 @@ public interface Converter<T, E extends Exception> { /** * Applies the conversion function to the String argument. * - * @param string the String to convert + * @param string the String to convert. * @return the Object from the conversion. * @throws E on error. */ diff --git a/src/main/java/org/apache/commons/cli/DefaultParser.java b/src/main/java/org/apache/commons/cli/DefaultParser.java index 63441666..0eb03a19 100644 --- a/src/main/java/org/apache/commons/cli/DefaultParser.java +++ b/src/main/java/org/apache/commons/cli/DefaultParser.java @@ -64,9 +64,9 @@ public class DefaultParser implements CommandLineParser { /** * Constructs a new {@code Builder} for a {@code DefaultParser} instance. - * - * Both allowPartialMatching and stripLeadingAndTrailingQuotes are true by default, - * mimicking the argument-less constructor. + * <p> + * Both allowPartialMatching and stripLeadingAndTrailingQuotes are true by default, mimicking the argument-less constructor. + * </p> */ private Builder() { } @@ -96,10 +96,12 @@ public class DefaultParser implements CommandLineParser { /** * Sets if partial matching of long options is supported. - * + * <p> * By "partial matching" we mean that given the following code: + * </p> * * <pre> + * * { * @code * final Options options = new Options(); @@ -108,12 +110,13 @@ public class DefaultParser implements CommandLineParser { * options.addOption(new Option("o", "option", true, "Turn on option with argument.")); * } * </pre> - * - * If "partial matching" is turned on, {@code -de} only matches the {@code "debug"} option. However, with - * "partial matching" disabled, {@code -de} would enable both {@code debug} as well as {@code extract} + * <p> + * If "partial matching" is turned on, {@code -de} only matches the {@code "debug"} option. However, with "partial matching" disabled, {@code -de} would + * enable both {@code debug} as well as {@code extract} + * </p> * * @param allowPartialMatching whether to allow partial matching of long options. - * @return {@code this} instance.. + * @return {@code this} instance. * @since 1.5.0 */ public Builder setAllowPartialMatching(final boolean allowPartialMatching) { @@ -136,13 +139,14 @@ public class DefaultParser implements CommandLineParser { /** * Sets if balanced leading and trailing double quotes should be stripped from option arguments. * - * If "stripping of balanced leading and trailing double quotes from option arguments" is true, - * the outermost balanced double quotes of option arguments values will be removed. - * For example, {@code -o '"x"'} getValue() will return {@code x}, instead of {@code "x"} - * - * If "stripping of balanced leading and trailing double quotes from option arguments" is null, - * then quotes will be stripped from option values separated by space from the option, but - * kept in other cases, which is the historic behavior. + * <p> + * If "stripping of balanced leading and trailing double quotes from option arguments" is true, the outermost balanced double quotes of option arguments + * values will be removed. For example, {@code -o '"x"'} getValue() will return {@code x}, instead of {@code "x"} + * </p> + * <p> + * If "stripping of balanced leading and trailing double quotes from option arguments" is null, then quotes will be stripped from option values + * separated by space from the option, but kept in other cases, which is the historic behavior. + * </p> * * @param stripLeadingAndTrailingQuotes whether balanced leading and trailing double quotes should be stripped from option arguments. * @return {@code this} instance. @@ -248,8 +252,9 @@ public class DefaultParser implements CommandLineParser { /** * Creates a new DefaultParser instance with partial matching enabled. - * + * <p> * By "partial matching" we mean that given the following code: + * </p> * * <pre> * { @@ -273,9 +278,9 @@ public class DefaultParser implements CommandLineParser { /** * Create a new DefaultParser instance with the specified partial matching policy. - * + * <p> * By "partial matching" we mean that given the following code: - * + * </p> * <pre> * { * @code @@ -285,10 +290,11 @@ public class DefaultParser implements CommandLineParser { * options.addOption(new Option("o", "option", true, "Turn on option with argument.")); * } * </pre> - * + * <p> * with "partial matching" turned on, {@code -de} only matches the {@code "debug"} option. However, with * "partial matching" disabled, {@code -de} would enable both {@code debug} as well as {@code extract} * options. + * </p> * * @param allowPartialMatching if partial matching of long options shall be enabled */ diff --git a/src/main/java/org/apache/commons/cli/GnuParser.java b/src/main/java/org/apache/commons/cli/GnuParser.java index 06cab8b5..fdbe7c4d 100644 --- a/src/main/java/org/apache/commons/cli/GnuParser.java +++ b/src/main/java/org/apache/commons/cli/GnuParser.java @@ -24,7 +24,7 @@ import java.util.List; * The class GnuParser provides an implementation of the {@link Parser#flatten(Options, String[], boolean) flatten} * method. * - * @deprecated since 1.3, use the {@link DefaultParser} instead + * @deprecated since 1.3, use the {@link DefaultParser} instead. */ @Deprecated public class GnuParser extends Parser { @@ -47,8 +47,8 @@ public class GnuParser extends Parser { * * @param options The Options to parse the arguments by. * @param arguments The arguments that have to be flattened. - * @param stopAtNonOption specifies whether to stop flattening when a non option has been encountered - * @return a String array of the flattened arguments + * @param stopAtNonOption specifies whether to stop flattening when a non option has been encountered. + * @return a String array of the flattened arguments. */ @Override protected String[] flatten(final Options options, final String[] arguments, final boolean stopAtNonOption) { @@ -84,7 +84,6 @@ public class GnuParser extends Parser { } else { tokens.add(arg); } - if (eatTheRest) { for (i++; i < arguments.length; i++) { // NOPMD tokens.add(arguments[i]); @@ -92,7 +91,6 @@ public class GnuParser extends Parser { } } } - return tokens.toArray(Util.EMPTY_STRING_ARRAY); } } diff --git a/src/main/java/org/apache/commons/cli/OptionBuilder.java b/src/main/java/org/apache/commons/cli/OptionBuilder.java index 41ff9b63..a4b8cf98 100644 --- a/src/main/java/org/apache/commons/cli/OptionBuilder.java +++ b/src/main/java/org/apache/commons/cli/OptionBuilder.java @@ -26,47 +26,47 @@ package org.apache.commons.cli; * This class is NOT thread safe. See <a href="https://issues.apache.org/jira/browse/CLI-209";>CLI-209</a> * * @since 1.0 - * @deprecated since 1.3, use {@link Option#builder(String)} instead + * @deprecated since 1.3, use {@link Option#builder(String)} instead. */ @Deprecated public final class OptionBuilder { - /** Long option */ + /** Long option. */ private static String longOption; - /** Option description */ + /** Option description. */ private static String description; - /** Argument name */ + /** Argument name. */ private static String argName; - /** Is required? */ + /** Required test. */ private static boolean required; - /** The number of arguments */ + /** The number of arguments. */ private static int argCount = Option.UNINITIALIZED; - /** Option type */ + /** Option type. */ private static Class<?> type; - /** Option can have an optional argument value */ + /** Option can have an optional argument value. */ private static boolean optionalArg; - /** Value separator for argument value */ + /** Value separator for argument value. */ private static char valueSeparator; - /** Option builder instance */ + /** Option builder instance. */ private static final OptionBuilder INSTANCE = new OptionBuilder(); static { - // ensure the consistency of the initial values + // ensure the consistency of the initial values. reset(); } /** - * Creates an Option using the current settings + * Creates an Option using the current settings. * - * @return the Option instance + * @return the Option instance. * @throws IllegalArgumentException if {@code longOpt} has not been set. */ public static Option create() throws IllegalArgumentException { @@ -74,15 +74,14 @@ public final class OptionBuilder { reset(); throw new IllegalStateException("must specify longopt"); } - return create(null); } /** * Creates an Option using the current settings and with the specified Option {@code char}. * - * @param opt the character representation of the Option - * @return the Option instance + * @param opt the character representation of the Option. + * @return the Option instance. * @throws IllegalArgumentException if {@code opt} is not a valid character. See Option. */ public static Option create(final char opt) throws IllegalArgumentException { @@ -92,8 +91,8 @@ public final class OptionBuilder { /** * Creates an Option using the current settings and with the specified Option {@code char}. * - * @param opt the {@code String} representation of the Option - * @return the Option instance + * @param opt the {@code String} representation of the Option. + * @return the Option instance. * @throws IllegalArgumentException if {@code opt} is not a valid character. See Option. */ public static Option create(final String opt) throws IllegalArgumentException { @@ -101,7 +100,6 @@ public final class OptionBuilder { try { // create the option option = new Option(opt, description); - // set the option properties option.setLongOpt(longOption); option.setRequired(required); @@ -115,7 +113,6 @@ public final class OptionBuilder { // reset the OptionBuilder properties reset(); } - // return the Option instance return option; } @@ -133,8 +130,8 @@ public final class OptionBuilder { /** * The next Option created will require an argument value if {@code hasArg} is true. * - * @param hasArg if true then the Option has an argument value - * @return the OptionBuilder instance + * @param hasArg if true then the Option has an argument value. + * @return the OptionBuilder instance. */ public static OptionBuilder hasArg(final boolean hasArg) { argCount = hasArg ? 1 : Option.UNINITIALIZED; @@ -144,7 +141,7 @@ public final class OptionBuilder { /** * The next Option created can have unlimited argument values. * - * @return the OptionBuilder instance + * @return the OptionBuilder instance. */ public static OptionBuilder hasArgs() { argCount = Option.UNLIMITED_VALUES; @@ -154,8 +151,8 @@ public final class OptionBuilder { /** * The next Option created can have {@code num} argument values. * - * @param num the number of args that the option can have - * @return the OptionBuilder instance + * @param num the number of args that the option can have. + * @return the OptionBuilder instance. */ public static OptionBuilder hasArgs(final int num) { argCount = num; @@ -165,7 +162,7 @@ public final class OptionBuilder { /** * The next Option can have an optional argument. * - * @return the OptionBuilder instance + * @return the OptionBuilder instance. */ public static OptionBuilder hasOptionalArg() { argCount = 1; @@ -176,7 +173,7 @@ public final class OptionBuilder { /** * The next Option can have an unlimited number of optional arguments. * - * @return the OptionBuilder instance + * @return the OptionBuilder instance. */ public static OptionBuilder hasOptionalArgs() { argCount = Option.UNLIMITED_VALUES; @@ -188,7 +185,7 @@ public final class OptionBuilder { * The next Option can have the specified number of optional arguments. * * @param numArgs the maximum number of optional arguments the next Option created can have. - * @return the OptionBuilder instance + * @return the OptionBuilder instance. */ public static OptionBuilder hasOptionalArgs(final int numArgs) { argCount = numArgs; @@ -199,7 +196,7 @@ public final class OptionBuilder { /** * The next Option created will be required. * - * @return the OptionBuilder instance + * @return the OptionBuilder instance. */ public static OptionBuilder isRequired() { required = true; @@ -209,8 +206,8 @@ public final class OptionBuilder { /** * The next Option created will be required if {@code required} is true. * - * @param newRequired if true then the Option is required - * @return the OptionBuilder instance + * @param newRequired if true then the Option is required. + * @return the OptionBuilder instance. */ public static OptionBuilder isRequired(final boolean newRequired) { required = newRequired; diff --git a/src/main/java/org/apache/commons/cli/OptionValidator.java b/src/main/java/org/apache/commons/cli/OptionValidator.java index e170ccb1..56852f20 100644 --- a/src/main/java/org/apache/commons/cli/OptionValidator.java +++ b/src/main/java/org/apache/commons/cli/OptionValidator.java @@ -108,7 +108,7 @@ final class OptionValidator { * </p><p> * In case {@code opt} is {@code null} no further validation is performed. * - * @param option The option string to validate, may be null + * @param option The option string to validate, may be null. * @throws IllegalArgumentException if the Option is not valid. */ static String validate(final String option) throws IllegalArgumentException { diff --git a/src/main/java/org/apache/commons/cli/ParseException.java b/src/main/java/org/apache/commons/cli/ParseException.java index 785f862b..a8a67f22 100644 --- a/src/main/java/org/apache/commons/cli/ParseException.java +++ b/src/main/java/org/apache/commons/cli/ParseException.java @@ -28,15 +28,15 @@ public class ParseException extends Exception { private static final long serialVersionUID = 9112808380089253192L; /** - * Converts any exception except {@code UnsupportedOperationException} to a {@code ParseException}. - * if {@code e} is an instance of {@code ParseException} it is returned, otherwise a {@code ParseException} is - * created that wraps it. + * Converts any exception except {@code UnsupportedOperationException} to a {@code ParseException}. if {@code e} is an instance of {@code ParseException} it + * is returned, otherwise a {@code ParseException} is created that wraps it. * <p> - * Note: {@code UnsupportedOperationException} are not wrapped. This is to solve a legacy expected exception problem and will be - * removed in the future.</p> + * Note: {@code UnsupportedOperationException} are not wrapped. This is to solve a legacy expected exception problem and will be removed in the future. + * </p> + * * @param e the exception to convert. * @return the ParseException. - * @throws UnsupportedOperationException due to legacy expectations. Will be removed in the future. + * @throws UnsupportedOperationException due to legacy expectations. Will be removed in the future. * @since 1.7.0 */ public static ParseException wrap(final Throwable e) throws UnsupportedOperationException { @@ -53,7 +53,7 @@ public class ParseException extends Exception { /** * Constructs a new {@code ParseException} with the specified detail message. * - * @param message the detail message + * @param message the detail message. */ public ParseException(final String message) { super(message); diff --git a/src/main/java/org/apache/commons/cli/Parser.java b/src/main/java/org/apache/commons/cli/Parser.java index 759827f2..c3065f5e 100644 --- a/src/main/java/org/apache/commons/cli/Parser.java +++ b/src/main/java/org/apache/commons/cli/Parser.java @@ -65,8 +65,8 @@ public abstract class Parser implements CommandLineParser { * * @param opts The Options to parse the arguments by. * @param arguments The arguments that have to be flattened. - * @param stopAtNonOption specifies whether to stop flattening when a non option has been encountered - * @return a String array of the flattened arguments + * @param stopAtNonOption specifies whether to stop flattening when a non option has been encountered. + * @return a String array of the flattened arguments. * @throws ParseException if there are any problems encountered while parsing the command line tokens. */ protected abstract String[] flatten(Options opts, String[] arguments, boolean stopAtNonOption) throws ParseException; @@ -92,9 +92,9 @@ public abstract class Parser implements CommandLineParser { /** * Parses the specified {@code arguments} based on the specified {@link Options}. * - * @param options the {@code Options} - * @param arguments the {@code arguments} - * @return the {@code CommandLine} + * @param options the {@code Options}. + * @param arguments the {@code arguments}. + * @return the {@code CommandLine}. * @throws ParseException if there are any problems encountered while parsing the command line tokens. */ @Override @@ -105,12 +105,12 @@ public abstract class Parser implements CommandLineParser { /** * Parses the specified {@code arguments} based on the specified {@link Options}. * - * @param options the {@code Options} - * @param arguments the {@code arguments} + * @param options the {@code Options}. + * @param arguments the {@code arguments}. * @param stopAtNonOption if {@code true} an unrecognized argument stops the parsing and the remaining arguments * are added to the {@link CommandLine}s args list. If {@code false} an unrecognized argument triggers a * ParseException. - * @return the {@code CommandLine} + * @return the {@code CommandLine}. * @throws ParseException if an error occurs when parsing the arguments. */ @Override @@ -121,10 +121,10 @@ public abstract class Parser implements CommandLineParser { /** * Parse the arguments according to the specified options and properties. * - * @param options the specified Options - * @param arguments the command line arguments - * @param properties command line option name-value pairs - * @return the list of atomic option and value tokens + * @param options the specified Options. + * @param arguments the command line arguments. + * @param properties command line option name-value pairs. + * @return the list of atomic option and value tokens. * @throws ParseException if there are any problems encountered while parsing the command line tokens. * @since 1.1 */ @@ -135,13 +135,13 @@ public abstract class Parser implements CommandLineParser { /** * Parse the arguments according to the specified options and properties. * - * @param options the specified Options - * @param arguments the command line arguments - * @param properties command line option name-value pairs + * @param options the specified Options. + * @param arguments the command line arguments. + * @param properties command line option name-value pairs. * @param stopAtNonOption if {@code true} an unrecognized argument stops the parsing and the remaining arguments * are added to the {@link CommandLine}s args list. If {@code false} an unrecognized argument triggers a * ParseException. - * @return the list of atomic option and value tokens + * @return the list of atomic option and value tokens. * @throws ParseException if there are any problems encountered while parsing the command line tokens. * @since 1.1 */ @@ -211,7 +211,7 @@ public abstract class Parser implements CommandLineParser { * Process the argument values for the specified Option {@code opt} using the values retrieved from the specified * iterator {@code iter}. * - * @param opt The current Option + * @param opt The current Option. * @param iter The iterator over the flattened command line Options. * @throws ParseException if an argument value is required and it is has not been found. */ @@ -241,9 +241,9 @@ public abstract class Parser implements CommandLineParser { * Process the Option specified by {@code arg} using the values retrieved from the specified iterator * {@code iter}. * - * @param arg The String value representing an Option + * @param arg The String value representing an Option. * @param iter The iterator over the flattened command line arguments. - * @throws ParseException if {@code arg} does not represent an Option + * @throws ParseException if {@code arg} does not represent an Option. */ protected void processOption(final String arg, final ListIterator<String> iter) throws ParseException { final boolean hasOption = getOptions().hasOption(arg); diff --git a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java index e62ce40b..43b36abf 100644 --- a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java +++ b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java @@ -113,9 +113,9 @@ public class PatternOptionBuilder { /** * Retrieve the class that {@code ch} represents. * - * @param ch the specified character - * @return The class that {@code ch} represents - * @deprecated use {@link #getValueType(char)} + * @param ch the specified character. + * @return The class that {@code ch} represents. + * @deprecated Use {@link #getValueType(char)}. */ @Deprecated // since="1.7.0" public static Object getValueClass(final char ch) { diff --git a/src/main/java/org/apache/commons/cli/PosixParser.java b/src/main/java/org/apache/commons/cli/PosixParser.java index 6947e130..1434312c 100644 --- a/src/main/java/org/apache/commons/cli/PosixParser.java +++ b/src/main/java/org/apache/commons/cli/PosixParser.java @@ -67,13 +67,12 @@ public class PosixParser extends Parser { * that character prepended with "<strong>-</strong>".</li> * </ul> * - * @param token The current token to be <strong>burst</strong> + * @param token The current token to be <strong>burst</strong>. * @param stopAtNonOption Specifies whether to stop processing at the first non-Option encountered. */ protected void burstToken(final String token, final boolean stopAtNonOption) { for (int i = 1; i < token.length(); i++) { final String ch = String.valueOf(token.charAt(i)); - if (!options.hasOption(ch)) { if (stopAtNonOption) { processNonOptionToken(token.substring(i), true); @@ -84,10 +83,8 @@ public class PosixParser extends Parser { } tokens.add("-" + ch); currentOption = options.getOption(ch); - if (currentOption.hasArg() && token.length() != i + 1) { tokens.add(token.substring(i + 1)); - break; } } @@ -118,8 +115,8 @@ public class PosixParser extends Parser { * to the list of processed tokens.</li> * </ol> * - * @param options The command line {@link Options} - * @param arguments The command line arguments to be parsed + * @param options The command line {@link Options}. + * @param arguments The command line arguments to be parsed. * @param stopAtNonOption Specifies whether to stop flattening when an non option is found. * @return The flattened {@code arguments} String array. */ @@ -141,16 +138,13 @@ public class PosixParser extends Parser { // handle long option --foo or --foo=bar final int pos = DefaultParser.indexOfEqual(token); final String opt = pos == -1 ? token : token.substring(0, pos); // --foo - final List<String> matchingOpts = options.getMatchingOptions(opt); - if (matchingOpts.isEmpty()) { processNonOptionToken(token, stopAtNonOption); } else if (matchingOpts.size() > 1) { throw new AmbiguousOptionException(opt, matchingOpts); } else { currentOption = options.getOption(matchingOpts.get(0)); - tokens.add("--" + currentOption.getLongOpt()); if (pos != -1) { tokens.add(token.substring(pos + 1)); @@ -206,14 +200,13 @@ public class PosixParser extends Parser { * Add the special token "<strong>--</strong>" and the current {@code value} to the processed tokens list. Then add all the * remaining {@code argument} values to the processed tokens list. * - * @param value The current token + * @param value The current token. */ private void processNonOptionToken(final String value, final boolean stopAtNonOption) { if (stopAtNonOption && (currentOption == null || !currentOption.hasArg())) { eatTheRest = true; tokens.add("--"); } - tokens.add(value); } @@ -227,18 +220,16 @@ public class PosixParser extends Parser { * processed tokens list directly. * </p> * - * @param token The current option token + * @param token The current option token. * @param stopAtNonOption Specifies whether flattening should halt at the first non option. */ private void processOptionToken(final String token, final boolean stopAtNonOption) { if (stopAtNonOption && !options.hasOption(token)) { eatTheRest = true; } - if (options.hasOption(token)) { currentOption = options.getOption(token); } - tokens.add(token); } } diff --git a/src/main/java/org/apache/commons/cli/TypeHandler.java b/src/main/java/org/apache/commons/cli/TypeHandler.java index 4685f403..9795de45 100644 --- a/src/main/java/org/apache/commons/cli/TypeHandler.java +++ b/src/main/java/org/apache/commons/cli/TypeHandler.java @@ -44,15 +44,15 @@ public class TypeHandler { */ private static final TypeHandler DEFAULT = new TypeHandler(); - /** Value of hex conversion of strings */ + /** Value of hex conversion of strings. */ private static final int HEX_RADIX = 16; /** * Returns the class whose name is {@code className}. * - * @param className the class name - * @return The class if it is found - * @throws ParseException if the class could not be found + * @param className the class name. + * @return The class if it is found. + * @throws ParseException if the class could not be found. */ public static Class<?> createClass(final String className) throws ParseException { return createValue(className, Class.class); @@ -64,7 +64,7 @@ public class TypeHandler { * This method is not yet implemented and always throws an {@link UnsupportedOperationException}. * </p> * - * @param string the date string + * @param string the date string. * @return The date if {@code string} is a valid date string, otherwise return null. */ public static Date createDate(final String string) { @@ -84,7 +84,7 @@ public class TypeHandler { /** * Returns the File represented by {@code string}. * - * @param string the File location + * @param string the File location. * @return The file represented by {@code string}. */ public static File createFile(final String string) { @@ -98,10 +98,10 @@ public class TypeHandler { * This method is not yet implemented and always throws an {@link UnsupportedOperationException}. * </p> * - * @param string the paths to the files + * @param string the paths to the files. * @return The File[] represented by {@code string}. - * @throws UnsupportedOperationException always - * @deprecated with no replacement + * @throws UnsupportedOperationException always. + * @deprecated Without replacement. */ @Deprecated // since 1.7.0 public static File[] createFiles(final String string) { @@ -113,9 +113,9 @@ public class TypeHandler { /** * Creates a number from a String. If a '.' is present, it creates a Double, otherwise a Long. * - * @param string the value - * @return the number represented by {@code string} - * @throws ParseException if {@code string} is not a number + * @param string the value. + * @return the number represented by {@code string}. + * @throws ParseException if {@code string} is not a number. */ @Deprecated // since 1.7.0 public static Number createNumber(final String string) throws ParseException { @@ -125,10 +125,10 @@ public class TypeHandler { /** * Creates an Object from the class name and empty constructor. * - * @param className the argument value - * @return the initialized object - * @throws ParseException if the class could not be found or the object could not be created - * @deprecated use {@link #createValue(String, Class)} + * @param className the argument value. + * @return the initialized object. + * @throws ParseException if the class could not be found or the object could not be created. + * @deprecated Use {@link #createValue(String, Class)}. */ @Deprecated // since 1.7.0 public static Object createObject(final String className) throws ParseException { @@ -138,9 +138,9 @@ public class TypeHandler { /** * Creates the URL represented by {@code string}. * - * @param string the URL string - * @return The URL in {@code string} is well-formed - * @throws ParseException if the URL in {@code string} is not well-formed + * @param string the URL string. + * @return The URL in {@code string} is well-formed. + * @throws ParseException if the URL in {@code string} is not well-formed. */ public static URL createURL(final String string) throws ParseException { return createValue(string, URL.class); @@ -149,9 +149,9 @@ public class TypeHandler { /** * Creates the @code Object} of type {@code clazz} with the value of {@code string}. * - * @param string the command line value - * @param clazz the class representing the type of argument - * @param <T> type of argument + * @param string the command line value. + * @param clazz the class representing the type of argument. + * @param <T> type of argument. * @return The instance of {@code clazz} initialized with the value of {@code string}. * @throws ParseException if the value creation for the given class threw an exception. */ @@ -166,11 +166,11 @@ public class TypeHandler { /** * Creates the {@code Object} of type {@code obj} with the value of {@code string}. * - * @param string the command line value - * @param obj the type of argument + * @param string the command line value. + * @param obj the type of argument. * @return The instance of {@code obj} initialized with the value of {@code string}. - * @throws ParseException if the value creation for the given object type failed - * @deprecated use {@link #createValue(String, Class)} + * @throws ParseException if the value creation for the given object type failed. + * @deprecated Use {@link #createValue(String, Class)}. */ @Deprecated // since 1.7.0 public static Object createValue(final String string, final Object obj) throws ParseException { @@ -180,9 +180,9 @@ public class TypeHandler { /** * Delegates to {@link #createValue(String, Class)} throwing IllegalArgumentException instead of ParseException. * - * @param string the command line value - * @param clazz the class representing the type of argument - * @param <T> type of argument + * @param string the command line value. + * @param clazz the class representing the type of argument. + * @param <T> type of argument. * @return The instance of {@code clazz} initialized with the value of {@code string}. * @throws IllegalArgumentException if the value creation for the given class threw an exception. */ @@ -207,10 +207,10 @@ public class TypeHandler { /** * Returns the opened FileInputStream represented by {@code string}. * - * @param string the file location + * @param string the file location. * @return The file input stream represented by {@code string}. - * @throws ParseException if the file is not exist or not readable - * @deprecated use {@link #createValue(String, Class)} + * @throws ParseException if the file is not exist or not readable. + * @deprecated Use {@link #createValue(String, Class)}. */ @Deprecated // since 1.7.0 public static FileInputStream openFile(final String string) throws ParseException { diff --git a/src/main/java/org/apache/commons/cli/UnrecognizedOptionException.java b/src/main/java/org/apache/commons/cli/UnrecognizedOptionException.java index 87d56883..49f0ed29 100644 --- a/src/main/java/org/apache/commons/cli/UnrecognizedOptionException.java +++ b/src/main/java/org/apache/commons/cli/UnrecognizedOptionException.java @@ -33,7 +33,7 @@ public class UnrecognizedOptionException extends ParseException { /** * Constructs a new {@code UnrecognizedArgumentException} with the specified detail message. * - * @param message the detail message + * @param message the detail message. */ public UnrecognizedOptionException(final String message) { this(message, null); @@ -42,8 +42,8 @@ public class UnrecognizedOptionException extends ParseException { /** * Constructs a new {@code UnrecognizedArgumentException} with the specified option and detail message. * - * @param message the detail message - * @param option the unrecognized option + * @param message the detail message. + * @param option the unrecognized option. * @since 1.2 */ public UnrecognizedOptionException(final String message, final String option) { @@ -54,7 +54,7 @@ public class UnrecognizedOptionException extends ParseException { /** * Gets the unrecognized option. * - * @return the related option + * @return the related option. * @since 1.2 */ public String getOption() {
