From a955ec39a3ea28c07a8c32315acfa8e6ebc2f4ba Mon Sep 17 00:00:00 2001
From: Claude Warren <claude@xenei.com>
Date: Sat, 11 May 2024 16:34:50 +0200
Subject: [PATCH 1/4] added ability to display deprecation information in help
 output

---
 .../org/apache/commons/cli/HelpFormatter.java | 47 +++++++++------
 .../apache/commons/cli/HelpFormatterTest.java | 59 +++++++++++++++++++
 2 files changed, 87 insertions(+), 19 deletions(-)

diff --git a/src/main/java/org/apache/commons/cli/HelpFormatter.java b/src/main/java/org/apache/commons/cli/HelpFormatter.java
index 539e18ceb..7f3e9aee0 100644
--- a/src/main/java/org/apache/commons/cli/HelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/HelpFormatter.java
@@ -30,6 +30,8 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import java.util.Iterator;
 import java.util.List;
 import java.util.Objects;
+import java.util.function.Function;
+import java.util.function.BiFunction;
 import java.util.function.Supplier;
 
 /**
@@ -74,10 +76,12 @@ public static final class Builder implements Supplier<HelpFormatter> {
         // TODO All other instance HelpFormatter instance variables.
         // Make HelpFormatter immutable for 2.0
 
+        private static final BiFunction<String, Option,String> DEFAULT_DEPRECATED_FORMAT = (d,o) -> "[Deprecated] "+d;
+
         /**
-         * Whether to show deprecated options.
+         * Formatter for deprecated options.
          */
-        private boolean showDeprecated;
+        private BiFunction<String,Option,String> deprecatedFormatFunc;
 
         /**
          * The output PrintWriter, defaults to wrapping {@link System#out}.
@@ -86,7 +90,7 @@ public static final class Builder implements Supplier<HelpFormatter> {
 
         @Override
         public HelpFormatter get() {
-            return new HelpFormatter(showDeprecated, printStream);
+            return new HelpFormatter(deprecatedFormatFunc, printStream);
         }
 
         /**
@@ -103,14 +107,23 @@ public Builder setPrintWriter(final PrintWriter printWriter) {
         /**
          * Sets whether to show deprecated options.
          *
-         * @param showDeprecated Whether to show deprecated options.
+         * @param useDefaultFormat if {@code true} use the default format, otherwise clear the formatter.
          * @return this.
          */
-        public Builder setShowDeprecated(final boolean showDeprecated) {
-            this.showDeprecated = showDeprecated;
-            return this;
+        public Builder setShowDeprecated(final boolean useDefaultFormat) {
+            return setShowDeprecated(useDefaultFormat ? DEFAULT_DEPRECATED_FORMAT : null);
         }
 
+        /**
+         * Sets whether to show deprecated options.
+         *
+         * @param showDeprecatedFunc Specify the format for the deprecated options.
+         * @return this.
+         */
+        public Builder setShowDeprecated(final BiFunction<String,Option,String> showDeprecatedFunc) {
+            this.deprecatedFormatFunc = showDeprecatedFunc;
+            return this;
+        }
     }
 
     /**
@@ -250,9 +263,9 @@ private static PrintWriter createDefaultPrintWriter() {
     protected Comparator<Option> optionComparator = new OptionComparator();
 
     /**
-     * Whether to show deprecated options.
+     * BiFunction to format the description for a deprecated option.
      */
-    private final boolean showDeprecated;
+    private final BiFunction<String,Option,String> deprecatedFormatFunc;
 
     /**
      * Where to print help.
@@ -268,17 +281,17 @@ private static PrintWriter createDefaultPrintWriter() {
      * Constructs a new instance.
      */
     public HelpFormatter() {
-        this(false, createDefaultPrintWriter());
+        this(null, createDefaultPrintWriter());
     }
 
     /**
      * Constructs a new instance.
      * @param printStream TODO
      */
