refactor: obsolete throwOnUnexpectedArg in favor of UnrecognizedArgumentHandling enum

Author: natemcmaster

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-[Unreleased changes](https://github.com/natemcmaster/CommandLineUtils/compare/v2.5.0...HEAD):
+[Unreleased changes](https://github.com/natemcmaster/CommandLineUtils/compare/v2.5.1...HEAD):
+
+## [v2.6.0](https://github.com/natemcmaster/CommandLineUtils/compare/v2.5.1...v2.6.0)
+
+* Refactor: obsolete throwOnUnexpectedArg in favor of UnrecognizedArgumentHandling. See https://github.com/natemcmaster/CommandLineUtils/issues/339 for details
 
 ## [v2.5.1](https://github.com/natemcmaster/CommandLineUtils/compare/v2.5.0...v2.5.1)
 

docs/docs/arguments.md

@@ -145,8 +145,8 @@ or the Windows command `cmd` take some arguments, and pass the rest on to the co
 > In this example, `-l` is an option on `time`. This starts a timer which then invokes `ls` with additional arguments.
 > `-l` is also an option on `ls`.
 
-Normally, unrecognized arguments is an error. You must set ThrowOnUnexpectedArgument to `false` to allow the parser
-to allow unrecognized arguments and options.
+Normally, unrecognized arguments is an error. You must set `UnrecognizedArgumentHandling` to `StopParsingAndCollect` to allow the parser
+to collect unrecognized arguments and options.
 
 ### The double-dash convention `--`
 
@@ -171,6 +171,6 @@ to include all values. See @McMaster.Extensions.CommandLineUtils.Conventions.Rem
 
 ### [Using Builder API](#tab/using-builder-api)
 
-When `throwOnUnexpctedArg` is set to false,
+When `UnrecognizedArgumentHandling` is set to `Stop`,
 
 [!code-csharp[Program](../samples/passthru-args/builder-api/Program.cs)]

docs/samples/passthru-args/attributes/Program.cs

@@ -3,7 +3,9 @@
 using System.Linq;
 using McMaster.Extensions.CommandLineUtils;
 
-[Command(ThrowOnUnexpectedArgument = false, AllowArgumentSeparator = true)]
+[Command(
+    UnrecognizedArgumentHandling = UnrecognizedArgumentHandling.StopParsingAndCollect,
+    AllowArgumentSeparator = true)]
 public class Program
 {
     public static int Main(string[] args) => CommandLineApplication.Execute<Program>(args);

docs/samples/passthru-args/builder-api/Program.cs

@@ -7,9 +7,10 @@ public class Program
 {
     public static int Main(string[] args)
     {
-        var app = new CommandLineApplication(throwOnUnexpectedArg: false)
+        var app = new CommandLineApplication
         {
-            AllowArgumentSeparator = true
+            AllowArgumentSeparator = true,
+            UnrecognizedArgumentHandling = UnrecognizedArgumentHandling.StopParsingAndCollect,
         };
 
         var showMilliseconds = app.Option<int>("-m", "Show time in milliseconds", CommandOptionType.NoValue);

docs/samples/subcommands/nested-types/Program.cs

@@ -57,7 +57,7 @@ private void OnExecute(IConsole console)
 
             [Command("run", Description = "Run a command in a new container",
                 AllowArgumentSeparator = true,
-                ThrowOnUnexpectedArgument = false)]
+                UnrecognizedArgumentHandling = UnrecognizedArgumentHandling.StopParsingAndCollect)]
             private class Run
             {
                 [Required(ErrorMessage = "You must specify the image name")]
@@ -94,7 +94,7 @@ private int OnExecute(IConsole console)
 
 
             [Command("ls", Description = "List images",
-                ThrowOnUnexpectedArgument = false)]
+                UnrecognizedArgumentHandling = UnrecognizedArgumentHandling.StopParsingAndCollect)]
             private class List
             {
                 [Option(Description = "Show all containers (default shows just running)")]

src/CommandLineUtils/Attributes/CommandAttribute.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.ComponentModel;
 using System.Globalization;
 using System.Linq;
 
@@ -90,10 +91,30 @@ public string? Name
         public string? ExtendedHelpText { get; set; }
 
         /// <summary>
+        /// <para>
+        /// This property is obsolete and will be removed in a future version.
+        /// The recommended replacement is <seealso cref="UnrecognizedArgumentHandling"/>.
+        /// </para>
+        /// <para>
         /// Throw when unexpected arguments are encountered.
+        /// </para>
         /// </summary>
         /// <seealso cref="CommandLineApplication.ThrowOnUnexpectedArgument"/>
-        public bool ThrowOnUnexpectedArgument { get; set; } = true;
+        [Obsolete("This property is obsolete and will be removed in a future version. " +
+            "The recommended replacement is UnrecognizedArgumentHandling.")]
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public bool ThrowOnUnexpectedArgument
+        {
+            get => UnrecognizedArgumentHandling == UnrecognizedArgumentHandling.Throw;
+            set => UnrecognizedArgumentHandling = value
+                ? UnrecognizedArgumentHandling.Throw
+                : UnrecognizedArgumentHandling.StopParsingAndCollect;
+        }
+
+        /// <summary>
+        /// Set the behavior for how to handle unrecognized arguments.
+        /// </summary>
+        public UnrecognizedArgumentHandling UnrecognizedArgumentHandling { get; set; } = UnrecognizedArgumentHandling.Throw;
 
         /// <summary>
         /// Allow '--' to be used to stop parsing arguments.
@@ -167,7 +188,7 @@ internal void Configure(CommandLineApplication app)
             app.FullName = FullName;
             app.ResponseFileHandling = ResponseFileHandling;
             app.ShowInHelpText = ShowInHelpText;
-            app.ThrowOnUnexpectedArgument = ThrowOnUnexpectedArgument;
+            app.UnrecognizedArgumentHandling = UnrecognizedArgumentHandling;
             app.OptionsComparison = OptionsComparison;
             app.ValueParsers.ParseCulture = ParseCulture;