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
The following commit(s) were added to refs/heads/master by this push:
new 7aac2dd [CLI-332] Add optional HelpFormatter Function to document
Deprecated options (#271)
7aac2dd is described below
commit 7aac2dd3336153857e6ab7be76f089f8787dd829
Author: Claude Warren <cla...@xenei.com>
AuthorDate: Sat May 11 18:35:35 2024 +0100
[CLI-332] Add optional HelpFormatter Function to document Deprecated
options (#271)
* added ability to display deprecation information in help output
* fixed checkstyle errors
* added since annotation to new method
* Fix Javadoc
---------
Co-authored-by: Gary Gregory <garydgreg...@users.noreply.github.com>
---
.../java/org/apache/commons/cli/HelpFormatter.java | 50 +++++++++++-------
.../org/apache/commons/cli/HelpFormatterTest.java | 59 ++++++++++++++++++++++
2 files changed, 90 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 539e18c..aa2ced3 100644
--- a/src/main/java/org/apache/commons/cli/HelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/HelpFormatter.java
@@ -30,6 +30,7 @@ import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.Objects;
+import java.util.function.BiFunction;
import java.util.function.Supplier;
/**
@@ -75,9 +76,14 @@ public class HelpFormatter {
// Make HelpFormatter immutable for 2.0
/**
- * Whether to show deprecated options.
+ * A function to convert a description (not null) and a deprecated
Option (not null) to help description
*/
- private boolean showDeprecated;
+ private static final BiFunction<String, Option, String>
DEFAULT_DEPRECATED_FORMAT = (d, o) -> "[Deprecated] " + d;
+
+ /**
+ * Formatter for deprecated options.
+ */
+ private BiFunction<String, Option, String> deprecatedFormatFunc;
/**
* The output PrintWriter, defaults to wrapping {@link System#out}.
@@ -86,7 +92,7 @@ public class HelpFormatter {
@Override
public HelpFormatter get() {
- return new HelpFormatter(showDeprecated, printStream);
+ return new HelpFormatter(deprecatedFormatFunc, printStream);
}
/**
@@ -103,14 +109,24 @@ public class HelpFormatter {
/**
* 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.
+ * @since 1.8.0
+ */
+ public Builder setShowDeprecated(final BiFunction<String, Option,
String> showDeprecatedFunc) {
+ this.deprecatedFormatFunc = showDeprecatedFunc;
+ return this;
+ }
}
/**
@@ -250,9 +266,9 @@ public class HelpFormatter {
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 +284,17 @@ public class HelpFormatter {
* 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 +794,9 @@ public class HelpFormatter {
}
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 bf380ca..6c1a31a 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 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
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 class HelpFormatterTest {
assertEquals(expected, sb.toString(), "multiple wrapped options");
}
+ @ParameterizedTest
+ @MethodSource("deprecatedOptionsProvider")
+ public void testPrintDeprecatedOptions(final HelpFormatter hf, final
Option option, final 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 = 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);
