Merge branch 'release/3.0' into merge/release/3.0-preview9-to-release/3.0\n\nCommit migrated from dotnet/extensions@07c506d

Author: pranavkm

src/Shared/CommandLineUtils/CommandLine/CommandLineApplication.cs

@@ -13,14 +13,23 @@ namespace Microsoft.Extensions.CommandLineUtils
 {
     internal class CommandLineApplication
     {
-        // Indicates whether the parser should throw an exception when it runs into an unexpected argument.
-        // If this field is set to false, the parser will stop parsing when it sees an unexpected argument, and all
-        // remaining arguments, including the first unexpected argument, will be stored in RemainingArguments property.
+        // Indicates whether the parser should throw an exception when it runs into an unexpected argument. If this is
+        // set to true (the default), the parser will throw on the first unexpected argument. Otherwise, all unexpected
+        // arguments (including the first) are added to RemainingArguments.
         private readonly bool _throwOnUnexpectedArg;
 
-        public CommandLineApplication(bool throwOnUnexpectedArg = true)
+        // Indicates whether the parser should check remaining arguments for command or option matches after
+        // encountering an unexpected argument. Ignored if _throwOnUnexpectedArg is true (the default). If
+        // _throwOnUnexpectedArg and this are both false, the first unexpected argument and all remaining arguments are
+        // added to RemainingArguments. If _throwOnUnexpectedArg is false and this is true, only unexpected arguments
+        // are added to RemainingArguments -- allowing a mix of expected and unexpected arguments, commands and
+        // options.
+        private readonly bool _continueAfterUnexpectedArg;
+
+        public CommandLineApplication(bool throwOnUnexpectedArg = true, bool continueAfterUnexpectedArg = false)
         {
             _throwOnUnexpectedArg = throwOnUnexpectedArg;
+            _continueAfterUnexpectedArg = continueAfterUnexpectedArg;
             Options = new List<CommandOption>();
             Arguments = new List<CommandArgument>();
             Commands = new List<CommandLineApplication>();
@@ -145,6 +154,7 @@ public int Execute(params string[] args)
                     {
                         shortOption = arg.Substring(1).Split(new[] { ':', '=' }, 2);
                     }
+
                     if (longOption != null)
                     {
                         processed = true;
@@ -153,13 +163,27 @@ public int Execute(params string[] args)
 
                         if (option == null)
                         {
-                            if (string.IsNullOrEmpty(longOptionName) && !command._throwOnUnexpectedArg  && AllowArgumentSeparator)
+                            var ignoreContinueAfterUnexpectedArg = false;
+                            if (string.IsNullOrEmpty(longOptionName) &&
+                                !command._throwOnUnexpectedArg &&
+                                AllowArgumentSeparator)
                             {
-                                // skip over the '--' argument separator
+                                // Skip over the '--' argument separator then consume all remaining arguments. All
+                                // remaining arguments are unconditionally stored for further use.
                                 index++;
+                                ignoreContinueAfterUnexpectedArg = true;
+                            }
+
+                            if (HandleUnexpectedArg(
+                                command,
+                                args,
+                                index,
+                                argTypeName: "option",
+                                ignoreContinueAfterUnexpectedArg))
+                            {
+                                continue;
                             }
 
-                            HandleUnexpectedArg(command, args, index, argTypeName: "option");
                             break;
                         }
 
@@ -191,6 +215,7 @@ public int Execute(params string[] args)
                             option = null;
                         }
                     }
+
                     if (shortOption != null)
                     {
                         processed = true;
@@ -204,7 +229,11 @@ public int Execute(params string[] args)
 
                         if (option == null)
                         {
-                            HandleUnexpectedArg(command, args, index, argTypeName: "option");
+                            if (HandleUnexpectedArg(command, args, index, argTypeName: "option"))
+                            {
+                                continue;
+                            }
+
                             break;
                         }
 
@@ -268,6 +297,7 @@ public int Execute(params string[] args)
                         processed = true;
                     }
                 }
+
                 if (!processed)
                 {
                     if (arguments == null)
@@ -280,9 +310,14 @@ public int Execute(params string[] args)
                         arguments.Current.Values.Add(arg);
                     }
                 }
+
                 if (!processed)
                 {
-                    HandleUnexpectedArg(command, args, index, argTypeName: "command or argument");
+                    if (HandleUnexpectedArg(command, args, index, argTypeName: "command or argument"))
+                    {
+                        continue;
+                    }
+
                     break;
                 }
             }
@@ -490,17 +525,29 @@ public void ShowRootCommandFullNameAndVersion()
             Out.WriteLine();
         }
 
-        private void HandleUnexpectedArg(CommandLineApplication command, string[] args, int index, string argTypeName)
+        private bool HandleUnexpectedArg(
+            CommandLineApplication command,
+            string[] args,
+            int index,
+            string argTypeName,
+            bool ignoreContinueAfterUnexpectedArg = false)
         {
             if (command._throwOnUnexpectedArg)
             {
                 command.ShowHint();
                 throw new CommandParsingException(command, $"Unrecognized {argTypeName} '{args[index]}'");
             }
+            else if (_continueAfterUnexpectedArg && !ignoreContinueAfterUnexpectedArg)
+            {
+                // Store argument for further use.
+                command.RemainingArguments.Add(args[index]);
+                return true;
+            }
             else
             {
-                // All remaining arguments are stored for further use
+                // Store all remaining arguments for later use.
                 command.RemainingArguments.AddRange(new ArraySegment<string>(args, index, args.Length - index));
+                return false;
             }
         }