introduce ParseResult.GetValue<T>(string name)

src/System.CommandLine.ApiCompatibility.Tests/ApiCompatibilityApprovalTests.System_CommandLine_api_is_not_changed.approved.txt

@@ -174,6 +174,7 @@ System.CommandLine
     public System.Collections.Generic.IEnumerable<System.CommandLine.Completions.CompletionItem> GetCompletions(System.Nullable<System.Int32> position = null)
     public T GetValue<T>(Argument<T> argument)
     public T GetValue<T>(Option<T> option)
+    public T GetValue<T>(System.String name)
     public System.Int32 Invoke(IConsole console = null)
     public System.Threading.Tasks.Task<System.Int32> InvokeAsync(IConsole console = null, System.Threading.CancellationToken cancellationToken = null)
     public System.String ToString()

src/System.CommandLine.Hosting.Tests/HostingHandlerTest.cs

@@ -206,7 +206,7 @@ public class MyOtherCommand : Command
             public MyOtherCommand() : base(name: "myothercommand")
             {
                 Options.Add(new Option<int>("--int-option")); // or nameof(Handler.IntOption).ToKebabCase() if you don't like the string literal
-                Arguments.Add(new Argument<string>("One"));
+                Arguments.Add(new Argument<string>("One") {  Arity = ArgumentArity.ZeroOrOne });
             }
 
             public class MyHandler : ICommandHandler

src/System.CommandLine.Tests/GetValueByNameParserTests.cs

