Merge branch 'master' of https://gitbox.apache.org/repos/asf/commons-cli

Author: garydgregory

.github/workflows/codeql-analysis.yml

@@ -45,7 +45,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # 4.1.6
+      uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # 4.1.7
       with:
         persist-credentials: false
     - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
@@ -57,7 +57,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@9fdb3e49720b44c48891d036bb502feb25684276    # 3.25.6
+      uses: github/codeql-action/init@23acc5c183826b7a8a97bce3cecc52db901f8251    # 3.25.10
       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@9fdb3e49720b44c48891d036bb502feb25684276    # 3.25.6
+      uses: github/codeql-action/autobuild@23acc5c183826b7a8a97bce3cecc52db901f8251    # 3.25.10
 
     # ℹ️ 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@9fdb3e49720b44c48891d036bb502feb25684276    # 3.25.6
+      uses: github/codeql-action/analyze@23acc5c183826b7a8a97bce3cecc52db901f8251    # 3.25.10

.github/workflows/coverage.yml

@@ -29,7 +29,7 @@ jobs:
         java: [ 8 ]
 
     steps:
-    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # 4.1.6
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # 4.1.7
       with:
         persist-credentials: false
     - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
@@ -47,6 +47,6 @@ jobs:
       run: mvn --show-version --batch-mode --no-transfer-progress test jacoco:report
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@125fc84a9a348dbcf27191600683ec096ec9021c # v4.4.1
+      uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
       with:
         files: ./target/site/jacoco/jacoco.xml

.github/workflows/maven.yml

@@ -34,7 +34,7 @@ jobs:
             experimental: true
 
     steps:
-    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # 4.1.6
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # 4.1.7
       with:
         persist-credentials: false
     - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2

.github/workflows/scorecards-analysis.yml

@@ -40,7 +40,7 @@ jobs:
     steps:
 
       - name: "Checkout code"
-        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29   # 4.1.6
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332   # 4.1.7
         with:
           persist-credentials: false
 
@@ -64,6 +64,6 @@ jobs:
           retention-days: 5
 
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@9fdb3e49720b44c48891d036bb502feb25684276    # 3.25.6
+        uses: github/codeql-action/upload-sarif@23acc5c183826b7a8a97bce3cecc52db901f8251    # 3.25.10
         with:
           sarif_file: results.sarif

pom.xml

@@ -19,12 +19,12 @@
   <parent>
     <groupId>org.apache.commons</groupId>
     <artifactId>commons-parent</artifactId>
-    <version>70</version>
+    <version>71</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <groupId>commons-cli</groupId>
   <artifactId>commons-cli</artifactId>
-  <version>1.8.1-SNAPSHOT</version>
+  <version>1.9.0-SNAPSHOT</version>
   <name>Apache Commons CLI</name>
   <inceptionYear>2002</inceptionYear>
   <description>
@@ -70,12 +70,12 @@
     <maven.compiler.target>1.8</maven.compiler.target>
     <commons.componentid>cli</commons.componentid>
     <commons.module.name>org.apache.commons.cli</commons.module.name>
-    <commons.release.version>1.8.0</commons.release.version>
-    <commons.release.next>1.8.1</commons.release.next>
+    <commons.release.version>1.9.0</commons.release.version>
+    <commons.release.next>1.9.1</commons.release.next>
     <commons.release.name>commons-cli-${commons.release.version}</commons.release.name>
     <commons.release.isDistModule>true</commons.release.isDistModule>
     <commons.rc.version>RC2</commons.rc.version>
-    <commons.bc.version>1.7.0</commons.bc.version>
+    <commons.bc.version>1.8.0</commons.bc.version>
     <commons.osgi.symbolicName>org.apache.commons.cli</commons.osgi.symbolicName>
     <commons.jira.id>CLI</commons.jira.id>
     <commons.jira.pid>12310463</commons.jira.pid>

src/changes/changes.xml

@@ -22,8 +22,14 @@
     <title>Apache Commons CLI Release Notes</title>
   </properties>
   <body>
