From fb8b27553352fb4486857d8a9105d5764418a674 Mon Sep 17 00:00:00 2001
From: Claude Warren <claude@xenei.com>
Date: Sat, 1 Nov 2025 16:55:22 +0000
Subject: [PATCH 1/4] Fix issue with groups not being reported in help output.

AbstractHelpFormatter:

 * Swapped printHelp using Iterable<Option> with printHelp using Options.  Effectively switching to using Options class to print the help.

 * Removed public String toSyntaxOptions(final Iterable<Option> options) as it was added in this version and should have only been used internally.

HelpFormatterTest:

 * removed toSyntaxOptions using Iterable<Option> test.

 * added a printHelpTest with Iterable<Option> as previously we depended on printHelpTest with Option to test the code branch.

 * added verifyOptionGroupingOutput as a test to show that reported issue is corrected.
---
 .../cli/help/AbstractHelpFormatter.java       |  22 ++--
 .../commons/cli/help/HelpFormatterTest.java   | 118 +++++++++++++++---
 2 files changed, 110 insertions(+), 30 deletions(-)

diff --git a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
index f8947c660..1b3721e66 100644
--- a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
@@ -293,7 +293,7 @@ public final String getSyntaxPrefix() {
      * @param autoUsage     whether to print an automatically generated usage statement.
      * @throws IOException If the output could not be written to the {@link HelpAppendable}.
      */
-    public void printHelp(final String cmdLineSyntax, final String header, final Iterable<Option> options, final String footer, final boolean autoUsage)
+    public void printHelp(final String cmdLineSyntax, final String header, final Options options, final String footer, final boolean autoUsage)
             throws IOException {
         if (Util.isEmpty(cmdLineSyntax)) {
             throw new IllegalArgumentException("cmdLineSyntax not provided");
@@ -306,7 +306,7 @@ public void printHelp(final String cmdLineSyntax, final String header, final Ite
         if (!Util.isEmpty(header)) {
             helpAppendable.appendParagraph(header);
         }
-        helpAppendable.appendTable(getTableDefinition(options));
+        helpAppendable.appendTable(getTableDefinition(options.getOptions()));
         if (!Util.isEmpty(footer)) {
             helpAppendable.appendParagraph(footer);
         }
@@ -317,14 +317,16 @@ public void printHelp(final String cmdLineSyntax, final String header, final Ite
      *
      * @param cmdLineSyntax the syntax for this application.
      * @param header        the banner to display at the beginning of the help.
-     * @param options       the {@link Options} to print.
+     * @param options       the collection of {@link Option} objects to print.
      * @param footer        the banner to display at the end of the help.
      * @param autoUsage     whether to print an automatically generated usage statement.
      * @throws IOException If the output could not be written to the {@link HelpAppendable}.
      */
-    public final void printHelp(final String cmdLineSyntax, final String header, final Options options, final String footer, final boolean autoUsage)
+    public final void printHelp(final String cmdLineSyntax, final String header, final Iterable<Option> options, final String footer, final boolean autoUsage)
             throws IOException {
-        printHelp(cmdLineSyntax, header, options.getOptions(), footer, autoUsage);
+        Options optionsObject = new Options();
+        options.forEach(optionsObject::addOption);
+        printHelp(cmdLineSyntax, header, optionsObject, footer, autoUsage);
     }
 
     /**
@@ -401,16 +403,6 @@ public final String toArgName(final String argName) {
         return optionFormatBuilder.toArgName(argName);
     }
 
-    /**
-     * Return the string representation of the options as used in the syntax display.
-     *
-     * @param options The collection of {@link Option} instances to create the string representation for.
-     * @return the string representation of the options as used in the syntax display.
-     */
-    public String toSyntaxOptions(final Iterable<Option> options) {
-        return toSyntaxOptions(options, o -> null);
-    }
-
     /**
      * Return the string representation of the options as used in the syntax display.
      *
diff --git a/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java b/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
index 9d524033a..9f97f6b65 100644
--- a/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
+++ b/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
@@ -147,6 +147,85 @@ void testPrintHelp() throws IOException {
         assertEquals(0, sb.length(), "Should not write to output");
     }
 
+    @Test
+    public void testPrintHelpWithIterableOptions() throws IOException {
+        final StringBuilder sb = new StringBuilder();
+        final TextHelpAppendable serializer = new TextHelpAppendable(sb);
+        HelpFormatter formatter = HelpFormatter.builder().setHelpAppendable(serializer).get();
+
+        final List<Option> options = new ArrayList<>();
+        options.add(Option.builder("a").since("1853").hasArg().desc("aaaa aaaa aaaa aaaa aaaa").build());
+
+        List<String> expected = new ArrayList<>();
+        expected.add(" usage:  commandSyntax [-a <arg>]");
+        expected.add("");
+        expected.add(" header");
+        expected.add("");
+        expected.add(" Options      Since           Description       ");
+        expected.add(" -a <arg>     1853      aaaa aaaa aaaa aaaa aaaa");
+        expected.add("");
+        expected.add(" footer");
+        expected.add("");
+
+        formatter.printHelp("commandSyntax", "header", options, "footer", true);
+        List<String> actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        formatter = HelpFormatter.builder().setShowSince(false).setHelpAppendable(serializer).get();
+        expected = new ArrayList<>();
+        expected.add(" usage:  commandSyntax [-a <arg>]");
+        expected.add("");
+        expected.add(" header");
+        expected.add("");
+        expected.add(" Options            Description       ");
+        expected.add(" -a <arg>     aaaa aaaa aaaa aaaa aaaa");
+        expected.add("");
+        expected.add(" footer");
+        expected.add("");
+
+        sb.setLength(0);
+        formatter.printHelp("commandSyntax", "header", options, "footer", true);
+        actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        sb.setLength(0);
+        formatter.printHelp("commandSyntax", "header", options, "footer", false);
+        expected.set(0, " usage:  commandSyntax");
+        actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        sb.setLength(0);
+        formatter.printHelp("commandSyntax", "", options, "footer", false);
+        expected.remove(3);
+        expected.remove(2);
+        actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        sb.setLength(0);
+        formatter.printHelp("commandSyntax", null, options, "footer", false);
+        actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        sb.setLength(0);
+        formatter.printHelp("commandSyntax", null, options, "", false);
+        expected.remove(6);
+        expected.remove(5);
+        actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        sb.setLength(0);
+        formatter.printHelp("commandSyntax", null, options, null, false);
+        actual = IOUtils.readLines(new StringReader(sb.toString()));
+        assertEquals(expected, actual);
+
+        sb.setLength(0);
+        final HelpFormatter fHelp = formatter;
+        assertThrows(IllegalArgumentException.class, () -> fHelp.printHelp("", "header", options, "footer", true));
+        assertEquals(0, sb.length(), "Should not write to output");
+        assertThrows(IllegalArgumentException.class, () -> fHelp.printHelp(null, "header", options, "footer", true));
+        assertEquals(0, sb.length(), "Should not write to output");
+    }
+
     /**
      * Tests example from the mailing list that caused an infinite loop.
      *
@@ -347,21 +426,6 @@ void testToSyntaxOptionGroupTest() {
         assertEquals("", underTest.toSyntaxOptions(new OptionGroup()), "empty group should return empty string");
     }
 
-    @Test
-    void testToSyntaxOptionIterableTest() {
-        final HelpFormatter underTest = HelpFormatter.builder().get();
-        final List<Option> options = new ArrayList<>();
-
-        options.add(Option.builder().option("o").longOpt("one").hasArg().get());
-        options.add(Option.builder().option("t").longOpt("two").hasArg().required().argName("other").get());
-        options.add(Option.builder().option("th").longOpt("three").required().argName("other").get());
-        options.add(Option.builder().option("f").argName("other").get());
-        options.add(Option.builder().longOpt("five").hasArg().argName("other").get());
-        options.add(Option.builder().longOpt("six").required().hasArg().argName("other").get());
-        options.add(Option.builder().option("s").longOpt("sevem").hasArg().get());
-        assertEquals("[-f] [--five <other>] [-o <arg>] [-s <arg>] --six <other> -t <other> -th", underTest.toSyntaxOptions(options));
-
-    }
 
     @Test
     void testToSyntaxOptionOptionsTest() {
@@ -415,4 +479,28 @@ void testToSyntaxOptionOptionsTest() {
                 "options with required group failed");
     }
 
+    @Test
+    void verifyOptionGroupingOutput() throws IOException {
+         // create options and groups
+         final Option o1 = new Option("o1", "Descr");
+         final Option o2 = new Option("o2", "Descr");
+
+         final Options options = new Options();
+         options.addOption(o1);
+         options.addOption(o2);
+
+         final OptionGroup group = new OptionGroup();
+         group.addOption(o1);
+         group.addOption(o2);
+         options.addOptionGroup(group);
+
+         final StringBuilder output = new StringBuilder();
+         //format options with new formatter
+         final org.apache.commons.cli.help.HelpFormatter newFormatter =
+                 org.apache.commons.cli.help.HelpFormatter.builder().setShowSince(false)
+        .setHelpAppendable(new TextHelpAppendable(output)).get();
+         newFormatter.printHelp("Command", null, options, null, true);
+         assertTrue(output.toString().contains("[-o1 | -o2]"));
+     }
+
 }

From 0c7262903833b6bd9f26ec55ff26d72db29fc137 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@users.noreply.github.com>
Date: Sat, 1 Nov 2025 13:23:52 -0400
Subject: [PATCH 2/4] Don't break binary compatibility

---
 .../apache/commons/cli/help/AbstractHelpFormatter.java | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
index 1b3721e66..f435d4c41 100644
--- a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
@@ -403,6 +403,16 @@ public final String toArgName(final String argName) {
         return optionFormatBuilder.toArgName(argName);
     }
 
+    /**
+     * Return the string representation of the options as used in the syntax display.
+     *
+     * @param options The collection of {@link Option} instances to create the string representation for.
+     * @return the string representation of the options as used in the syntax display.
+     */
+    public String toSyntaxOptions(final Iterable<Option> options) {
+        return toSyntaxOptions(options, o -> null);
+    }
+
     /**
      * Return the string representation of the options as used in the syntax display.
      *

From 1cbac2fe6115a4cd1f5c15b9bda05abe2843428f Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@users.noreply.github.com>
Date: Sat, 1 Nov 2025 13:27:18 -0400
Subject: [PATCH 3/4] Restore test

Add test for toSyntaxOptions with iterable of options
---
 .../commons/cli/help/HelpFormatterTest.java       | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java b/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
index 9f97f6b65..7062daa5e 100644
--- a/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
+++ b/src/test/java/org/apache/commons/cli/help/HelpFormatterTest.java
@@ -426,6 +426,21 @@ void testToSyntaxOptionGroupTest() {
         assertEquals("", underTest.toSyntaxOptions(new OptionGroup()), "empty group should return empty string");
     }
 
+    @Test
+    void testToSyntaxOptionIterableTest() {
+        final HelpFormatter underTest = HelpFormatter.builder().get();
+        final List<Option> options = new ArrayList<>();
+
+        options.add(Option.builder().option("o").longOpt("one").hasArg().get());
+        options.add(Option.builder().option("t").longOpt("two").hasArg().required().argName("other").get());
+        options.add(Option.builder().option("th").longOpt("three").required().argName("other").get());
+        options.add(Option.builder().option("f").argName("other").get());
+        options.add(Option.builder().longOpt("five").hasArg().argName("other").get());
+        options.add(Option.builder().longOpt("six").required().hasArg().argName("other").get());
+        options.add(Option.builder().option("s").longOpt("sevem").hasArg().get());
+        assertEquals("[-f] [--five <other>] [-o <arg>] [-s <arg>] --six <other> -t <other> -th", underTest.toSyntaxOptions(options));
+
+    }
 
     @Test
     void testToSyntaxOptionOptionsTest() {

From 9a34a8768a1573a241cae730bacd09ec38fafb0b Mon Sep 17 00:00:00 2001
From: Claude Warren <claude@xenei.com>
Date: Mon, 3 Nov 2025 17:00:48 +0000
Subject: [PATCH 4/4] fixed issues arising from reverting incompatible binary
 changes

---
 .../apache/commons/cli/help/AbstractHelpFormatter.java    | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
index f435d4c41..cc06c90ae 100644
--- a/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
+++ b/src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java
@@ -322,7 +322,7 @@ public void printHelp(final String cmdLineSyntax, final String header, final Opt
      * @param autoUsage     whether to print an automatically generated usage statement.
      * @throws IOException If the output could not be written to the {@link HelpAppendable}.
      */
-    public final void printHelp(final String cmdLineSyntax, final String header, final Iterable<Option> options, final String footer, final boolean autoUsage)
+    public void printHelp(final String cmdLineSyntax, final String header, final Iterable<Option> options, final String footer, final boolean autoUsage)
             throws IOException {
         Options optionsObject = new Options();
         options.forEach(optionsObject::addOption);
@@ -405,7 +405,11 @@ public final String toArgName(final String argName) {
 
     /**
      * Return the string representation of the options as used in the syntax display.
-     *
+     * <p>
+     *     This is probably not the method you want.  This method does not track the presence
+     *     of option groups.  To display the option grouping use {@link #toSyntaxOptions(Options)} or
+     *     {@link #toSyntaxOptions(OptionGroup)} for individual groups.
+     * </p>
      * @param options The collection of {@link Option} instances to create the string representation for.
      * @return the string representation of the options as used in the syntax display.
      */