Add builder factory CommandLine#builder()

Author: garydgregory

src/changes/changes.xml

@@ -36,6 +36,7 @@
       <action type="add" issue="CLI-324" dev="ggregory" due-to="Claude Warren, Gary Gregory">Make adding OptionGroups and Options to existing Options easier #230.</action>
       <action type="add" issue="CLI-323" dev="ggregory" due-to="Claude Warren, Gary Gregory">Added Supplier&lt;T&gt; defaults for getParsedOptionValue #229.</action>
       <action type="add" issue="CLI-326" dev="ggregory" due-to="Claude Warren, Gary Gregory">Make Option.getKey() public #239.</action>
+      <action type="add" dev="ggregory" due-to="Claude Warren, Gary Gregory">Add builder factory CommandLine#builder().</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory" due-to="Gary Gregory">Bump commons-parent from 64 to 67.</action>
       <action type="update" dev="ggregory" due-to="Elric, Gary Gregory">Update the tests to JUnit 5 #238.</action>

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

@@ -24,6 +24,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 import java.util.Iterator;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Objects;
 import java.util.Properties;
 import java.util.function.Supplier;
 
@@ -46,10 +47,11 @@ public class CommandLine implements Serializable {
      */
     public static final class Builder {
 
-        /**
-         * CommandLine that is being build by this Builder.
-         */
-        private final CommandLine commandLine = new CommandLine();
+        /** The unrecognized options/arguments */
+        private final List<String> args = new LinkedList<>();
+
+        /** The processed options */
+        private final List<Option> options = new ArrayList<>();
 
         /**
          * Adds left-over unrecognized option/argument.
@@ -59,7 +61,9 @@ public static final class Builder {
          * @return this Builder instance for method chaining.
          */
         public Builder addArg(final String arg) {
-            commandLine.addArg(arg);
+            if (arg != null) {
+                args.add(arg);
+            }
             return this;
         }
 
@@ -71,7 +75,9 @@ public Builder addArg(final String arg) {
          * @return this Builder instance for method chaining.
          */
         public Builder addOption(final Option opt) {
-            commandLine.addOption(opt);
+            if (opt != null) {
+                options.add(opt);
+            }
             return this;
         }
 
@@ -81,24 +87,42 @@ public Builder addOption(final Option opt) {
          * @return the new instance.
          */
         public CommandLine build() {
-            return commandLine;
+            return new CommandLine(args, options);
         }
     }
 
+    /**
+     * Creates a new builder.
+     *
+     * @return a new builder.
+     * @since 1.7.0
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /** The serial version UID. */
     private static final long serialVersionUID = 1L;
 
     /** The unrecognized options/arguments */
-    private final List<String> args = new LinkedList<>();
+    private final List<String> args;
 
     /** The processed options */
-    private final List<Option> options = new ArrayList<>();
+    private final List<Option> options;
 
     /**
      * Creates a command line.
      */
     protected CommandLine() {
-        // nothing to do
+        this(new LinkedList<>(), new ArrayList<>());
+    }
+
+    /**
+     * Creates a command line.
+     */
+    private CommandLine(final List<String> args, final List<Option> options) {
+        this.args = Objects.requireNonNull(args, "args");
+        this.options = Objects.requireNonNull(options, "options");
     }
 
     /**

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

@@ -677,7 +677,7 @@ public CommandLine parse(final Options options, final String[] arguments, final
             group.setSelected(null);
         }
 
-        cmd = new CommandLine();
+        cmd = CommandLine.builder().build();
 
         if (arguments != null) {
             for (final String argument : arguments) {

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

@@ -156,7 +156,7 @@ public CommandLine parse(final Options options, final String[] arguments, final
         // initialize members
         setOptions(options);
 
-        cmd = new CommandLine();
+        cmd = CommandLine.builder().build();
 
         boolean eatTheRest = false;
 

src/test/java/org/apache/commons/cli/CommandLineTest.java

@@ -113,7 +113,20 @@ public void testGetOptionPropertiesWithOption() throws Exception {
     }
 
     @Test
-    public void testGetOptions() {
+    public void testGetOptionsBuilder() {
+        final CommandLine cmd = CommandLine.builder().build();
+        assertNotNull(cmd.getOptions());
+        assertEquals(0, cmd.getOptions().length);
+
+        cmd.addOption(new Option("a", null));
+        cmd.addOption(new Option("b", null));
+        cmd.addOption(new Option("c", null));
+
+        assertEquals(3, cmd.getOptions().length);
+    }
+
+    @Test
+    public void testGetOptionsCtor() {
         final CommandLine cmd = new CommandLine();
         assertNotNull(cmd.getOptions());
         assertEquals(0, cmd.getOptions().length);