-    <release version="1.8.1" date="YYYY-MM-DD" description="This release contains new features and bug fixes and requires Java 8 or above.">
-      <action type="add" issue="CLI-334" dev="ggregory" due-to="Eric Pugh">Fix Javadoc pathing #280.</action>
+    <release version="1.9.0" date="YYYY-MM-DD" description="This release contains new features and bug fixes and requires Java 8 or above.">
+      <!-- ADD -->
+      <action type="add" dev="ggregory" due-to="Gary Gregory">Add OptionGroup.isSelected().</action>
+      <!-- FIX -->
+      <action type="fix" issue="CLI-334" dev="ggregory" due-to="Eric Pugh">Fix Javadoc pathing #280.</action>
+      <action type="fix" issue="CLI-335" dev="ggregory" due-to="Claude Warren">Updated properties documentation #285 .</action>
+      <!-- UPDATE -->
+      <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 70 to 71 #283.</action>
     </release>
     <release version="1.8.0" date="2024-05-18" description="This release contains new features and bug fixes and requires Java 8 or above.">
       <!-- ADD -->

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

@@ -443,7 +443,7 @@ private void handleProperties(final Properties properties) throws ParseException
             }
             // if the option is part of a group, check if another option of the group has been selected
             final OptionGroup group = options.getOptionGroup(opt);
