[CLI-329] Support "Deprecated" CLI Options

Deprecated string looks like: "Option 'c': Deprecated for removal since
2.0: Use X."

Author: garydgregory

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

@@ -51,7 +51,7 @@ public static final class Builder {
         /**
          * Prints an Option to {@link System#out}.
          */
-        static final Consumer<Option> DEPRECATED_HANDLER = o -> System.out.println(o);
+        static final Consumer<Option> DEPRECATED_HANDLER = o -> System.out.println(o.toDeprecatedString());
 
         /** The unrecognized options/arguments */
         private final List<String> args = new LinkedList<>();
@@ -570,7 +570,6 @@ private void handleDeprecated(final Option option) {
         if (deprecatedHandler != null) {
             deprecatedHandler.accept(option);
         }
-
     }
 
     /**

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

@@ -167,23 +167,16 @@ private String toEmpty(final String since) {
         return since != null ? since : EMPTY_STRING;
     }
 
-    public String toShortString() {
-        final StringBuilder builder = new StringBuilder();
-        builder.append("Deprecated");
+    @Override
+    public String toString() {
+        final StringBuilder builder = new StringBuilder("Deprecated");
         if (forRemoval) {
             builder.append(" for removal");
         }
         if (!since.isEmpty()) {
             builder.append(" since ");
             builder.append(since);
         }
-        return builder.toString();
-    }
-
-    @Override
-    public String toString() {
-        final StringBuilder builder = new StringBuilder();
-        builder.append(toShortString());
         if (!description.isEmpty()) {
             builder.append(": ");
             builder.append(description);

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

@@ -25,16 +25,13 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import java.util.Objects;
 
 /**
- * Describes a single command-line option. It maintains information regarding the short-name of the option, the
- * long-name, if any exists, a flag indicating if an argument is required for this option, and a self-documenting
- * description of the option.
+ * Describes a single command-line option. It maintains information regarding the short-name of the option, the long-name, if any exists, a flag indicating if
+ * an argument is required for this option, and a self-documenting description of the option.
  * <p>
- * An Option is not created independently, but is created through an instance of {@link Options}. An Option is required
- * to have at least a short or a long-name.
+ * An Option is not created independently, but is created through an instance of {@link Options}. An Option is required to have at least a short or a long-name.
  * </p>
  * <p>
- * <b>Note:</b> once an {@link Option} has been added to an instance of {@link Options}, its required flag cannot be
- * changed.
+ * <b>Note:</b> once an {@link Option} has been added to an instance of {@link Options}, its required flag cannot be changed.
  * </p>
  *
  * @see org.apache.commons.cli.Options
@@ -126,7 +123,9 @@ public Option build() {
         /**
          * Sets the converter for the option.
          *
-         * <p>Note: see {@link TypeHandler} for serialization discussion.</p>
+         * <p>
+         * Note: see {@link TypeHandler} for serialization discussion.
+         * </p>
          *
          * @param converter the Converter to use.
          * @return this builder, to allow method chaining.
@@ -300,7 +299,7 @@ public Builder valueSeparator() {
          * Option opt = Option.builder("D").hasArgs().valueSeparator('=').build();
          * Options options = new Options();
          * options.addOption(opt);
-         * String[] args = {"-Dkey=value"};
+         * String[] args = { "-Dkey=value" };
          * CommandLineParser parser = new DefaultParser();
          * CommandLine line = parser.parse(options, args);
          * String propertyName = line.getOptionValues("D")[0]; // will be "key"
@@ -389,7 +388,7 @@ public static Builder builder(final String option) {
     /** The character that is the value separator. */
     private char valuesep;
 
-    /** The explicit converter for this option.  May be null. */
+    /** The explicit converter for this option. May be null. */
     private transient Converter<?, ?> converter;
 
     /**
@@ -414,8 +413,8 @@ private Option(final Builder builder) {
     /**
      * Creates an Option using the specified parameters.
      *
-     * @param option short representation of the option.
-     * @param hasArg specifies whether the Option takes an argument or not.
+     * @param option      short representation of the option.
+     * @param hasArg      specifies whether the Option takes an argument or not.
      * @param description describes the function of the option.
      *
      * @throws IllegalArgumentException if there are any non valid Option characters in {@code opt}.
@@ -427,7 +426,7 @@ public Option(final String option, final boolean hasArg, final String descriptio
     /**
      * Creates an Option using the specified parameters. The option does not take an argument.
      *
-     * @param option short representation of the option.
+     * @param option      short representation of the option.
      * @param description describes the function of the option.
      *
      * @throws IllegalArgumentException if there are any non valid Option characters in {@code opt}.
@@ -439,9 +438,9 @@ public Option(final String option, final String description) throws IllegalArgum
     /**
      * Creates an Option using the specified parameters.
      *
-     * @param option short representation of the option.
-     * @param longOption the long representation of the option.
-     * @param hasArg specifies whether the Option takes an argument or not.
+     * @param option      short representation of the option.
+     * @param longOption  the long representation of the option.
+     * @param hasArg      specifies whether the Option takes an argument or not.
      * @param description describes the function of the option.
      *
      * @throws IllegalArgumentException if there are any non valid Option characters in {@code opt}.
@@ -469,8 +468,8 @@ boolean acceptsArg() {
     }
 
     /**
-     * Adds the value to this Option. If the number of arguments is greater than zero and there is enough space in the list
-     * then add the value. Otherwise, throw a runtime exception.
+     * Adds the value to this Option. If the number of arguments is greater than zero and there is enough space in the list then add the value. Otherwise, throw
+     * a runtime exception.
      *
      * @param value The value to be added to this Option.
      *
@@ -485,8 +484,7 @@ private void add(final String value) {
     }
 
     /**
-     * This method is not intended to be used. It was a piece of internal API that was made public in 1.0. It currently
-     * throws an UnsupportedOperationException.
+     * This method is not intended to be used. It was a piece of internal API that was made public in 1.0. It currently throws an UnsupportedOperationException.
      *
      * @param value the value to add.
      * @return always throws an {@link UnsupportedOperationException}.
@@ -496,7 +494,7 @@ private void add(final String value) {
     @Deprecated
     public boolean addValue(final String value) {
         throw new UnsupportedOperationException(
-            "The addValue method is not intended for client use. " + "Subclasses should use the addValueForProcessing method instead. ");
+                "The addValue method is not intended for client use. " + "Subclasses should use the addValueForProcessing method instead. ");
     }
 
     /**
@@ -512,8 +510,7 @@ void addValueForProcessing(final String value) {
     }
 
     /**
-     * Clears the Option values. After a parse is complete, these are left with data in them and they need clearing if
-     * another parse is done.
+     * Clears the Option values. After a parse is complete, these are left with data in them and they need clearing if another parse is done.
      *
      * See: <a href="https://issues.apache.org/jira/browse/CLI-71">CLI-71</a>
      */
@@ -566,9 +563,8 @@ public String getArgName() {
      * Gets the number of argument values this Option can take.
      *
      * <p>
-     * A value equal to the constant {@link #UNINITIALIZED} (= -1) indicates the number of arguments has not been specified.
-     * A value equal to the constant {@link #UNLIMITED_VALUES} (= -2) indicates that this options takes an unlimited amount
-     * of values.
+     * A value equal to the constant {@link #UNINITIALIZED} (= -1) indicates the number of arguments has not been specified. A value equal to the constant
+     * {@link #UNLIMITED_VALUES} (= -2) indicates that this options takes an unlimited amount of values.
      * </p>
      *
      * @return num the number of argument values.
@@ -609,8 +605,7 @@ public String getDescription() {
     }
 
     /**
-     * Gets the id of this Option. This is only set when the Option shortOpt is a single character. This is used for
-     * switch statements.
+     * Gets the id of this Option. This is only set when the Option shortOpt is a single character. This is used for switch statements.
      *
      * @return the id of this Option.
      */
@@ -619,8 +614,7 @@ public int getId() {
     }
 
     /**
-     * Gets the 'unique' Option identifier.  This is the option value if set or the long value
-     * if the options value is not set.
+     * Gets the 'unique' Option identifier. This is the option value if set or the long value if the options value is not set.
      *
      * @return the 'unique' Option identifier.
      * @since 1.7.0
@@ -642,8 +636,8 @@ public String getLongOpt() {
     /**
      * Gets the name of this Option.
      *
-     * It is this String which can be used with {@link CommandLine#hasOption(String opt)} and
-     * {@link CommandLine#getOptionValue(String opt)} to check for existence and argument.
+     * It is this String which can be used with {@link CommandLine#hasOption(String opt)} and {@link CommandLine#getOptionValue(String opt)} to check for
+     * existence and argument.
      *
      * @return The name of this option.
      */
@@ -811,9 +805,8 @@ public boolean isRequired() {
     }
 
     /**
-     * Processes the value. If this Option has a value separator the value will have to be parsed into individual tokens.
-     * When n-1 tokens have been processed and there are more value separators in the value, parsing is ceased and the
-     * remaining characters are added as a single token.
+     * Processes the value. If this Option has a value separator the value will have to be parsed into individual tokens. When n-1 tokens have been processed
+     * and there are more value separators in the value, parsing is ceased and the remaining characters are added as a single token.
      *
      * @param value The String to be processed.
      *
@@ -945,8 +938,7 @@ public void setType(final Class<?> type) {
     /**
      * Sets the type of this Option.
      * <p>
-     * <b>Note:</b> this method is kept for binary compatibility and the input type is supposed to be a {@link Class}
-     * object.
+     * <b>Note:</b> this method is kept for binary compatibility and the input type is supposed to be a {@link Class} object.
      * </p>
      *
      * @param type the type of this Option.
@@ -966,6 +958,21 @@ public void setValueSeparator(final char sep) {
         this.valuesep = sep;
     }
 
+    String toDeprecatedString() {
+        if (!isDeprecated()) {
+            return "";
+        }
+        final StringBuilder buf = new StringBuilder().append("Option '");
+        buf.append(option).append('\'');
+        if (longOption != null) {
+            buf.append('\'').append(longOption).append('\'');
+        }
+        if (isDeprecated()) {
+            buf.append(": ").append(deprecated);
+        }
+        return buf.toString();
+    }
+
     /**
      * Creates a String suitable for debugging.
      *
@@ -974,16 +981,15 @@ public void setValueSeparator(final char sep) {
     @Override
     public String toString() {
         final StringBuilder buf = new StringBuilder().append("[ ");
-        if (isDeprecated()) {
-            buf.append(deprecated.toShortString());
-            buf.append(' ');
-        }
-        buf.append("option: ");
+        buf.append("Option ");
         buf.append(option);
         if (longOption != null) {
             buf.append(' ').append(longOption);
         }
-        buf.append(' ');
+        if (isDeprecated()) {
+            buf.append(' ');
+            buf.append(deprecated.toString());
+        }
         if (hasArgs()) {
             buf.append("[ARG...]");
         } else if (hasArg()) {

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

@@ -266,7 +266,6 @@ public void testHashCode() {
 
     @Test
     public void testSerialization() throws IOException, ClassNotFoundException {
-
         final Option o = Option.builder("o").type(TypeHandlerTest.Instantiable.class).build();
         assertEquals(Converter.DEFAULT, o.getConverter());
         Option o2 = roundTrip(o);

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

@@ -17,8 +17,10 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 
 package org.apache.commons.cli;
 
+
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -132,18 +134,25 @@ public void testDuplicateLong() {
     @Test
     public void testDeprecated() {
         final Options opts = new Options();
-        opts.addOption(Option.builder().option("a").deprecated().build());
-        opts.addOption(Option.builder().option("b").build());
-        assertTrue(opts.getOption("a").toString().startsWith("[ Deprecated option:"));
-        assertTrue(opts.getOption("b").toString().startsWith("[ option:"));
+        opts.addOption(Option.builder().option("a").build());
+        opts.addOption(Option.builder().option("b").deprecated().build());
+        opts.addOption(Option.builder().option("c")
+                .deprecated(DeprecatedAttributes.builder().setForRemoval(true).setSince("2.0").setDescription("Use X.").get()).build());
+        // toString()
+        assertTrue(opts.getOption("a").toString().startsWith("[ Option a"));
+        assertTrue(opts.getOption("b").toString().startsWith("[ Option b"));
+        assertTrue(opts.getOption("c").toString().startsWith("[ Option c"));
+        // toDeprecatedString()
+        assertFalse(opts.getOption("a").toDeprecatedString().startsWith("Option a"));
+        assertEquals("Option 'b': Deprecated", opts.getOption("b").toDeprecatedString());
+        assertEquals("Option 'c': Deprecated for removal since 2.0: Use X.", opts.getOption("c").toDeprecatedString());
     }
 
     @Test
     public void testDuplicateSimple() {
         final Options opts = new Options();
         opts.addOption("a", false, "toggle -a");
         opts.addOption("a", true, "toggle -a*");
-
         assertEquals("toggle -a*", opts.getOption("a").getDescription(), "last one in wins");
     }