@@ -0,0 +1,290 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using FluentAssertions;
+using System.Collections.Generic;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace System.CommandLine.Tests
+{
+    public class GetValueByNameParserTests : ParserTests
+    {
+        public GetValueByNameParserTests(ITestOutputHelper output) : base(output)
+        {
+        }
+
+        protected override T GetValue<T>(ParseResult parseResult, Option<T> option)
+            => parseResult.GetValue<T>(option.Name);
+
+        protected override T GetValue<T>(ParseResult parseResult, Argument<T> argument)
+            => parseResult.GetValue<T>(argument.Name);
+
+        [Fact]
+        public void In_case_of_argument_name_conflict_the_value_which_belongs_to_the_last_parsed_command_is_returned()
+        {
+            RootCommand command = new()
+            {
+                new Argument<int>("arg"),
+                new Command("inner1")
+                {
+                    new Argument<int>("arg"),
+                    new Command("inner2")
+                    {
+                        new Argument<int>("arg"),
+                    }
+                }
+            };
+
+            ParseResult parseResult = command.Parse("1 inner1 2 inner2 3");
+
+            parseResult.GetValue<int>("arg").Should().Be(3);
+        }
+
+        [Fact]
+        public void In_case_of_option_name_conflict_the_value_which_belongs_to_the_last_parsed_command_is_returned()
+        {
+            RootCommand command = new()
+            {
+                new Option<int>("--integer", "-i"),
+                new Command("inner1")
+                {
+                    new Option<int>("--integer", "-i"),
+                    new Command("inner2")
+                    {
+                        new Option<int>("--integer", "-i")
+                    }
+                }
+            };
+
+            ParseResult parseResult = command.Parse("-i 1 inner1 --integer 2 inner2 -i 3");
+
+            parseResult.GetValue<int>("--integer").Should().Be(3);
+        }
+
+        [Fact]
+        public void When_option_value_is_not_parsed_then_default_value_is_returned()
+        {
+            RootCommand command = new()
+            {
+                new Option<int>("--integer", "-i")
+            };
+
+            ParseResult parseResult = command.Parse("");
+
+            parseResult.GetValue<int>("--integer").Should().Be(default);
+        }
+
+        [Fact]
+        public void When_optional_argument_is_not_parsed_then_default_value_is_returned()
+        {
+            RootCommand command = new()
+            {
+                new Argument<int>("arg")
+                {
+                    Arity = ArgumentArity.ZeroOrOne
+                }
+            };
+
+            ParseResult parseResult = command.Parse("");
+
+            parseResult.GetValue<int>("arg").Should().Be(default);
+        }
+
+        [Fact]
+        public void When_required_option_value_is_not_parsed_then_an_exception_is_thrown()
+        {
+            RootCommand command = new()
+            {
+                new Option<int>("--required")
+                {
+                    IsRequired = true
+                }
+            };
+
+            ParseResult parseResult = command.Parse("");
+
+            Action getRequired = () => parseResult.GetValue<int>("--required");
+
+            getRequired
+                .Should()
+                .Throw<InvalidOperationException>()
+                .Where(ex => ex.Message == LocalizationResources.RequiredOptionWasNotProvided("--required"));
+        }
+
+        [Fact]
+        public void When_required_argument_value_is_not_parsed_then_an_exception_is_thrown()
+        {
+            RootCommand command = new()
+            {
+                new Argument<int>("required")
+                {
+                    Arity = ArgumentArity.ExactlyOne
+                }
+            };
+
+            ParseResult parseResult = command.Parse("");
+
+            Action getRequired = () => parseResult.GetValue<int>("required");
+
+            getRequired
+                .Should()
+                .Throw<InvalidOperationException>()
+                .Where(ex => ex.Message == LocalizationResources.RequiredArgumentMissing(parseResult.FindResultFor(command.Arguments[0])));
+        }
+
+        [Fact]
+        public void When_non_existing_name_is_used_then_exception_is_thrown()
+        {
+            const string nonExistingName = "nonExisting";
+            Command command = new ("noSymbols");
+            ParseResult parseResult = command.Parse("");
+
+            Action getRequired = () => parseResult.GetValue<int>(nonExistingName);
+
+            getRequired
+                .Should()
+                .Throw<ArgumentException>()
+                .Where(ex => ex.Message == $"No symbol result found for \"{nonExistingName}\" for command \"{command.Name}\".");
+        }
+
+        [Fact]
+        public void When_an_option_and_argument_use_same_name_on_the_same_level_of_the_tree_an_exception_is_thrown()
+        {
+            const string sameName = "same";
+
+            RootCommand command = new()
+            {
+                new Argument<int>(sameName)
+                {
+                    Arity = ArgumentArity.ZeroOrOne
+                },
+                new Option<int>(sameName)
+            };
+
+            ParseResult parseResult = command.Parse("");
+
+            Action getConflicted = () => parseResult.GetValue<int>(sameName);
+
+            getConflicted
+                .Should()
+                .Throw<NotSupportedException>()
+                .Where(ex => ex.Message == $"More than one symbol uses name \"{sameName}\" for command \"{command.Name}\".");
+        }
+
+        [Fact]
+        public void When_an_option_and_argument_use_same_name_on_different_levels_of_the_tree_the_value_which_belongs_to_parsed_command_is_returned()
+        {
+            const string sameName = "same";
+
+            Command command = new("outer")
+            {
+                new Argument<int>(sameName),
+                new Command("inner")
+                {
+                    new Option<int>(sameName)
+                }
+            };
+
+            ParseResult parseResult = command.Parse($"outer 123 inner {sameName} 456");
+            parseResult.GetValue<int>(sameName).Should().Be(456);
+
+            parseResult = command.Parse($"outer 123");
+            parseResult.GetValue<int>(sameName).Should().Be(123);
+        }
+
+        [Fact]
+        public void When_an_option_and_argument_use_same_name_on_different_levels_of_the_tree_the_default_value_which_belongs_to_parsed_command_is_returned()
+        {
+            const string sameName = "same";
+
+            Command command = new("outer")
+            {
+                new Argument<int>(sameName)
+                {
+                    DefaultValueFactory = (_) => 123
+                },
+                new Command("inner")
+                {
+                    new Option<int>(sameName)
+                    {
+                        DefaultValueFactory = (_) => 456
+                    }
+                }
+            };
+
+            ParseResult parseResult = command.Parse($"outer inner 456");
+            parseResult.GetValue<int>(sameName).Should().Be(456);
+
+            parseResult = command.Parse($"outer 123");
+            parseResult.GetValue<int>(sameName).Should().Be(123);
+        }
+
+        [Fact]
+        public void T_can_be_casted_to_nullable_of_T()
+        {
+            RootCommand command = new()
+            {
+                new Argument<int>("name")
+            };
+
+            ParseResult parseResult = command.Parse("123");
+
+            parseResult.GetValue<int?>("name").Should().Be(123);
+        }
+
+        [Fact]
+        public void Array_of_T_can_be_casted_to_ienumerable_of_T()
+        {
+            RootCommand command = new()
+            {
+                new Argument<int[]>("name")
+            };
+
+            ParseResult parseResult = command.Parse("1 2 3");
+
+            parseResult.GetValue<IEnumerable<int>>("name").Should().BeEquivalentTo(new int[] { 1, 2, 3 });
+        }
+
+        [Fact]
+        public void When_casting_is_not_allowed_an_exception_is_thrown()
+        {
+            const string Name = "name";
+
+            RootCommand command = new()
+            {
+                new Argument<int>(Name)
+            };
+
+            ParseResult parseResult = command.Parse("123");
+
+            Assert(() => parseResult.GetValue<double>(Name));
+            Assert(() => parseResult.GetValue<int[]>(Name));
+            Assert(() => parseResult.GetValue<string>(Name));
+
+            static void Assert(Action invalidCast)
+                => invalidCast.Should().Throw<InvalidCastException>();
+        }
+
+        [Fact]
+        public void Parse_errors_have_precedence_over_type_mismatch()
+        {
+            RootCommand command = new()
+            {
+                new Option<int>("--required")
+                {
+                    IsRequired = true
+                }
+            };
+
+            ParseResult parseResult = command.Parse("");
+
+            Action getRequiredWithTypeMismatch = () => parseResult.GetValue<double>("--required");
+
+            getRequiredWithTypeMismatch
+                .Should()
+                .Throw<InvalidOperationException>()
+                .Where(ex => ex.Message == LocalizationResources.RequiredOptionWasNotProvided("--required"));
+        }
+    }
+}