-            final boolean selected = group != null && group.getSelected() != null;
+            final boolean selected = group != null && group.isSelected();
             if (!cmd.hasOption(option) && !selected) {
                 // get the value from the properties
                 final String value = properties.getProperty(option);

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

@@ -41,7 +41,7 @@ public class OptionGroup implements Serializable {
     private boolean required;
 
     /**
-     * Add the specified {@code Option} to this group.
+     * Adds the given {@code Option} to this group.
      *
      * @param option the option to add to this group
      * @return this option group with the option added
@@ -54,23 +54,29 @@ public OptionGroup addOption(final Option option) {
     }
 
     /**
-     * @return the names of the options in this group as a {@code Collection}
+     * Gets the names of the options in this group as a {@code Collection}.
+     *
+     * @return the names of the options in this group as a {@code Collection}.
      */
     public Collection<String> getNames() {
         // the key set is the collection of names
         return optionMap.keySet();
     }
 
     /**
-     * @return the options in this group as a {@code Collection}
+     * Gets the options in this group as a {@code Collection}.
+     *
+     * @return the options in this group as a {@code Collection}.
      */
     public Collection<Option> getOptions() {
         // the values are the collection of options
         return optionMap.values();
     }
 
     /**
-     * @return the selected option name
+     * Gets the selected option name.
+     *
+     * @return the selected option name.
      */
     public String getSelected() {
         return selected;
@@ -86,7 +92,19 @@ public boolean isRequired() {
     }
 
     /**
-     * @param required specifies if this group is required
+     * Tests whether an option is selected.
+     *
+     * @return whether whether an option is selected.
+     * @since 1.9.0
+     */
+    public boolean isSelected() {
+        return selected != null;
+    }
+
+    /**
+     * Sets whether this group is required.
+     *
+     * @param required whether this group is required.
      */
     public void setRequired(final boolean required) {
         this.required = required;

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

@@ -273,7 +273,7 @@ protected void processProperties(final Properties properties) throws ParseExcept
             }
             // if the option is part of a group, check if another option of the group has been selected
             final OptionGroup group = options.getOptionGroup(opt);
-            final boolean selected = group != null && group.getSelected() != null;
+            final boolean selected = group != null && group.isSelected();
             if (!cmd.hasOption(option) && !selected) {
                 // get the value from the properties instance
                 final String value = properties.getProperty(option);

src/site/xdoc/properties.xml

@@ -31,7 +31,7 @@
         <a href="javadocs/api-release/org/apache/commons/cli/Option.html">Option</a> has.  All of these
         can be set using the accessors or using the methods
         defined in the
-        <a href="javadocs/api-release/org/apache/commons/cli/OptionBuilder.html">OptionBuilder</a>.
+        <a href="javadocs/api-release/org/apache/commons/cli/Option.Builder.html">Option.Builder</a>.
       </p>
       <table>
         <tr>
@@ -40,68 +40,80 @@
           <th>Description</th>
         </tr>
         <tr>
-          <td>opt</td>
-          <td>java.lang.String</td>
-          <td>the identification string of the Option.</td>
+          <td>arg</td>
+          <td>boolean</td>
+          <td>A flag to say whether the option takes an argument.</td>
         </tr>
         <tr>
-          <td>longOpt</td>
-          <td>java.lang.String</td>
-          <td>an alias and more descriptive identification string</td>
+          <td>args</td>
+          <td>boolean</td>
+          <td>A flag to say whether the option takes more than one argument.</td>
         </tr>
         <tr>
-          <td>description</td>
+          <td>argName</td>
           <td>java.lang.String</td>
-          <td>a description of the function of the option</td>
+          <td>The name of the argument value for the usage statement.</td>
         </tr>
         <tr>
-          <td>required</td>
-          <td>boolean</td>
-          <td>a flag to say whether the option <b>must</b> appear on 
-            the command line.</td>
+          <td>converter</td>
+          <td>org.apache.commons.cli.Converter&lt;T, E extends Throwable&gt;</td>
+          <td>A FunctionalInterface that converts a String to type T and may throw an exception E.  When
+            CommandLine.getParsedValue() is called this FunctionalInterface will perform the conversion from the
+            command line argument to the parsed type. This is used when a desired type is not registered, or to
+            provide a custom type implementation.  The 'type' property is not required to use the 'converter' property.</td>
         </tr>
         <tr>
-          <td>arg</td>
-          <td>boolean</td>
-          <td>a flag to say whether the option takes an argument</td>
+          <td>deprecated</td>
+          <td>org.apache.commons.cli.DeprecatedAttributes</td>
+          <td>Marks the option as deprecated and has the deprecation properties.</td>
         </tr>
         <tr>
-          <td>args</td>
-          <td>boolean</td>
-          <td>a flag to say whether the option takes more than one argument</td>
+          <td>description</td>
+          <td>java.lang.String</td>
+          <td>A description of the function of the option.</td>
         </tr>
         <tr>
-          <td>optionalArg</td>
-          <td>boolean</td>
-          <td>a flag to say whether the option's argument is optional</td>
+          <td>longOpt</td>
+          <td>java.lang.String</td>
+          <td>An alias and more descriptive identification string. May be null or not specified if 'opt' is provided.</td>
         </tr>
         <tr>
-          <td>argName</td>
+          <td>opt</td>
           <td>java.lang.String</td>
-          <td>the name of the argument value for the usage statement</td>
+          <td>The identification string of the Option. May be null or not specified if 'longOpt' is provided.</td>
         </tr>
         <tr>
-          <td>valueSeparator</td>
-          <td>char</td>
-          <td>the character value used to split the argument string, that
-            is used in conjunction with multipleArgs e.g.
-            if the separator is ',' and the argument string is 'a,b,c' then
-            there are three argument values, 'a', 'b' and 'c'.</td>
+          <td>optionalArg</td>
+          <td>boolean</td>
+          <td>A flag to say whether the option's argument is optional.</td>
+        </tr>
+        <tr>
+          <td>required</td>
+          <td>boolean</td>
+          <td>A flag to say whether the option <b>must</b> appear on the command line.</td>
         </tr>
         <tr>
           <td>type</td>
-          <td>java.lang.Object</td>
-          <td>the type of the argument</td>
+          <td>java.lang.Class&lt;?&gt;</td>
+          <td>The class of the object returned from getParsedValue(). The class must be registered in TypeHandler instance.
+            See also 'converter' property.</td>
         </tr>
         <tr>
           <td>value</td>
           <td>java.lang.String</td>
-          <td>the value of the option</td>
+          <td>The value of the option.</td>
         </tr>
         <tr>
           <td>values</td>
           <td>java.lang.String[]</td>
-          <td>the values of the option</td>
+          <td>The values of the option.</td>
+        </tr>
+        <tr>
+          <td>valueSeparator</td>
+          <td>char</td>
+          <td>The character value used to split the argument string, that is used in conjunction with multipleArgs e.g.
+            if the separator is ',' and the argument string is 'a,b,c' then there are three argument values, 'a', 'b'
+            and 'c'.</td>
         </tr>
       </table>
     </section>