-    private HelpFormatter(final boolean showDeprecated, final PrintWriter printStream) {
+    private HelpFormatter(final BiFunction<String, Option,String> deprecatedFormatFunc, final PrintWriter printStream) {
         // TODO All other instance HelpFormatter instance variables.
         // Make HelpFormatter immutable for 2.0
-        this.showDeprecated = showDeprecated;
+        this.deprecatedFormatFunc = deprecatedFormatFunc;
         this.printWriter = printStream;
     }
 
@@ -778,13 +791,9 @@ protected StringBuffer renderOptions(final StringBuffer sb, final int width, fin
             }
             optBuf.append(dpad);
             final int nextLineTabStop = max + descPad;
-            if (showDeprecated && option.isDeprecated()) {
-                optBuf.append("[Deprecated]");
-            }
-            if (option.getDescription() != null) {
-                if (showDeprecated && option.isDeprecated()) {
-                    optBuf.append(' ');
-                }
+            if (deprecatedFormatFunc != null && option.isDeprecated()) {
+                optBuf.append(deprecatedFormatFunc.apply(option.getDescription()==null?"":option.getDescription(), option).trim());
+            } else if (option.getDescription() != null) {
                 optBuf.append(option.getDescription());
             }
             renderWrappedText(sb, width, nextLineTabStop, optBuf.toString());
diff --git a/src/test/java/org/apache/commons/cli/HelpFormatterTest.java b/src/test/java/org/apache/commons/cli/HelpFormatterTest.java
index bf380caa3..b2a9b3531 100644
--- a/src/test/java/org/apache/commons/cli/HelpFormatterTest.java
+++ b/src/test/java/org/apache/commons/cli/HelpFormatterTest.java
@@ -24,9 +24,15 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import java.io.ByteArrayOutputStream;
 import java.io.PrintWriter;
 import java.io.StringWriter;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Stream;
 
 import org.apache.commons.cli.HelpFormatter.Builder;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
 /**
  * Test case for the HelpFormatter class.
@@ -484,6 +490,59 @@ public void testPrintOptions() {
         assertEquals(expected, sb.toString(), "multiple wrapped options");
     }
 
+    @ParameterizedTest
+    @MethodSource("deprecatedOptionsProvider")
+    public void testPrintDeprecatedOptions(HelpFormatter hf, Option option, String expectedTxt) {
+        final StringBuffer sb = new StringBuffer();
+
+        final int leftPad = 1;
+        final int descPad = 3;
+        final String lpad = hf.createPadding(leftPad);
+        final String dpad = hf.createPadding(descPad);
+        Options options;
+        String expected = expected = lpad + "-a,--aaa";
+
+        options = new Options().addOption(option);
+        if (expectedTxt.length() > 0) {
+            expected = expected + dpad + expectedTxt;
+        }
+        hf.renderOptions(sb, 160, options, leftPad, descPad);
+        assertEquals(expected, sb.toString());
+    }
+
+    static Stream<Arguments> deprecatedOptionsProvider() {
+        List<Arguments> lst = new ArrayList<>();
+        Option option = Option.builder("a").longOpt("aaa").desc("dddd dddd dddd")
+                .deprecated(DeprecatedAttributes.builder().setForRemoval(true).setSince("now")
+                        .setDescription("Why why why").get())
+                .build();
+
+        HelpFormatter hf = HelpFormatter.builder().setShowDeprecated(false).get();
+        lst.add(Arguments.of(hf, option, "dddd dddd dddd"));
+
+        hf = HelpFormatter.builder().setShowDeprecated(true).get();
+        lst.add(Arguments.of(hf, option, "[Deprecated] dddd dddd dddd"));
+
+        hf = HelpFormatter.builder().setShowDeprecated((d,o) -> String.format("%s [%s]",d,o.getDeprecated())).get();
+        lst.add(Arguments.of(hf, option, "dddd dddd dddd [Deprecated for removal since now: Why why why]"));
+
+        option = Option.builder("a").longOpt("aaa")
+                .deprecated(DeprecatedAttributes.builder().setForRemoval(true).setSince("now")
+                        .setDescription("Why why why").get())
+                .build();
+
+        hf = HelpFormatter.builder().setShowDeprecated(false).get();
+        lst.add(Arguments.of(hf, option, ""));
+
+        hf = HelpFormatter.builder().setShowDeprecated(true).get();
+        lst.add(Arguments.of(hf, option, "[Deprecated]"));
+
+        hf = HelpFormatter.builder().setShowDeprecated((d,o)-> String.format("%s [%s]",d,o.getDeprecated())).get();
+        lst.add(Arguments.of(hf, option, "[Deprecated for removal since now: Why why why]"));
+
+        return lst.stream();
+    }
+
     @Test
     public void testPrintOptionWithEmptyArgNameUsage() {
         final Option option = new Option("f", true, null);

From 0069ab8139f3f47c639997ba92a202d2ce8a909c Mon Sep 17 00:00:00 2001
From: Claude Warren <claude@xenei.com>
Date: Sat, 11 May 2024 16:46:58 +0200
Subject: [PATCH 2/4] fixed checkstyle errors

---
 .../org/apache/commons/cli/HelpFormatter.java    | 16 +++++++++-------
 .../apache/commons/cli/HelpFormatterTest.java    |  8 ++++----
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/src/main/java/org/apache/commons/cli/HelpFormatter.java b/src/main/java/org/apache/commons/cli/HelpFormatter.java
index 7f3e9aee0..d84046c0a 100644
--- a/src/main/java/org/apache/commons/cli/HelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/HelpFormatter.java
@@ -30,7 +30,6 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import java.util.Iterator;
 import java.util.List;
 import java.util.Objects;
-import java.util.function.Function;
 import java.util.function.BiFunction;
 import java.util.function.Supplier;
 
@@ -76,12 +75,15 @@ public static final class Builder implements Supplier<HelpFormatter> {
         // TODO All other instance HelpFormatter instance variables.
         // Make HelpFormatter immutable for 2.0
 
-        private static final BiFunction<String, Option,String> DEFAULT_DEPRECATED_FORMAT = (d,o) -> "[Deprecated] "+d;
+        /**
+         * A function to convert a description (not null) and a deprecated Option (not null) to help description
+         */
+        private static final BiFunction<String, Option, String> DEFAULT_DEPRECATED_FORMAT = (d, o) -> "[Deprecated] " + d;
 
         /**
          * Formatter for deprecated options.
          */
-        private BiFunction<String,Option,String> deprecatedFormatFunc;
+        private BiFunction<String, Option, String> deprecatedFormatFunc;
 
         /**
          * The output PrintWriter, defaults to wrapping {@link System#out}.
@@ -120,7 +122,7 @@ public Builder setShowDeprecated(final boolean useDefaultFormat) {
          * @param showDeprecatedFunc Specify the format for the deprecated options.
          * @return this.
          */
-        public Builder setShowDeprecated(final BiFunction<String,Option,String> showDeprecatedFunc) {
+        public Builder setShowDeprecated(final BiFunction<String, Option, String> showDeprecatedFunc) {
             this.deprecatedFormatFunc = showDeprecatedFunc;
             return this;
         }
@@ -265,7 +267,7 @@ private static PrintWriter createDefaultPrintWriter() {
     /**
      * BiFunction to format the description for a deprecated option.
      */
-    private final BiFunction<String,Option,String> deprecatedFormatFunc;
+    private final BiFunction<String, Option, String> deprecatedFormatFunc;
 
     /**
      * Where to print help.
@@ -288,7 +290,7 @@ public HelpFormatter() {
      * Constructs a new instance.
      * @param printStream TODO
      */
-    private HelpFormatter(final BiFunction<String, Option,String> deprecatedFormatFunc, final PrintWriter printStream) {
+    private HelpFormatter(final BiFunction<String, Option, String> deprecatedFormatFunc, final PrintWriter printStream) {
         // TODO All other instance HelpFormatter instance variables.
         // Make HelpFormatter immutable for 2.0
         this.deprecatedFormatFunc = deprecatedFormatFunc;
@@ -792,7 +794,7 @@ protected StringBuffer renderOptions(final StringBuffer sb, final int width, fin
             optBuf.append(dpad);
             final int nextLineTabStop = max + descPad;
             if (deprecatedFormatFunc != null && option.isDeprecated()) {
-                optBuf.append(deprecatedFormatFunc.apply(option.getDescription()==null?"":option.getDescription(), option).trim());
+                optBuf.append(deprecatedFormatFunc.apply(option.getDescription() == null ? "" : option.getDescription(), option).trim());
             } else if (option.getDescription() != null) {
                 optBuf.append(option.getDescription());
             }
diff --git a/src/test/java/org/apache/commons/cli/HelpFormatterTest.java b/src/test/java/org/apache/commons/cli/HelpFormatterTest.java
index b2a9b3531..6c1a31a16 100644
--- a/src/test/java/org/apache/commons/cli/HelpFormatterTest.java
+++ b/src/test/java/org/apache/commons/cli/HelpFormatterTest.java
@@ -492,7 +492,7 @@ public void testPrintOptions() {
 
     @ParameterizedTest
     @MethodSource("deprecatedOptionsProvider")
-    public void testPrintDeprecatedOptions(HelpFormatter hf, Option option, String expectedTxt) {
+    public void testPrintDeprecatedOptions(final HelpFormatter hf, final Option option, final String expectedTxt) {
         final StringBuffer sb = new StringBuffer();
 
         final int leftPad = 1;
@@ -500,7 +500,7 @@ public void testPrintDeprecatedOptions(HelpFormatter hf, Option option, String e
         final String lpad = hf.createPadding(leftPad);
         final String dpad = hf.createPadding(descPad);
         Options options;
-        String expected = expected = lpad + "-a,--aaa";
+        String expected = lpad + "-a,--aaa";
 
         options = new Options().addOption(option);
         if (expectedTxt.length() > 0) {
@@ -523,7 +523,7 @@ static Stream<Arguments> deprecatedOptionsProvider() {
         hf = HelpFormatter.builder().setShowDeprecated(true).get();
         lst.add(Arguments.of(hf, option, "[Deprecated] dddd dddd dddd"));
 
-        hf = HelpFormatter.builder().setShowDeprecated((d,o) -> String.format("%s [%s]",d,o.getDeprecated())).get();
+        hf = HelpFormatter.builder().setShowDeprecated((d, o) -> String.format("%s [%s]", d, o.getDeprecated())).get();
         lst.add(Arguments.of(hf, option, "dddd dddd dddd [Deprecated for removal since now: Why why why]"));
 
         option = Option.builder("a").longOpt("aaa")
@@ -537,7 +537,7 @@ static Stream<Arguments> deprecatedOptionsProvider() {
         hf = HelpFormatter.builder().setShowDeprecated(true).get();
         lst.add(Arguments.of(hf, option, "[Deprecated]"));
 
-        hf = HelpFormatter.builder().setShowDeprecated((d,o)-> String.format("%s [%s]",d,o.getDeprecated())).get();
+        hf = HelpFormatter.builder().setShowDeprecated((d, o) -> String.format("%s [%s]", d, o.getDeprecated())).get();
         lst.add(Arguments.of(hf, option, "[Deprecated for removal since now: Why why why]"));
 
         return lst.stream();

From 86c0aa7b10478b2958b3b1faa44efc8221dcc26a Mon Sep 17 00:00:00 2001
From: Claude Warren <claude@xenei.com>
Date: Sat, 11 May 2024 17:53:27 +0200
Subject: [PATCH 3/4] added since annotation to new method

---
 src/main/java/org/apache/commons/cli/HelpFormatter.java | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/main/java/org/apache/commons/cli/HelpFormatter.java b/src/main/java/org/apache/commons/cli/HelpFormatter.java
index d84046c0a..34831bc17 100644
--- a/src/main/java/org/apache/commons/cli/HelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/HelpFormatter.java
@@ -121,6 +121,7 @@ public Builder setShowDeprecated(final boolean useDefaultFormat) {
          *
          * @param showDeprecatedFunc Specify the format for the deprecated options.
          * @return this.
+         * @since(1.8.0)
          */
         public Builder setShowDeprecated(final BiFunction<String, Option, String> showDeprecatedFunc) {
             this.deprecatedFormatFunc = showDeprecatedFunc;

From 66df78f683bfde2986b20346b5c65d6c593035b0 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@users.noreply.github.com>
Date: Sat, 11 May 2024 13:27:40 -0400
Subject: [PATCH 4/4] Fix Javadoc

---
 src/main/java/org/apache/commons/cli/HelpFormatter.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/java/org/apache/commons/cli/HelpFormatter.java b/src/main/java/org/apache/commons/cli/HelpFormatter.java
index 34831bc17..aa2ced300 100644
--- a/src/main/java/org/apache/commons/cli/HelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/HelpFormatter.java
@@ -121,7 +121,7 @@ public Builder setShowDeprecated(final boolean useDefaultFormat) {
          *
          * @param showDeprecatedFunc Specify the format for the deprecated options.
          * @return this.
-         * @since(1.8.0)
+         * @since 1.8.0
          */
         public Builder setShowDeprecated(final BiFunction<String, Option, String> showDeprecatedFunc) {
             this.deprecatedFormatFunc = showDeprecatedFunc;