src/System.CommandLine.Tests/GetValueByNameTypeConversionTests.cs

@@ -0,0 +1,19 @@
+using System.CommandLine.Tests.Binding;
+
+namespace System.CommandLine.Tests
+{
+    public class GetValueByNameTypeConversionTests : TypeConversionTests
+    {
+        protected override T GetValue<T>(Argument<T> argument, string commandLine)
+        {
+            var result = new RootCommand { argument }.Parse(commandLine);
+            return result.GetValue<T>(argument.Name);
+        }
+
+        protected override T GetValue<T>(Option<T> option, string commandLine)
+        {
+            var result = new RootCommand { option }.Parse(commandLine);
+            return result.GetValue<T>(option.Name);
+        }
+    }
+}

src/System.CommandLine.Tests/ParserTests.DoubleDash.cs

@@ -1,7 +1,6 @@
 // Copyright (c) .NET Foundation and contributors. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-using System.CommandLine.Parsing;
 using System.CommandLine.Tests.Utility;
 using FluentAssertions;
 using Xunit;

src/System.CommandLine.Tests/ParserTests.MultipleArguments.cs

@@ -257,7 +257,7 @@ public void Unsatisfied_subsequent_argument_with_min_arity_1_parses_as_default_v
 
                 var result = rootCommand.Parse("");
 
-                result.FindResultFor(arg1).Should().BeNull();
+                result.FindResultFor(arg1).Should().NotBeNull();
                 result.GetValue(arg2).Should().Be("the-default");
             }
 
@@ -299,12 +299,9 @@ public void When_there_are_not_enough_tokens_for_all_arguments_then_the_correct_
 
                 var result = Parser.Parse(command, providedArgs);
 
-                var numberOfMissingArgs =
-                    result
-                        .Errors
-                        .Count(e => e.Message == LocalizationResources.RequiredArgumentMissing(result.CommandResult));
-
-                numberOfMissingArgs
+                result
+                    .Errors
+                    .Count
                     .Should()
                     .Be(4 - providedArgs.Split(new[] { ' ' }, StringSplitOptions.RemoveEmptyEntries).Length);
             }