[cli-221] resolved merge conflict from master

Author: JoergBudi

.github/pull_request_template.md

@@ -22,7 +22,9 @@ Thanks for your contribution to [Apache Commons](https://commons.apache.org/)! Y
 Before you push a pull request, review this list:
 
 - [ ] Read the [contribution guidelines](CONTRIBUTING.md) for this project.
+- [ ] Read the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) if you use Artificial Intelligence (AI).
+- [ ] I used AI to create any part of, or all of, this pull request.
 - [ ] Run a successful build using the default [Maven](https://maven.apache.org/) goal with `mvn`; that's `mvn` on the command line by itself.
-- [ ] Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible but is a best-practice.
+- [ ] Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best-practice.
 - [ ] Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
-- [ ] Each commit in the pull request should have a meaningful subject line and body. Note that commits might be squashed by a maintainer on merge.
+- [ ] Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process.

.github/workflows/codeql-analysis.yml

@@ -57,7 +57,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@181d5eefc20863364f96762470ba6f862bdef56b    # 3.29.2
+      uses: github/codeql-action/init@4e828ff8d448a8a6e532957b1811f387a63867e8    # 3.29.4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -68,7 +68,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@181d5eefc20863364f96762470ba6f862bdef56b    # 3.29.2
+      uses: github/codeql-action/autobuild@4e828ff8d448a8a6e532957b1811f387a63867e8    # 3.29.4
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -82,4 +82,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@181d5eefc20863364f96762470ba6f862bdef56b    # 3.29.2
+      uses: github/codeql-action/analyze@4e828ff8d448a8a6e532957b1811f387a63867e8    # 3.29.4

.github/workflows/scorecards-analysis.yml

@@ -64,6 +64,6 @@ jobs:
           retention-days: 5
 
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@181d5eefc20863364f96762470ba6f862bdef56b    # 3.29.2
+        uses: github/codeql-action/upload-sarif@4e828ff8d448a8a6e532957b1811f387a63867e8    # 3.29.4
         with:
           sarif_file: results.sarif

CONTRIBUTING.md

@@ -61,11 +61,11 @@ Making Changes
 
 + Create a _topic branch_ for your isolated work.
   * Usually you should base your branch from the `master` branch.
-  * A good topic branch name can be the JIRA bug ID plus a keyword, for example, `CLI-123-InputStream`.
+  * A good topic branch name can be the JIRA bug ID plus a keyword, e.g. `CLI-123-InputStream`.
   * If you have submitted multiple JIRA issues, try to maintain separate branches and pull requests.
 + Make commits of logical units.
   * Make sure your commit messages are meaningful and in the proper format. Your commit message should contain the key of the JIRA issue.
-  * For example, `[CLI-123] Close input stream earlier`
+  * For example, `[CLI-123] Close input stream sooner`
 + Respect the original code style:
   + Only use spaces for indentation; you can check for unnecessary whitespace with `git diff` before committing.
   + Create minimal diffs - disable _On Save_ actions like _Reformat Source Code_ or _Organize Imports_. If you feel the source code should be reformatted create a separate PR for this change first.

README.md

@@ -90,7 +90,7 @@ There are some guidelines which will make applying PRs easier for us:
 + Create minimal diffs - disable on save actions like reformat source code or organize imports. If you feel the source code should be reformatted create a separate PR for this change.
 + Provide JUnit tests for your changes and make sure your changes don't break any existing tests by running `mvn`.
 + Before you pushing a PR, run `mvn` (by itself), this runs the default goal, which contains all build checks.
-+ To see the code coverage report, regardless of coverage failures, run `mvn clean site -Dcommons.jacoco.haltOnFailure=false`
++ To see the code coverage report, regardless of coverage failures, run `mvn clean site -Dcommons.jacoco.haltOnFailure=false -Pjacoco`
 
 If you plan to contribute on a regular basis, please consider filing a [contributor license agreement](https://www.apache.org/licenses/#clas).
 You can learn more about contributing via GitHub in our [contribution guidelines](CONTRIBUTING.md).

RELEASE-NOTES.txt

@@ -1,11 +1,73 @@
 Apache Commons CLI 1.10.0 Release Notes
 ---------------------------------------
 
+The Apache Commons CLI team is pleased to announce the release of Apache Commons CLI 1.10.0.
+
 Apache Commons CLI provides a simple API for presenting, processing, and validating a Command Line Interface.
 
 This is a feature and maintenance release. Java 8 or later is required.
 
 
+New Features
+------------
+
+* CLI-339:  Help formatter extension in the new package #314. Thanks to Claude Warren, Gary Gregory.
+*           CommandLine.Builder implements Supplier<CommandLine>. Thanks to Gary Gregory.
+*           DefaultParser.Builder implements Supplier<DefaultParser>. Thanks to Gary Gregory.
+* CLI-340:  Add CommandLine.getParsedOptionValues() #334. Thanks to Claude Warren, Gary Gregory.
+* CLI-333:  org.apache.commons.cli.Option.Builder implements Supplier<Option>. Thanks to Claude Warren, Gary Gregory.
+
+Fixed Bugs
+----------
+
+*           Deprecate CommandLine.Builder() in favor of CommandLine.builder(). Thanks to Gary Gregory.
+*           Deprecate DeprecatedAttributes.Builder() in favor of DeprecatedAttributes.builder(). Thanks to Gary Gregory.
+*           Refactor default parser test #294. Thanks to Dávid Szigecsán.
+*           Port to JUnit 5. Thanks to Gary Gregory.
+*           Generics for Converter should use Exception not Throwable. Thanks to Gary Gregory.
+*           Pick up maven-antrun-plugin version from parent POM org.apache:apache. Thanks to Gary Gregory.
+*           Javadoc is missing its Overview page. Thanks to Gary Gregory.
+*           Get mockito version from parent pom (#351). Thanks to Arnout Engelen.
+*           Remove -nouses directive from maven-bundle-plugin. OSGi package imports now state 'uses' definitions for package imports, this doesn't affect JPMS (from org.apache.commons:commons-parent:80). Thanks to Gary Gregory.
+*           Deprecate PatternOptionBuilder.PatternOptionBuilder(). Thanks to Arnout Engelen.
+* CLI-341:  HelpFormatter infinite loop with 0 width input. Thanks to Ruiqi Dong, Gary Gregory.
+* CLI-349:  Fail faster with a more precise NullPointerException: Option.processValue() throws NullPointerException when passed null value with value separator configured. Thanks to Leo Fernandes, Gary Gregory.
+* CLI-344:  Fail faster with a more precise NullPointerException: DefaultParser.parse() throws NullPointerException when options parameter is null. Thanks to Ruiqi Dong, Gary Gregory.
+* CLI-347:  Options.addOptionGroup(OptionGroup) does not remove required options from requiredOpts list. Thanks to Ruiqi Dong, Gary Gregory.
+*           org.apache.commons.cli.Option.Builder.get() should throw IllegalStateException instead of IllegalArgumentException. Thanks to Gary Gregory.
+*           org.apache.commons.cli.Option.processValue(String) should throw IllegalStateException instead of IllegalArgumentException. Thanks to Gary Gregory.
+*           org.apache.commons.cli.OptionBuilder.create() should throw IllegalStateException instead of IllegalArgumentException. Thanks to Gary Gregory.
+
+Updates
+-------
+
+*           Bump org.apache.commons:commons-parent from 72 to 85 #302, #304, #310, #315, #320, #327, #371. Thanks to Gary Gregory, Dependabot.
+*           [test] Bump commons-io:commons-io from 2.16.1 to 2.20.0 #309, #337. Thanks to Gary Gregory, Dependabot.
+*           [test] Bump org.apache.commons:commons-text from 1.12.0 to 1.14.0 #344. Thanks to Gary Gregory, Dependabot.
+*           Update site documentation to https://maven.apache.org/xsd/xdoc-2.0.xsd. Thanks to Gary Gregory.
+
+
+Historical list of changes: https://commons.apache.org/proper/commons-cli/changes.html
+
+For complete information on Apache Commons CLI, including instructions on how to submit bug reports,
+patches, or suggestions for improvement, see the Apache Commons CLI website:
+
+https://commons.apache.org/proper/commons-cli/
+
+Download page: https://commons.apache.org/proper/commons-cli/download_cli.cgi
+
+Have fun!
+The Apache Commons Team
+
+------------------------------------------------------------------------------
+
+Apache Commons CLI 1.10.0 Release Notes
+---------------------------------------
+
+Apache Commons CLI provides a simple API for presenting, processing, and validating a Command Line Interface.
+
+This is a feature and maintenance release. Java 8 or later is required.
+
 New Features
 ------------
 

pom.xml

@@ -70,7 +70,7 @@
     <dependency>
       <groupId>org.apache.commons</groupId>
       <artifactId>commons-text</artifactId>
-      <version>1.13.1</version>
+      <version>1.14.0</version>
       <scope>test</scope>
     </dependency>
     <dependency>

src/changes/changes.xml

@@ -22,7 +22,7 @@
     <title>Apache Commons CLI Release Notes</title>
   </properties>
   <body>
-    <release version="1.10.0" date="YYYY-MM-DD" description="This is a feature and maintenance release. Java 8 or later is required.">
+    <release version="1.10.0" date="2025-07-30" description="This is a feature and maintenance release. Java 8 or later is required.">
       <!-- FIX -->
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Deprecate CommandLine.Builder() in favor of CommandLine.builder().</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Deprecate DeprecatedAttributes.Builder() in favor of DeprecatedAttributes.builder().</action>
@@ -35,15 +35,22 @@
       <action type="fix" dev="ggregory" due-to="Gary Gregory">Remove -nouses directive from maven-bundle-plugin. OSGi package imports now state 'uses' definitions for package imports, this doesn't affect JPMS (from org.apache.commons:commons-parent:80).</action>
       <action type="fix" dev="ggregory" due-to="Arnout Engelen">Deprecate PatternOptionBuilder.PatternOptionBuilder().</action>
       <action type="fix" issue="CLI-341" dev="ggregory" due-to="Ruiqi Dong, Gary Gregory">HelpFormatter infinite loop with 0 width input.</action>
+      <action type="fix" issue="CLI-349" dev="ggregory" due-to="Leo Fernandes, Gary Gregory">Fail faster with a more precise NullPointerException: Option.processValue() throws NullPointerException when passed null value with value separator configured.</action>
+      <action type="fix" issue="CLI-344" dev="ggregory" due-to="Ruiqi Dong, Gary Gregory">Fail faster with a more precise NullPointerException: DefaultParser.parse() throws NullPointerException when options parameter is null.</action>
+      <action type="fix" issue="CLI-347" dev="ggregory" due-to="Ruiqi Dong, Gary Gregory">Options.addOptionGroup(OptionGroup) does not remove required options from requiredOpts list.</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">org.apache.commons.cli.Option.Builder.get() should throw IllegalStateException instead of IllegalArgumentException.</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">org.apache.commons.cli.Option.processValue(String) should throw IllegalStateException instead of IllegalArgumentException.</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">org.apache.commons.cli.OptionBuilder.create() should throw IllegalStateException instead of IllegalArgumentException.</action>
       <!-- ADD -->
       <action type="add" issue="CLI-339" dev="ggregory" due-to="Claude Warren, Gary Gregory">Help formatter extension in the new package #314.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">CommandLine.Builder implements Supplier&lt;CommandLine&gt;.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">DefaultParser.Builder implements Supplier&lt;DefaultParser&gt;.</action>
-      <action type="add" issue="CLI-340" dev="ggregory" due-to="Claude Warren, Gary Gregory">Add CommandLine.getParsedOptionValues() #334.</action> 
+      <action type="add" issue="CLI-340" dev="ggregory" due-to="Claude Warren, Gary Gregory">Add CommandLine.getParsedOptionValues() #334.</action>
+      <action type="add" issue="CLI-333" dev="ggregory" due-to="Claude Warren, Gary Gregory">org.apache.commons.cli.Option.Builder implements Supplier&lt;Option&gt;.</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 72 to 85 #302, #304, #310, #315, #320, #327, #371.</action>
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[test] Bump commons-io:commons-io from 2.16.1 to 2.20.0 #309, #337.</action>
-      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[test] Bump org.apache.commons:commons-text from 1.12.0 to 1.13.1 #344.</action>
+      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[test] Bump org.apache.commons:commons-text from 1.12.0 to 1.14.0 #344.</action>
       <action type="update" dev="ggregory" due-to="Gary Gregory">Update site documentation to https://maven.apache.org/xsd/xdoc-2.0.xsd.</action>
     </release>
     <release version="1.9.0" date="2024-08-10" description="This release contains new features and bug fixes and requires Java 8 or above.">

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

@@ -28,21 +28,21 @@ public class AlreadySelectedException extends ParseException {
     private static final long serialVersionUID = 3674381532418544760L;
 
     /** The option group selected. */
-    private final OptionGroup group;
+    private final OptionGroup optionGroup;
 
     /** The option that triggered the exception. */
     private final Option option;
 
     /**
      * Constructs a new {@code AlreadySelectedException} for the specified option group.
      *
-     * @param group the option group already selected
+     * @param optionGroup the option group already selected
      * @param option the option that triggered the exception
      * @since 1.2
      */
-    public AlreadySelectedException(final OptionGroup group, final Option option) {
-        this(String.format("The option '%s' was specified but an option from this group has already been selected: '%s'", option.getKey(), group.getSelected()),
-                group, option);
+    public AlreadySelectedException(final OptionGroup optionGroup, final Option option) {
+        this(String.format("The option '%s' was specified but an option from this group has already been selected: '%s'", option.getKey(),
+                optionGroup.getSelected()), optionGroup, option);
     }
 
     /**
@@ -54,9 +54,9 @@ public AlreadySelectedException(final String message) {
         this(message, null, null);
     }
 
-    private AlreadySelectedException(final String message, final OptionGroup group, final Option option) {
+    private AlreadySelectedException(final String message, final OptionGroup optionGroup, final Option option) {
         super(message);
-        this.group = group;
+        this.optionGroup = optionGroup;
         this.option = option;
     }
 
@@ -77,6 +77,6 @@ public Option getOption() {
      * @since 1.2
      */
     public OptionGroup getOptionGroup() {
-        return group;
+        return optionGroup;
     }
 }