[API proposal]: System.CommandLine APIs

[KathleenDollard]

Updated version: https://github.com/dotnet/runtime/issues/68578#issuecomment-1490627545

Old version:

## Background and motivation System.CommandLine is finalizing GA and is thus looking for a final design review prior to V1. There have been significant changes since the previous design review 2 years ago, driven by API review feedback, user feedback, and especially improvements in performance and to enable trimming. Since the surface area is large, we suggest focusing on these questions: ### Namespace reorganization Following the previous API review we segmented the namespaces to specific areas in order to surface the most important types in the root `System.CommandLine` namespace. This resulted in needing a significant number of using statements, as pointed out in the issue [System.CommandLine is split into too many namespaces](https://github.com/dotnet/command-line-api/issues/1680). We'd like to discuss how we balance between too many and too few namespaces. ### Ergonomics Previous feedback included that the coding UX was rather complicated. We have done some simplification, and we have [docs](https://docs.microsoft.com/dotnet/standard/commandline/), but we believe fundamental simplification will require an opinionated layer, probably with source generation for Rolsyn. A community member created a very nice layer for [F# based on computation expressions](https://github.com/JordanMarr/FSharp.SystemCommandLine). Our choice is to keep System.CommandLine as it is and allow these layers to simplify the less complicated use cases. Usability of System.CommandLine has been shown in both static mode (.NET CLI) and dynmaic mode (`dotnet new`). We also have experience with significantly different models with the very popular Dragonfruit, and prototyping subcommands. One of the reasons we want to build a foundation for an opinionated layer is that this is where the community can explore options, including wrappers for current styles used in other parsers. We wanted to check in on thinking around tooling related to API's now that we have source generation as an approach. ### SetHandler One of the things we do to simplify using the API is SetHandler which connects a command with a function/lambda and passes the results for arguments and options. This is effective, and we think is the best approach prior to opinionated layers. However, there are two areas of issues: * Because the delegates are generic and there may be any number of arguments and thus many overloads differing on generic arity, we have 16 overloads of each of the 2 patterns - void returning and task returning. We also document special handling where 16 arguments and options are not enough. * As seen in the [Simple sample](#simple-sample), there is redundancy to pass the option to the SetHandler method. The main mechanism was previously name based, and it was the major source of user issues. We have moved name-based matching into a separate package so it is available for backwards compatibility. Prototyping has confirmed that opinionated layers do not need SetHandler, so we think these issues are ugly, but that this will be an important secondary mechanism for complex CLI's and we do not see a way to avoid it. ### IConsole For testing and other issues we needed an abstraction for Console. We created an interface named IConsole. We strongly hope that .NET will have a future abstraction in lieu of or working with System.Console and hope to avoid a naming collision. At the last API review, our feedback was that an abstraction was very, very unlikely to be an interface, and we wanted to check that was still the case. ### TestConsole We have a buffered console that is used in our testing and we think anyone testing their console output will find valuable. The name indicates more how it is expected to be used than what it is. We think it should be public to help folks, and we think this name is fine since the purpose is the most important thing. ## API Proposal The current state of this proposal can be seen below: https://github.com/dotnet/runtime/issues/68578#issuecomment-1461983285

Previous version

This output is from our unit test for ensuring PRs do not change the API surface area unexpectedly, and thus is in a slightly non-standard format: ```csharp namespace System.CommandLine { public abstract class Argument : Symbol, IValueDescriptor, ICompletionSource { public ArgumentArity Arity { get; set; } public CompletionSourceList Completions { get; } public bool HasDefaultValue { get; } public string HelpName { get; set; } public Type ValueType { get; } public void AddValidator(ValidateSymbolResult validate); public IEnumerable GetCompletions(CompletionContext context); public object GetDefaultValue(); public void SetDefaultValue(object value); public void SetDefaultValueFactory(Func

[dotnet-issue-labeler[bot]]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[jkotas]

Simple sample This is a CLI with a single root command and a single option which has an argument:

There is no reason for a simple apps like this one to be async. It just adds unnecessary overhead.

[jkotas]

Complex sample This sample has multiple commands with numerous options. The first option does custom validation

It may be a good idea to show the alternative pattern for more than 16 options that the generic overload does not handle. I have run into 16 options limit quite often in the apps that I have tried to port to System.CommandLine.

I would recommend the generic SetHandler overload for up to say 5 options. It is better to use the alternative pattern beyond that - easier to maintain than a method with very large number of arguments.

[jonsequitur]

Would you recommend reducing the number of overloads then? This could make it easier to find the synchronous versus asynchronous variations within the list.

[jkotas]

Would you recommend reducing the number of overloads then?

Yes. I think having the generic overloads for up to 8 options would be enough.

[tannergooding]

Can we add braces to the proposal and newlines between types. The proposal is fairly difficult to follow and see what starts and ends where.

[tannergooding]

Normalizing to keywords (System.String to string, etc) would also help with the review

[ghost]

Tagging subscribers to this area: @dotnet/area-system-runtime See info in area-owners.md if you want to be subscribed.

Issue Details

---

## Background and motivation System.CommandLine is finalizing GA and is thus looking for a final design review prior to V1. There have been significant changes since the previous design review 2 years ago, driven by API review feedback, user feedback, and especially improvements in performance and to enable trimming. Since the surface area is large, we suggest focusing on these questions: ### Namespace reorganization Following the previous API review we segmented the namespaces to specific areas in order to surface the most important types in the root `System.CommandLine` namespace. This resulted in needing a significant number of using statements, as pointed out in the issue [System.CommandLine is split into too many namespaces](https://github.com/dotnet/command-line-api/issues/1680). We'd like to discuss how we balance between too many and too few namespaces. ### Ergonomics Previous feedback included that the coding UX was rather complicated. We have done some simplification, and we have [docs](https://docs.microsoft.com/dotnet/standard/commandline/), but we believe fundamental simplification will require an opinionated layer, probably with source generation for Rolsyn. A community member created a very nice layer for [F# based on computation expressions](https://github.com/JordanMarr/FSharp.SystemCommandLine). Our choice is to keep System.CommandLine as it is and allow these layers to simplify the less complicated use cases. Usability of System.CommandLine has been shown in both static mode (.NET CLI) and dynmaic mode (`dotnet new`). We also have experience with significantly different models with the very popular Dragonfruit, and prototyping subcommands. One of the reasons we want to build a foundation for an opinionated layer is that this is where the community can explore options, including wrappers for current styles used in other parsers. We wanted to check in on thinking around tooling related to API's now that we have source generation as an approach. ### SetHandler One of the things we do to simplify using the API is SetHandler which connects a command with a function/lambda and passes the results for arguments and options. This is effective, and we think is the best approach prior to opinionated layers. However, there are two areas of issues: * Because the delegates are generic and there may be any number of arguments and thus many overloads differing on generic arity, we have 16 overloads of each of the 2 patterns - void returning and task returning. We also document special handling where 16 arguments and options are not enough. * As seen in the [Simple sample](#simple-sample), there is redundancy to pass the option to the SetHandler method. The main mechanism was previously name based, and it was the major source of user issues. We have moved name-based matching into a separate package so it is available for backwards compatibility. Prototyping has confirmed that opinionated layers do not need SetHandler, so we think these issues are ugly, but that this will be an important secondary mechanism for complex CLI's and we do not see a way to avoid it. ### IConsole For testing and other issues we needed an abstraction for Console. We created an interface named IConsole. We strongly hope that .NET will have a future abstraction in lieu of or working with System.Console and hope to avoid a naming collision. At the last API review, our feedback was that an abstraction was very, very unlikely to be an interface, and we wanted to check that was still the case. ### TestConsole We have a buffered console that is used in our testing and we think anyone testing their console output will find valuable. The name indicates more how it is expected to be used than what it is. We think it should be public to help folks, and we think this name is fine since the purpose is the most important thing. ## API Proposal This output is from our unit test for ensuring PRs do not change the API surface area unexpectedly, and thus is in a slightly non-standard format: ```csharp System.CommandLine public abstract class Argument : Symbol, System.CommandLine.Binding.IValueDescriptor, System.CommandLine.Completions.ICompletionSource public ArgumentArity Arity { get; set; } public CompletionSourceList Completions { get; } public System.Boolean HasDefaultValue { get; } public System.String HelpName { get; set; } public System.Type ValueType { get; } public System.Void AddValidator(System.CommandLine.Parsing.ValidateSymbolResult validate) public System.Collections.Generic.IEnumerable GetCompletions(System.CommandLine.Completions.CompletionContext context) public System.Object GetDefaultValue() public System.Void SetDefaultValue(System.Object value) public System.Void SetDefaultValueFactory(System.Func getDefaultValue) public System.Void SetDefaultValueFactory(System.Func getDefaultValue) public System.String ToString() public class Argument : Argument, IValueDescriptor, System.CommandLine.Binding.IValueDescriptor, System.CommandLine.Completions.ICompletionSource .ctor() .ctor(System.String name, System.String description = null) .ctor(System.String name, Func getDefaultValue, System.String description = null) .ctor(Func getDefaultValue) .ctor(System.String name, ParseArgument parse, System.Boolean isDefault = False, System.String description = null) .ctor(ParseArgument parse, System.Boolean isDefault = False) public System.Type ValueType { get; } public struct ArgumentArity : System.ValueType, System.IEquatable public static ArgumentArity ExactlyOne { get; } public static ArgumentArity OneOrMore { get; } public static ArgumentArity Zero { get; } public static ArgumentArity ZeroOrMore { get; } public static ArgumentArity ZeroOrOne { get; } .ctor(System.Int32 minimumNumberOfValues, System.Int32 maximumNumberOfValues) public System.Int32 MaximumNumberOfValues { get; } public System.Int32 MinimumNumberOfValues { get; } public System.Boolean Equals(ArgumentArity other) public System.Boolean Equals(System.Object obj) public System.Int32 GetHashCode() public static class ArgumentExtensions public static TArgument AddCompletions(this TArgument argument, System.String[] values) public static TArgument AddCompletions(this TArgument argument, System.Func> complete) public static TArgument AddCompletions(this TArgument argument, System.CommandLine.Completions.CompletionDelegate complete) public static Argument ExistingOnly(this Argument argument) public static Argument ExistingOnly(this Argument argument) public static Argument ExistingOnly(this Argument argument) public static Argument ExistingOnly(this Argument argument) public static TArgument FromAmong(this TArgument argument, System.String[] values) public static TArgument LegalFileNamesOnly(this TArgument argument) public static TArgument LegalFilePathsOnly(this TArgument argument) public static System.CommandLine.Parsing.ParseResult Parse(this Argument argument, System.String commandLine) public static System.CommandLine.Parsing.ParseResult Parse(this Argument argument, System.String[] args) public class Command : IdentifierSymbol, System.Collections.Generic.IEnumerable, System.Collections.IEnumerable, System.CommandLine.Completions.ICompletionSource .ctor(System.String name, System.String description = null) public System.Collections.Generic.IReadOnlyList Arguments { get; } public System.Collections.Generic.IEnumerable Children { get; } public System.CommandLine.Invocation.ICommandHandler Handler { get; set; } public System.Collections.Generic.IReadOnlyList Options { get; } public System.Collections.Generic.IReadOnlyList Subcommands { get; } public System.Boolean TreatUnmatchedTokensAsErrors { get; set; } public System.Void Add(Option option) public System.Void Add(Argument argument) public System.Void Add(Command command) public System.Void AddArgument(Argument argument) public System.Void AddCommand(Command command) public System.Void AddGlobalOption(Option option) public System.Void AddOption(Option option) public System.Void AddValidator(System.CommandLine.Parsing.ValidateSymbolResult validate) public System.Collections.Generic.IEnumerable GetCompletions(System.CommandLine.Completions.CompletionContext context) public System.Collections.Generic.IEnumerator GetEnumerator() public static class CommandExtensions public static System.Int32 Invoke(this Command command, System.String[] args, IConsole console = null) public static System.Int32 Invoke(this Command command, System.String commandLine, IConsole console = null) public static System.Threading.Tasks.Task InvokeAsync(this Command command, System.String[] args, IConsole console = null) public static System.Threading.Tasks.Task InvokeAsync(this Command command, System.String commandLine, IConsole console = null) public static System.CommandLine.Parsing.ParseResult Parse(this Command command, System.String[] args) public static System.CommandLine.Parsing.ParseResult Parse(this Command command, System.String commandLine) public class CommandLineConfiguration .ctor(Command command, System.Boolean enablePosixBundling = True, System.Boolean enableDirectives = True, System.Boolean enableLegacyDoubleDashBehavior = False, System.Boolean enableTokenReplacement = True, LocalizationResources resources = null, System.Collections.Generic.IReadOnlyList middlewarePipeline = null, System.Func helpBuilderFactory = null, System.CommandLine.Parsing.TryReplaceToken tokenReplacer = null) public System.Boolean EnableDirectives { get; } public System.Boolean EnableLegacyDoubleDashBehavior { get; } public System.Boolean EnablePosixBundling { get; } public System.Boolean EnableTokenReplacement { get; } public LocalizationResources LocalizationResources { get; } public Command RootCommand { get; } public System.Void ThrowIfInvalid() public class CommandLineConfigurationException : System.Exception, System.Runtime.Serialization.ISerializable .ctor(System.String message) .ctor() .ctor(System.String message, System.Exception innerException) public static class CompletionSourceExtensions public static System.Void Add(this CompletionSourceList completionSources, System.Func> complete) public static System.Void Add(this CompletionSourceList completionSources, System.CommandLine.Completions.CompletionDelegate complete) public static System.Void Add(this CompletionSourceList completionSources, System.String[] completions) public class CompletionSourceList, System.Collections.Generic.IEnumerable, System.Collections.Generic.IReadOnlyCollection, System.Collections.Generic.IReadOnlyList, System.Collections.IEnumerable .ctor() public System.Int32 Count { get; } public System.CommandLine.Completions.ICompletionSource Item { get; } public System.Void Add(System.CommandLine.Completions.ICompletionSource source) public System.Void Clear() public System.Collections.Generic.IEnumerator GetEnumerator() public static class ConsoleExtensions public static System.Void Write(this IConsole console, System.String value) public static System.Void WriteLine(this IConsole console, System.String value) public class DirectiveCollection, System.Collections.Generic.IEnumerable>>, System.Collections.IEnumerable .ctor() public System.Boolean Contains(System.String name) public System.Collections.Generic.IEnumerator>> GetEnumerator() public System.Boolean TryGetValues(System.String name, ref System.Collections.Generic.IReadOnlyList values) public static class Handler public static System.Void SetHandler(this Command command, System.Action handle) public static System.Void SetHandler(this Command command, System.Func handle) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Action handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public static System.Void SetHandler(this Command command, Func handle, System.CommandLine.Binding.IValueDescriptor[] symbols) public interface IConsole : System.CommandLine.IO.IStandardError, System.CommandLine.IO.IStandardIn, System.CommandLine.IO.IStandardOut public abstract class IdentifierSymbol : Symbol, System.CommandLine.Completions.ICompletionSource public System.Collections.Generic.IReadOnlyCollection Aliases { get; } public System.String Name { get; set; } public System.Void AddAlias(System.String alias) public System.Boolean HasAlias(System.String alias) public class LocalizationResources public static LocalizationResources Instance { get; } public System.String ArgumentConversionCannotParse(System.String value, System.Type expectedType) public System.String ArgumentConversionCannotParseForCommand(System.String value, System.String commandAlias, System.Type expectedType) public System.String ArgumentConversionCannotParseForOption(System.String value, System.String optionAlias, System.Type expectedType) public System.String DirectoryDoesNotExist(System.String path) public System.String ErrorReadingResponseFile(System.String filePath, System.IO.IOException e) public System.String ExceptionHandlerHeader() public System.String ExpectsFewerArguments(System.CommandLine.Parsing.Token token, System.Int32 providedNumberOfValues, System.Int32 maximumNumberOfValues) public System.String ExpectsOneArgument(System.CommandLine.Parsing.SymbolResult symbolResult) public System.String FileDoesNotExist(System.String filePath) public System.String FileOrDirectoryDoesNotExist(System.String path) protected System.String GetResourceString(System.String resourceString, System.Object[] formatArguments) public System.String HelpAdditionalArgumentsDescription() public System.String HelpAdditionalArgumentsTitle() public System.String HelpArgumentDefaultValueLabel() public System.String HelpArgumentsTitle() public System.String HelpCommandsTitle() public System.String HelpDescriptionTitle() public System.String HelpOptionDescription() public System.String HelpOptionsRequiredLabel() public System.String HelpOptionsTitle() public System.String HelpUsageAdditionalArguments() public System.String HelpUsageCommand() public System.String HelpUsageOptions() public System.String HelpUsageTitle() public System.String InvalidCharactersInFileName(System.Char invalidChar) public System.String InvalidCharactersInPath(System.Char invalidChar) public System.String NoArgumentProvided(System.CommandLine.Parsing.SymbolResult symbolResult) public System.String RequiredArgumentMissing(System.CommandLine.Parsing.SymbolResult symbolResult) public System.String RequiredCommandWasNotProvided() public System.String ResponseFileNotFound(System.String filePath) public System.String SuggestionsTokenNotMatched(System.String token) public System.String UnrecognizedArgument(System.String unrecognizedArg, System.Collections.Generic.IReadOnlyCollection allowedValues) public System.String UnrecognizedCommandOrArgument(System.String arg) public System.String VersionOptionCannotBeCombinedWithOtherArguments(System.String optionAlias) public System.String VersionOptionDescription() public abstract class Option : IdentifierSymbol, System.CommandLine.Binding.IValueDescriptor, System.CommandLine.Completions.ICompletionSource public System.Boolean AllowMultipleArgumentsPerToken { get; set; } public System.String ArgumentHelpName { get; set; } public ArgumentArity Arity { get; set; } public System.Boolean IsRequired { get; set; } public System.Type ValueType { get; } public System.Void AddValidator(System.CommandLine.Parsing.ValidateSymbolResult validate) public System.Collections.Generic.IEnumerable GetCompletions(System.CommandLine.Completions.CompletionContext context) public System.Boolean HasAliasIgnoringPrefix(System.String alias) public System.Void SetDefaultValue(System.Object value) public System.Void SetDefaultValueFactory(System.Func getDefaultValue) public class Option : Option, IValueDescriptor, System.CommandLine.Binding.IValueDescriptor, System.CommandLine.Completions.ICompletionSource .ctor(System.String name, System.String description = null) .ctor(System.String[] aliases, System.String description = null) .ctor(System.String name, ParseArgument parseArgument, System.Boolean isDefault = False, System.String description = null) .ctor(System.String[] aliases, ParseArgument parseArgument, System.Boolean isDefault = False, System.String description = null) .ctor(System.String name, Func getDefaultValue, System.String description = null) .ctor(System.String[] aliases, Func getDefaultValue, System.String description = null) public ArgumentArity Arity { get; set; } public static class OptionExtensions public static TOption AddCompletions(this TOption option, System.String[] values) public static TOption AddCompletions(this TOption option, System.Func> complete) public static TOption AddCompletions(this TOption option, System.CommandLine.Completions.CompletionDelegate complete) public static Option ExistingOnly(this Option option) public static Option ExistingOnly(this Option option) public static Option ExistingOnly(this Option option) public static Option ExistingOnly(this Option option) public static TOption FromAmong(this TOption option, System.String[] values) public static TOption LegalFileNamesOnly(this TOption option) public static TOption LegalFilePathsOnly(this TOption option) public static System.CommandLine.Parsing.ParseResult Parse(this Option option, System.String commandLine) public static System.CommandLine.Parsing.ParseResult Parse(this Option option, System.String[] args) public class RootCommand : Command, System.Collections.Generic.IEnumerable, System.Collections.IEnumerable, System.CommandLine.Completions.ICompletionSource public static System.String ExecutableName { get; } public static System.String ExecutablePath { get; } .ctor(System.String description = ) public abstract class Symbol, System.CommandLine.Completions.ICompletionSource public System.String Description { get; set; } public System.Boolean IsHidden { get; set; } public System.String Name { get; set; } public System.Collections.Generic.IEnumerable Parents { get; } public System.Collections.Generic.IEnumerable GetCompletions() public System.Collections.Generic.IEnumerable GetCompletions(System.CommandLine.Completions.CompletionContext context) public System.String ToString() System.CommandLine.Binding public abstract class BinderBase, IValueDescriptor, IValueDescriptor, IValueSource protected T GetBoundValue(BindingContext bindingContext) public class BindingContext, System.IServiceProvider public System.CommandLine.IConsole Console { get; } public System.CommandLine.Parsing.ParseResult ParseResult { get; } public System.Void AddService(System.Type serviceType, System.Func factory) public System.Void AddService(Func factory) public System.Object GetService(System.Type serviceType) public struct BoundValue : System.ValueType public static BoundValue DefaultForValueDescriptor(IValueDescriptor valueDescriptor) public System.Object Value { get; } public IValueDescriptor ValueDescriptor { get; } public IValueSource ValueSource { get; } public System.String ToString() public interface IValueDescriptor public System.Boolean HasDefaultValue { get; } public System.String ValueName { get; } public System.Type ValueType { get; } public System.Object GetDefaultValue() public interface IValueDescriptor : IValueDescriptor public interface IValueSource public System.Boolean TryGetValue(IValueDescriptor valueDescriptor, BindingContext bindingContext, ref System.Object& boundValue) System.CommandLine.Builder public class CommandLineBuilder .ctor(System.CommandLine.Command rootCommand = null) public System.CommandLine.Command Command { get; } public System.CommandLine.Parsing.Parser Build() public static class CommandLineBuilderExtensions public static CommandLineBuilder AddMiddleware(this CommandLineBuilder builder, System.CommandLine.Invocation.InvocationMiddleware middleware, System.CommandLine.Invocation.MiddlewareOrder order = Default) public static CommandLineBuilder AddMiddleware(this CommandLineBuilder builder, System.Action onInvoke, System.CommandLine.Invocation.MiddlewareOrder order = Default) public static CommandLineBuilder CancelOnProcessTermination(this CommandLineBuilder builder) public static CommandLineBuilder EnableDirectives(this CommandLineBuilder builder, System.Boolean value = True) public static CommandLineBuilder EnableLegacyDoubleDashBehavior(this CommandLineBuilder builder, System.Boolean value = True) public static CommandLineBuilder EnablePosixBundling(this CommandLineBuilder builder, System.Boolean value = True) public static CommandLineBuilder RegisterWithDotnetSuggest(this CommandLineBuilder builder) public static CommandLineBuilder UseDefaults(this CommandLineBuilder builder) public static CommandLineBuilder UseEnvironmentVariableDirective(this CommandLineBuilder builder) public static CommandLineBuilder UseExceptionHandler(this CommandLineBuilder builder, System.Action onException = null, System.Nullable errorExitCode = null) public static CommandLineBuilder UseHelp(this CommandLineBuilder builder, System.Nullable maxWidth = null) public static CommandLineBuilder UseHelp(this CommandLineBuilder builder, System.String[] helpAliases) public static CommandLineBuilder UseHelp(this CommandLineBuilder builder, System.Action customize, System.Nullable maxWidth = null) public static TBuilder UseHelpBuilder(this TBuilder builder, System.Func getHelpBuilder) public static CommandLineBuilder UseLocalizationResources(this CommandLineBuilder builder, System.CommandLine.LocalizationResources validationMessages) public static CommandLineBuilder UseParseDirective(this CommandLineBuilder builder, System.Nullable errorExitCode = null) public static CommandLineBuilder UseParseErrorReporting(this CommandLineBuilder builder, System.Nullable errorExitCode = null) public static CommandLineBuilder UseSuggestDirective(this CommandLineBuilder builder) public static CommandLineBuilder UseTokenReplacer(this CommandLineBuilder builder, System.CommandLine.Parsing.TryReplaceToken replaceToken) public static CommandLineBuilder UseTypoCorrections(this CommandLineBuilder builder, System.Int32 maxLevenshteinDistance = 3) public static CommandLineBuilder UseVersionOption(this CommandLineBuilder builder) public static CommandLineBuilder UseVersionOption(this CommandLineBuilder builder, System.String[] aliases) System.CommandLine.Completions public abstract class CompletionContext public System.CommandLine.Parsing.ParseResult ParseResult { get; } public System.String WordToComplete { get; } public delegate CompletionDelegate : System.MulticastDelegate, System.ICloneable, System.Runtime.Serialization.ISerializable .ctor(System.Object object, System.IntPtr method) public System.IAsyncResult BeginInvoke(CompletionContext context, System.AsyncCallback callback, System.Object object) public System.Collections.Generic.IEnumerable EndInvoke(System.IAsyncResult result) public System.Collections.Generic.IEnumerable Invoke(CompletionContext context) public class CompletionItem .ctor(System.String label, System.String kind = Value, System.String sortText = null, System.String insertText = null, System.String documentation = null, System.String detail = null) public System.String Detail { get; } public System.String Documentation { get; set; } public System.String InsertText { get; } public System.String Kind { get; } public System.String Label { get; } public System.String SortText { get; } protected System.Boolean Equals(CompletionItem other) public System.Boolean Equals(System.Object obj) public System.Int32 GetHashCode() public System.String ToString() public interface ICompletionSource public System.Collections.Generic.IEnumerable GetCompletions(CompletionContext context) public class TextCompletionContext : CompletionContext public System.String CommandLineText { get; } public System.Int32 CursorPosition { get; } public TextCompletionContext AtCursorPosition(System.Int32 position) public class TokenCompletionContext : CompletionContext System.CommandLine.Help public class HelpBuilder .ctor(System.CommandLine.LocalizationResources localizationResources, System.Int32 maxWidth = 2147483647) public System.CommandLine.LocalizationResources LocalizationResources { get; } public System.Int32 MaxWidth { get; } public System.Void CustomizeLayout(System.Func> getLayout) public System.Void CustomizeSymbol(System.CommandLine.Symbol symbol, System.Func firstColumnText = null, System.Func secondColumnText = null, System.Func defaultValue = null) public TwoColumnHelpRow GetTwoColumnRow(System.CommandLine.Symbol symbol, HelpContext context) public System.Void Write(HelpContext context) public System.Void WriteColumns(System.Collections.Generic.IReadOnlyList items, HelpContext context) static class Default public static HelpSectionDelegate AdditionalArgumentsSection() public static HelpSectionDelegate CommandArgumentsSection() public static HelpSectionDelegate CommandUsageSection() public static System.String GetArgumentDefaultValue(System.CommandLine.Argument argument) public static System.String GetArgumentDescription(System.CommandLine.Argument argument) public static System.String GetArgumentUsageLabel(System.CommandLine.Argument argument) public static System.String GetIdentifierSymbolDescription(System.CommandLine.IdentifierSymbol symbol) public static System.String GetIdentifierSymbolUsageLabel(System.CommandLine.IdentifierSymbol symbol, HelpContext context) public static System.Collections.Generic.IEnumerable GetLayout() public static HelpSectionDelegate OptionsSection() public static HelpSectionDelegate SubcommandsSection() public static HelpSectionDelegate SynopsisSection() public static class HelpBuilderExtensions public static System.Void CustomizeSymbol(this HelpBuilder builder, System.CommandLine.Symbol symbol, System.String firstColumnText = null, System.String secondColumnText = null, System.String defaultValue = null) public static System.Void Write(this HelpBuilder helpBuilder, System.CommandLine.Command command, System.IO.TextWriter writer) public class HelpContext .ctor(HelpBuilder helpBuilder, System.CommandLine.Command command, System.IO.TextWriter output, System.CommandLine.Parsing.ParseResult parseResult = null) public System.CommandLine.Command Command { get; } public HelpBuilder HelpBuilder { get; } public System.IO.TextWriter Output { get; } public System.CommandLine.Parsing.ParseResult ParseResult { get; } public delegate HelpSectionDelegate : System.MulticastDelegate, System.ICloneable, System.Runtime.Serialization.ISerializable .ctor(System.Object object, System.IntPtr method) public System.IAsyncResult BeginInvoke(HelpContext context, System.AsyncCallback callback, System.Object object) public System.Void EndInvoke(System.IAsyncResult result) public System.Void Invoke(HelpContext context) public class TwoColumnHelpRow, System.IEquatable .ctor(System.String firstColumnText, System.String secondColumnText) public System.String FirstColumnText { get; } public System.String SecondColumnText { get; } public System.Boolean Equals(System.Object obj) public System.Boolean Equals(TwoColumnHelpRow other) public System.Int32 GetHashCode() System.CommandLine.Invocation public interface ICommandHandler public System.Int32 Invoke(InvocationContext context) public System.Threading.Tasks.Task InvokeAsync(InvocationContext context) public interface IInvocationResult public System.Void Apply(InvocationContext context) public class InvocationContext .ctor(System.CommandLine.Parsing.ParseResult parseResult, System.CommandLine.IConsole console = null) public System.CommandLine.Binding.BindingContext BindingContext { get; } public System.CommandLine.IConsole Console { get; set; } public System.Int32 ExitCode { get; set; } public System.CommandLine.Help.HelpBuilder HelpBuilder { get; } public IInvocationResult InvocationResult { get; set; } public System.CommandLine.LocalizationResources LocalizationResources { get; } public System.CommandLine.Parsing.Parser Parser { get; } public System.CommandLine.Parsing.ParseResult ParseResult { get; set; } public System.Threading.CancellationToken GetCancellationToken() public delegate InvocationMiddleware : System.MulticastDelegate, System.ICloneable, System.Runtime.Serialization.ISerializable .ctor(System.Object object, System.IntPtr method) public System.IAsyncResult BeginInvoke(InvocationContext context, System.Func next, System.AsyncCallback callback, System.Object object) public System.Threading.Tasks.Task EndInvoke(System.IAsyncResult result) public System.Threading.Tasks.Task Invoke(InvocationContext context, System.Func next) public enum MiddlewareOrder : System.Enum, System.IComparable, System.IConvertible, System.IFormattable Default=0 ErrorReporting=1000 ExceptionHandler=-2000 Configuration=-1000 System.CommandLine.IO public interface IStandardError public IStandardStreamWriter Error { get; } public System.Boolean IsErrorRedirected { get; } public interface IStandardIn public System.Boolean IsInputRedirected { get; } public interface IStandardOut public System.Boolean IsOutputRedirected { get; } public IStandardStreamWriter Out { get; } public interface IStandardStreamWriter public System.Void Write(System.String value) public static class StandardStreamWriter public static IStandardStreamWriter Create(System.IO.TextWriter writer) public static System.IO.TextWriter CreateTextWriter(this IStandardStreamWriter writer) public static System.Void WriteLine(this IStandardStreamWriter writer) public static System.Void WriteLine(this IStandardStreamWriter writer, System.String value) public class SystemConsole, System.CommandLine.IConsole, IStandardError, IStandardIn, IStandardOut .ctor() public IStandardStreamWriter Error { get; } public System.Boolean IsErrorRedirected { get; } public System.Boolean IsInputRedirected { get; } public System.Boolean IsOutputRedirected { get; } public IStandardStreamWriter Out { get; } public class TestConsole, System.CommandLine.IConsole, IStandardError, IStandardIn, IStandardOut .ctor() public IStandardStreamWriter Error { get; } public System.Boolean IsErrorRedirected { get; } public System.Boolean IsInputRedirected { get; } public System.Boolean IsOutputRedirected { get; } public IStandardStreamWriter Out { get; } protected System.Void set_Error(IStandardStreamWriter value) protected System.Void set_IsErrorRedirected(System.Boolean value) protected System.Void set_IsInputRedirected(System.Boolean value) protected System.Void set_IsOutputRedirected(System.Boolean value) protected System.Void set_Out(IStandardStreamWriter value) System.CommandLine.Parsing public class ArgumentResult : SymbolResult public System.CommandLine.Argument Argument { get; } public System.Object GetValueOrDefault() public T GetValueOrDefault() public System.Void OnlyTake(System.Int32 numberOfTokens) public System.String ToString() public class CommandLineStringSplitter public System.Collections.Generic.IEnumerable Split(System.String commandLine) public class CommandResult : SymbolResult public System.CommandLine.Command Command { get; } public Token Token { get; } public class OptionResult : SymbolResult public System.Boolean IsImplicit { get; } public System.CommandLine.Option Option { get; } public Token Token { get; } public System.Object GetValueOrDefault() public T GetValueOrDefault() public delegate ParseArgument : System.MulticastDelegate, System.ICloneable, System.Runtime.Serialization.ISerializable .ctor(System.Object object, System.IntPtr method) public System.IAsyncResult BeginInvoke(ArgumentResult result, System.AsyncCallback callback, System.Object object) public T EndInvoke(System.IAsyncResult result) public T Invoke(ArgumentResult result) public class ParseError public System.String Message { get; } public SymbolResult SymbolResult { get; } public System.String ToString() public class Parser .ctor(System.CommandLine.CommandLineConfiguration configuration) .ctor(System.CommandLine.Command command) .ctor() public System.CommandLine.CommandLineConfiguration Configuration { get; } public ParseResult Parse(System.Collections.Generic.IReadOnlyList arguments, System.String rawInput = null) public class ParseResult public CommandResult CommandResult { get; } public System.CommandLine.DirectiveCollection Directives { get; } public System.Collections.Generic.IReadOnlyList Errors { get; } public Parser Parser { get; } public CommandResult RootCommandResult { get; } public System.Collections.Generic.IReadOnlyList Tokens { get; } public System.Collections.Generic.IReadOnlyList UnmatchedTokens { get; } public System.Collections.Generic.IReadOnlyList UnparsedTokens { get; } public ArgumentResult FindResultFor(System.CommandLine.Argument argument) public CommandResult FindResultFor(System.CommandLine.Command command) public OptionResult FindResultFor(System.CommandLine.Option option) public SymbolResult FindResultFor(System.CommandLine.Symbol symbol) public System.CommandLine.Completions.CompletionContext GetCompletionContext() public System.Collections.Generic.IEnumerable GetCompletions(System.Nullable position = null) public System.Object GetValueForArgument(System.CommandLine.Argument argument) public T GetValueForArgument(Argument argument) public System.Object GetValueForOption(System.CommandLine.Option option) public T GetValueForOption(Option option) public System.String ToString() public static class ParseResultExtensions public static System.String Diagram(this ParseResult parseResult) public static System.Boolean HasOption(this ParseResult parseResult, System.CommandLine.Option option) public static System.Int32 Invoke(this ParseResult parseResult, System.CommandLine.IConsole console = null) public static System.Threading.Tasks.Task InvokeAsync(this ParseResult parseResult, System.CommandLine.IConsole console = null) public static class ParserExtensions public static System.Int32 Invoke(this Parser parser, System.String commandLine, System.CommandLine.IConsole console = null) public static System.Int32 Invoke(this Parser parser, System.String[] args, System.CommandLine.IConsole console = null) public static System.Threading.Tasks.Task InvokeAsync(this Parser parser, System.String commandLine, System.CommandLine.IConsole console = null) public static System.Threading.Tasks.Task InvokeAsync(this Parser parser, System.String[] args, System.CommandLine.IConsole console = null) public static ParseResult Parse(this Parser parser, System.String commandLine) public abstract class SymbolResult public System.Collections.Generic.IReadOnlyList Children { get; } public System.String ErrorMessage { get; set; } public System.CommandLine.LocalizationResources LocalizationResources { get; set; } public SymbolResult Parent { get; } public System.CommandLine.Symbol Symbol { get; } public System.Collections.Generic.IReadOnlyList Tokens { get; } public ArgumentResult FindResultFor(System.CommandLine.Argument argument) public CommandResult FindResultFor(System.CommandLine.Command command) public OptionResult FindResultFor(System.CommandLine.Option option) public T GetValueForArgument(Argument argument) public System.Object GetValueForArgument(System.CommandLine.Argument argument) public T GetValueForOption(Option option) public System.Object GetValueForOption(System.CommandLine.Option option) public System.String ToString() public class Token, System.IEquatable public static System.Boolean op_Equality(Token left, Token right) public static System.Boolean op_Inequality(Token left, Token right) .ctor(System.String value, TokenType type, System.CommandLine.Symbol symbol) public TokenType Type { get; } public System.String Value { get; } public System.Boolean Equals(System.Object obj) public System.Boolean Equals(Token other) public System.Int32 GetHashCode() public System.String ToString() public enum TokenType : System.Enum, System.IComparable, System.IConvertible, System.IFormattable Argument=0 Command=1 Option=2 DoubleDash=3 Unparsed=4 Directive=5 public delegate TryReplaceToken : System.MulticastDelegate, System.ICloneable, System.Runtime.Serialization.ISerializable .ctor(System.Object object, System.IntPtr method) public System.IAsyncResult BeginInvoke(System.String tokenToReplace, ref System.Collections.Generic.IReadOnlyList replacementTokens, ref System.String& errorMessage, System.AsyncCallback callback, System.Object object) public System.Boolean EndInvoke(ref System.Collections.Generic.IReadOnlyList replacementTokens, ref System.String& errorMessage, System.IAsyncResult result) public System.Boolean Invoke(System.String tokenToReplace, ref System.Collections.Generic.IReadOnlyList replacementTokens, ref System.String& errorMessage) public delegate ValidateSymbolResult : System.MulticastDelegate, System.ICloneable, System.Runtime.Serialization.ISerializable .ctor(System.Object object, System.IntPtr method) public System.IAsyncResult BeginInvoke(T symbolResult, System.AsyncCallback callback, System.Object object) public System.Void EndInvoke(System.IAsyncResult result) public System.Void Invoke(T symbolResult) ``` ## Samples ### Simple sample This is a CLI with a single root command and a single option which has an argument: ```csharp using System.CommandLine; internal class Program { private static async Task Main(string[] args) { var fileOption = new Option( name: "--file", description: "The file to read and display on the console."); var rootCommand = new RootCommand("Sample app for System.CommandLine"); rootCommand.AddOption(fileOption); rootCommand.SetHandler( (FileInfo file) => ReadFile(file), fileOption); return await rootCommand.InvokeAsync(args); } private static void ReadFile(FileInfo file) => File.ReadLines(file.FullName).ToList() .ForEach(line => Console.WriteLine(line)); } ``` ### Complex sample This sample has multiple commands with numerous options. The first option does custom validation: ```csharp using System.CommandLine; namespace scl; class Program { static async Task Main(string[] args) { var fileOption = new Option( name: "--file", description: "An option whose argument is parsed as a FileInfo", isDefault: true, parseArgument: result => { if (result.Tokens.Count == 0) { return new FileInfo("sampleQuotes.txt"); } var filePath = result.Tokens.Single().Value; if (!File.Exists(filePath)) { result.ErrorMessage = "File does not exist"; return null; } else { return new FileInfo(filePath); } }); var delayOption = new Option( name: "--delay", description: "Delay between lines, specified as milliseconds per character in a line.", getDefaultValue: () => 42); var fgcolorOption = new Option( name: "--fgcolor", description: "Foreground color of text displayed on the console.", getDefaultValue: () => ConsoleColor.White); var lightModeOption = new Option( name: "--light-mode", description: "Background color of text displayed on the console: default is black, light mode is white."); var searchTermsOption = new Option( name: "--search-terms", description: "Strings to search for when deleting entries.") { IsRequired = true, AllowMultipleArgumentsPerToken = true }; var quoteArgument = new Argument( name: "quote", description: "Text of quote."); var bylineArgument = new Argument( name: "byline", description: "Byline of quote."); var rootCommand = new RootCommand("Sample app for System.CommandLine"); rootCommand.AddGlobalOption(fileOption); var quotesCommand = new Command("quotes", "Work with a file that contains quotes."); rootCommand.AddCommand(quotesCommand); var readCommand = new Command("read", "Read and display the file.") { delayOption, fgcolorOption, lightModeOption }; quotesCommand.AddCommand(readCommand); var deleteCommand = new Command("delete", "Delete lines from the file."); deleteCommand.AddOption(searchTermsOption); quotesCommand.AddCommand(deleteCommand); var addCommand = new Command("add", "Add an entry to the file."); addCommand.AddArgument(quoteArgument); addCommand.AddArgument(bylineArgument); addCommand.AddAlias("insert"); quotesCommand.AddCommand(addCommand); readCommand.SetHandler(async (FileInfo file, int delay, ConsoleColor fgcolor, bool lightMode) => { await ReadFile(file, delay, fgcolor, lightMode); }, fileOption, delayOption, fgcolorOption, lightModeOption); deleteCommand.SetHandler( (FileInfo file, string[] searchTerms) => { DeleteFromFile(file, searchTerms); }, fileOption, searchTermsOption); addCommand.SetHandler( (FileInfo file, string quote, string byline) => { AddToFile(file, quote, byline); }, fileOption, quoteArgument, bylineArgument); return await rootCommand.InvokeAsync(args); } internal static async Task ReadFile( FileInfo file, int delay, ConsoleColor fgColor, bool lightMode) { Console.BackgroundColor = lightMode ? ConsoleColor.White : ConsoleColor.Black; Console.ForegroundColor = fgColor; var lines = File.ReadLines(file.FullName).ToList(); foreach (string line in lines) { Console.WriteLine(line); await Task.Delay(delay * line.Length); }; } internal static void DeleteFromFile(FileInfo file, string[] searchTerms) { Console.WriteLine("Deleting from file"); File.WriteAllLines( file.FullName, File.ReadLines(file.FullName) .Where(line => searchTerms.All(s => !line.Contains(s))).ToList()); } internal static void AddToFile(FileInfo file, string quote, string byline) { Console.WriteLine("Adding to file"); using var writer = file.AppendText(); writer.WriteLine($"{Environment.NewLine}{Environment.NewLine}{quote}"); writer.WriteLine($"{Environment.NewLine}-{byline}"); writer.Flush(); } } ```

Author:	KathleenDollard
Assignees:	-
Labels:	`area-System.Runtime`, `blocking`, `untriaged`, `api-ready-for-review`
Milestone:	-

[tannergooding]

This likely deserves an initial glance over (pre-API review) from @dotnet/area-system-console.

@jeffhandley, @ericstj. This likely deserves its own area as well given that its fairly expansive, in its own repo, and has been driven externally to the libraries team up until this point.

@KathleenDollard is the expectation that the SDK/CLI team is the primary owners of this moving forward?

[tannergooding]

@terrajobst, this one is marked blocking but likely needs its own API review slot as I expect it will take the full 2 hours due to size.

[terrajobst]

I know. I asked them to file this issue. It's already scheduled for tomorrow.

[davidfowl]

There is no reason for a simple apps like this one to be async. It just adds unnecessary overhead.

Are you saying we don't need async overloads or that the sample doesn't need to be async? Commands absolutely need to support asynchrony. I have a bunch of command line tools that make http requests in individual commands.

[jkotas]

I am saying that the simple sample does not need to be async.

I do not have a problem with async commands. We have introduced async Main shortcut some years ago and so it makes sense to have async Command shortcut in this library too, for similar reasons.

[davidfowl]

Just checking 😄

[ghost]

Tagging subscribers to this area: @dotnet/area-system-console See info in area-owners.md if you want to be subscribed.

Issue Details

---

## Background and motivation System.CommandLine is finalizing GA and is thus looking for a final design review prior to V1. There have been significant changes since the previous design review 2 years ago, driven by API review feedback, user feedback, and especially improvements in performance and to enable trimming. Since the surface area is large, we suggest focusing on these questions: ### Namespace reorganization Following the previous API review we segmented the namespaces to specific areas in order to surface the most important types in the root `System.CommandLine` namespace. This resulted in needing a significant number of using statements, as pointed out in the issue [System.CommandLine is split into too many namespaces](https://github.com/dotnet/command-line-api/issues/1680). We'd like to discuss how we balance between too many and too few namespaces. ### Ergonomics Previous feedback included that the coding UX was rather complicated. We have done some simplification, and we have [docs](https://docs.microsoft.com/dotnet/standard/commandline/), but we believe fundamental simplification will require an opinionated layer, probably with source generation for Rolsyn. A community member created a very nice layer for [F# based on computation expressions](https://github.com/JordanMarr/FSharp.SystemCommandLine). Our choice is to keep System.CommandLine as it is and allow these layers to simplify the less complicated use cases. Usability of System.CommandLine has been shown in both static mode (.NET CLI) and dynmaic mode (`dotnet new`). We also have experience with significantly different models with the very popular Dragonfruit, and prototyping subcommands. One of the reasons we want to build a foundation for an opinionated layer is that this is where the community can explore options, including wrappers for current styles used in other parsers. We wanted to check in on thinking around tooling related to API's now that we have source generation as an approach. ### SetHandler One of the things we do to simplify using the API is SetHandler which connects a command with a function/lambda and passes the results for arguments and options. This is effective, and we think is the best approach prior to opinionated layers. However, there are two areas of issues: * Because the delegates are generic and there may be any number of arguments and thus many overloads differing on generic arity, we have 16 overloads of each of the 2 patterns - void returning and task returning. We also document special handling where 16 arguments and options are not enough. * As seen in the [Simple sample](#simple-sample), there is redundancy to pass the option to the SetHandler method. The main mechanism was previously name based, and it was the major source of user issues. We have moved name-based matching into a separate package so it is available for backwards compatibility. Prototyping has confirmed that opinionated layers do not need SetHandler, so we think these issues are ugly, but that this will be an important secondary mechanism for complex CLI's and we do not see a way to avoid it. ### IConsole For testing and other issues we needed an abstraction for Console. We created an interface named IConsole. We strongly hope that .NET will have a future abstraction in lieu of or working with System.Console and hope to avoid a naming collision. At the last API review, our feedback was that an abstraction was very, very unlikely to be an interface, and we wanted to check that was still the case. ### TestConsole We have a buffered console that is used in our testing and we think anyone testing their console output will find valuable. The name indicates more how it is expected to be used than what it is. We think it should be public to help folks, and we think this name is fine since the purpose is the most important thing. ## API Proposal This output is from our unit test for ensuring PRs do not change the API surface area unexpectedly, and thus is in a slightly non-standard format: ```csharp namespace System.CommandLine { public abstract class Argument : Symbol, IValueDescriptor, ICompletionSource { public ArgumentArity Arity { get; set; } public CompletionSourceList Completions { get; } public bool HasDefaultValue { get; } public string HelpName { get; set; } public Type ValueType { get; } public void AddValidator(ValidateSymbolResult validate); public IEnumerable GetCompletions(CompletionContext context); public object GetDefaultValue(); public void SetDefaultValue(object value); public void SetDefaultValueFactory(Func

[GrabYourPitchforks]

I've removed blocking from this for the time being so that it doesn't keep showing up in API review. Please re-add the tag when it's time to bring it back. Thanks! :)

[deeprobin]

Can we add ReadOnlySpan-APIs (or ReadOnlySequence?)

    public static class CommandExtensions 
    {
        public static int Invoke(this Command command, ReadOnlySpan<string> args, IConsole console = null);
        public static int Invoke(this Command command, ReadOnlySpan<char> commandLine, IConsole console = null);
        public static Task<int> InvokeAsync(this Command command, ReadOnlySpan<string> args, IConsole console = null);
        public static Task<int> InvokeAsync(this Command command, ReadOnlySpan<char> commandLine, IConsole console = null);
        public static ParseResult Parse(this Command command, ReadOnlySpan<string> args);
        public static ParseResult Parse(this Command command, ReadOnlySpan<char> commandLine);
    }

[deeprobin]

& Why is Token not a (readonly) struct?

[KalleOlaviNiemitalo]

Why is Token not a (readonly) struct?

To minimise JIT compilation time during startup, according to https://github.com/dotnet/command-line-api/pull/1654.

[jkotas]

Can we add ReadOnlySpan-APIs (or ReadOnlySequence?)

It would be de-optimization. Command line parsing should be optimized for minimal code size and startup time. Span APIs like this do not help with that.

[EgorBo]

Today I tried to use System.CommandLine for the first time for my quick build script in C# and it was not exactly a pleasant experience I hoped it to be, honestly, it looks extremely verbose to me 😢

var pythonOpt = new Option<string>(
    name: "-python",
    description: "path to python",
    getDefaultValue: () => "python");

var spmiPathOpt = new Option<string>(
    name: "-superpmi_path",
    description: "path to superpmi.py");

var mchPathOpt = new Option<string>(
    name: "-output_mch_path",
    description: "output mch path");

var logFileOpt = new Option<string>(
    name: "-log_file",
    description: "path to log file");

var workDirOpt = new Option<string>(
    name: "-benchmarks_path",
    description: "path to aspnet benchmarks");

var corerunPathOpt = new Option<string>(
    name: "-corerun_path",
    description: "path to test corerun");

var dotnetCliPathOpt = new Option<string>(
    name: "-dotnetcli_path",
    description: "path to dotnet cli to build benchmarks",
    getDefaultValue: () => "dotnet");

var tfmOpt = new Option<string>(
    name: "-tfm",
    description: "target framework",
    getDefaultValue: () => "net7.0");

var ridOpt = new Option<string>(
    name: "-rid",
    description: "path to python",
    getDefaultValue: () => "win-x64");

var rootCommand = new RootCommand("TechEmpowerSpmiCollection");
rootCommand.Add(pythonOpt);
rootCommand.Add(spmiPathOpt);
rootCommand.Add(mchPathOpt);
rootCommand.Add(logFileOpt);
rootCommand.Add(workDirOpt);
rootCommand.Add(corerunPathOpt);
rootCommand.Add(dotnetCliPathOpt);
rootCommand.Add(tfmOpt);
rootCommand.Add(ridOpt);

// This doesn't compile -- only up to 9 arguments
/*rootCommand.SetHandler((python, superpmi_path, output_mch_path, log_file, benchmarks_path, corerun_path, dotnetcli_path, tfm_path, rid_opt) =>
{
    //
    // Do work
    //
}, pythonOpt, spmiPathOpt, mchPathOpt, logFileOpt, workDirOpt, corerunPathOpt, dotnetCliPathOpt, tfmOpt, ridOpt);
*/

rooCmd.SetHandler(ctx =>
{
    string python = ctx.ParseResult.GetValueForOption(pythonOpt);
    string spmiPath = ctx.ParseResult.GetValueForOption(pythonOpt);
    string mchPath = ctx.ParseResult.GetValueForOption(pythonOpt);
    string rid = ctx.ParseResult.GetValueForOption(pythonOpt);
    string tfm = ctx.ParseResult.GetValueForOption(pythonOpt);
    string dotnetCliPath = ctx.ParseResult.GetValueForOption(pythonOpt);
    string benchmarksPath = ctx.ParseResult.GetValueForOption(benchmarksPathOpt);
    string coreRunPath = ctx.ParseResult.GetValueForOption(corerunPathOpt);

    // do work
});

return rootCommand.Invoke(args);

and it didn't even compile for me because SetHandler only supports up to 9 arguments. I understand the intention to build CommandLine over complicated scenarios first because it's used in our tooling (e.g. dotnet/diagnostics), but it's very difficult to sell this feature for quick build scripts over e.g. https://github.com/commandlineparser/commandline where the same logic for my case would look way less verbose 🙁

[En3Tho]

This is the same example done with https://github.com/Cysharp/ConsoleAppFramework with AspNetCore minimal api style. Note that it also supports Controller-like command binding

static void Egor(
    [Option(null, "path to superpmi.py")] string superpmi_path,
    [Option(null, "output mch path")] string output_mch_path,
    [Option(null, "path to log file")] string log_file,
    [Option(null, "path to aspnet benchmarks")] string benchmarks_path,
    [Option(null, "path to test corerun")] string corerun_path,
    [Option(null, "path to python")] string python = "python",
    [Option(null, "path to dotnet cli to build benchmarks")] string dotnetcli_path = "dotnet",
    [Option(null, "target framework")] string tfm = "net7.0",
    [Option(null, "runtime identifier")] string rid = "win-x64")
{
    // Do work
};

var app = ConsoleApp.Create(args);
app.AddCommand("egor", Egor);
app.Run();

[jkoritzinsky]

@EgorBo did you try out the System.CommandLine.DragonFruit library? That might give you more what you want.

Also, for an API improvement here: I know it would be untyped and would have to be resolved with reflection, but now that lambdas have implicit conversions to System.Delegate, there could be an overload of AddHandler(System.Delegate, params IValueDescriptor[]) that would resolve the parameter <-> option mapping at runtime. This overload would allow any number of parameters, though would be slightly less safe at compile time. Since this would only be used for cases where there are more than 9 options, I think that's not the worst situation.

[jkotas]

My experience with trying to use the current System.CommandLine was very similar to Egor's.

an API improvement here:

Pure API approach cannot compete with usability of DSLs implemented by the other command line parsing packages mentioned in previous replies. The problem with the proposed API is that it is trying to be both lean and usable, and failing on both. I think that it would be best to make the usability of the direct API use a non-goal, and redesign the API to be a target for the source generator that delivers the desired lean command line parser with good usability.

[jonsequitur]

Also, for an API improvement here: I know it would be untyped and would have to be resolved with reflection, but now that lambdas have implicit conversions to System.Delegate, there could be an overload of AddHandler(System.Delegate, params IValueDescriptor[]) that would resolve the parameter <-> option mapping at runtime. This overload would allow any number of parameters, though would be slightly less safe at compile time. Since this would only be used for cases where there are more than 9 options, I think that's not the worst situation.

@jkoritzinsky, this would reintroduce the need for runtime reflection which was removed for performance and trimmability. But as @jkotas suggested, a layer on top of the core API using source generators could resolve this, and we're indeed working on that.

Currently, the simplest way to go beyond 8 parameters (and arguably a more consistent approach generally) is what @EgorBo used above:

rooCmd.SetHandler(ctx =>
{
    string python = ctx.ParseResult.GetValueForOption(pythonOpt);
    string spmiPath = ctx.ParseResult.GetValueForOption(pythonOpt);
    string mchPath = ctx.ParseResult.GetValueForOption(pythonOpt);
    string rid = ctx.ParseResult.GetValueForOption(pythonOpt);
    string tfm = ctx.ParseResult.GetValueForOption(pythonOpt);
    string dotnetCliPath = ctx.ParseResult.GetValueForOption(pythonOpt);
    string benchmarksPath = ctx.ParseResult.GetValueForOption(benchmarksPathOpt);
    string coreRunPath = ctx.ParseResult.GetValueForOption(corerunPathOpt);

    // do work
});

A less verbose version of this (proposed by @KathleenDollard in a discussion here) might look something like this:

rooCmd.SetHandler(ctx =>
{
    string python = ctx.GetValue(pythonOpt);
    string spmiPath = ctx.GetValue(pythonOpt);
    string mchPath = ctx.GetValue(pythonOpt);
    string rid = ctx.GetValue(pythonOpt);
    string tfm = ctx.GetValue(pythonOpt);
    string dotnetCliPath = ctx.GetValue(pythonOpt);
    string benchmarksPath = ctx.GetValue(benchmarksPathOpt);
    string coreRunPath = ctx.GetValue(corerunPathOpt);

    // do work
});

[davidfowl]

It’s great we removed the reflection but the API is painful to use. Do we have an issue with what the source generator experience will look like?

[KalleOlaviNiemitalo]

The specific issue for InvocationContext.GetValue is https://github.com/dotnet/command-line-api/issues/1785

[KathleenDollard]

@davidfowl @jkotas @tannergooding

I put my initial thoughts here: https://github.com/dotnet/command-line-api/issues/1829

[wiktor-golonka]

Can we have API methods that allow getting a result for argument/option without having to pass the exact instance, but only a name?

For example like these:

        public object GetValueForArgument(string argumentName);
        public T GetValueForArgument<T>(string argumentName);
        public object GetValueForOption(string optionName);
        public T GetValueForOption<T>(string optionName);

This would be especially useful if you have a handler that implements the ICommandHandler interface from System.CommandLine.Invocation and you register it with UseCommandHandler from System.CommandLine.Hosting

https://github.com/dotnet/command-line-api/blob/1d98a75ce2b109a2d7c18d81fac3f279be095e4e/src/System.CommandLine/ICommandHandler.cs#L7-28

https://github.com/dotnet/command-line-api/blob/1d98a75ce2b109a2d7c18d81fac3f279be095e4e/src/System.CommandLine.Hosting/HostingExtensions.cs#L86

public sealed class SampleCommandHandler : ICommandHandler
{
    public int Invoke(InvocationContext context)
    {
        throw new NotImplementedException();
    }

    public async Task<int> InvokeAsync(InvocationContext context)
    {
        var optionValue = context.ParseResult.GetValueForOption("--option1");

        return 0;
    }
}

[jonsequitur]

@wiktor-golonka The API allowed this in earlier previews. The problem was that it's much slower (because options can be looked up by several potential aliases and the lookup needs to traverse the command tree in case the option was declared on a parent command, e.g. accounting for myapp --option verb, myapp -o verb, myapp verb --option, etc.)

Another concern with the name-based lookup was that it's potentially ambiguous. It's possible to have different options or commands that have the same name. The object-based lookup allows these to be unambiguous whereas a name-based lookup would require the user to disambiguate them.

[richlander]

Is Program.Main or top-level statements the primary target for these APIs? It seems like the former. ASP.NET Core seems to be focused primarily on the latter. It would be great to see a "minimal APIs" approach for command-line, which would align our efforts and offerings. Both domains are a kind of routing on text input and controller problem space. Yes?

[En3Tho]

I'd like to note that minimal apis work good no matter what approach (main/top level) is chosen. @richlander please check out ConsoleAppFramework: https://github.com/Cysharp/ConsoleAppFramework. I've provided an example above (https://github.com/dotnet/runtime/issues/68578#issuecomment-1224321092).

I guess the problem with this approach is that it's quite reflection heavy I guess.

[adamsitnik]

Following proposal is not ready yet, it needs an edit and approval from @KathleenDollard and @jonsequitur.

Background and motivation

System.CommandLine has a very ambitious goal. We want to provide a set of simple, intuitive, and performant APIs for parsing of command line arguments, but at the same time we want them to be flexible enough to meet the requirements of users who build complex CLIs like “dotnet”. We basically want to avoid situations where people develop their own parsers because S.CL is missing something important.

The APIs that we want to include in BCL can be grouped into following categories:

• Building a hierarchy of symbols
• Completions
• Parsing the hierarchy for given input
• Execution of the parsed result (an optional step, not included in this proposal)

We expect these APIs to be building blocks for:

• Advanced users who build fully featured CLIs.
• Our incoming source-generator based solution (not included in this proposal), which aims for simplicity and not needing the users to become familiar with most of the concepts related to parsing.

// An example of how incoming source-generator based solution might look like
class Program
{
    static int Main(string target, int count = 4)
    {
        // arguments are already parsed!
    }
}

// The alternative
static int Main(string[] args)
{
    Command pingCommand = new ("ping")
    {
        new Argument<string>("target");
        new Option<int?>("--count")
    };

    ParseResult parseResult = pingCommand.Parse(args);

    string target = parseResult.GetValue<string>("target")
    int count = parseResult.GetValue<int?>("--count") ?? 4;
}

API Proposal

```cs namespace System.CommandLine { ///

/// Defines a named symbol that resides in a hierarchy with parent and child symbols. ///

public abstract class CliSymbol { public string Name { get; } public string? Description { get; set; } ///

/// Gets or sets a value indicating whether the symbol is hidden. /// Example: it can be parsed, but not being printed in help. ///

public bool IsHidden { get; set; } public IEnumerable Parents { get; } public abstract IEnumerable GetCompletions(CompletionContext context); } ///

/// Defines the arity of an option or argument. ///

/// The arity refers to the number of values that can be passed on the command line. /// public readonly struct ArgumentArity : IEquatable { public ArgumentArity(int minimumNumberOfValues, int maximumNumberOfValues); public int MinimumNumberOfValues { get; } public int MaximumNumberOfValues { get; } public static ArgumentArity Zero => new(0, 0); public static ArgumentArity ZeroOrOne => new(0, 1); public static ArgumentArity ExactlyOne => new(1, 1); public static ArgumentArity ZeroOrMore => new(0, MaximumArity); public static ArgumentArity OneOrMore => new(1, MaximumArity); } ///

/// A symbol defining a value that can be passed on the command line to a command or option. ///

public abstract class CliArgument : CliSymbol { public ArgumentArity Arity { get; } ///

/// The name used in help output to describe the argument. /// It can be localized, it's not used for parsing. ///

public string? HelpName { get; set; } ///

/// Gets the list of completion sources for the argument. ///

public List>> CompletionSources { get; } ///

/// Gets the that the argument token(s) will be converted to. ///

public abstract Type ValueType { get; } ///

/// Provides a list of argument validators. Validators can be used /// to provide custom errors based on user input. ///

public List> Validators { get; } ///

/// Gets the default value for the argument. ///

public object? GetDefaultValue(); ///

/// Specifies if a default value is defined for the argument. ///

public abstract bool HasDefaultValue { get; } } public class CliArgument : CliArgument { /// The name of the argument. It's not used for parsing, only when displaying Help or creating parse errors.> public CliArgument(string name); ///

/// The delegate to invoke to create the default value. ///

/// /// It's invoked when there was no parse input provided for given Argument. /// The same instance can be set as , in such case /// the delegate is also invoked when an input was provided. /// public Func? DefaultValueFactory { get; set; } ///

/// A custom argument parser. ///

/// /// It's invoked when there was parse input provided for given Argument. /// The same instance can be set as , in such case /// the delegate is also invoked when no input was provided. /// public Func? CustomParser { get; set; } ///

/// Configures the argument to accept only the specified values, and to suggest them as command line completions. ///

/// The values that are allowed for the argument. public void AcceptOnlyFromAmong(params string[] values); ///

/// Configures the argument to accept only values representing legal file paths. ///

public void AcceptLegalFilePathsOnly(); ///

/// Configures the argument to accept only values representing legal file names. ///

/// A parse error will result, for example, if file path separators are found in the parsed value. public void AcceptLegalFileNamesOnly(); } ///

/// A symbol defining a named parameter and a value for that parameter. ///

public abstract class CliOption : CliSymbol { public string? HelpName { get; set; } public ArgumentArity Arity { get; set; } ///

/// When set to true, this option will be applied to the command and recursively to subcommands. /// It will not apply to parent commands. ///

public bool AppliesToSelfAndChildren { get; set; } public List> Validators { get; } public List>> CompletionSources { get; } ///

/// Gets a value that indicates whether multiple argument tokens are allowed for each option identifier token. ///

/// /// If set to , the following command line is valid for passing multiple arguments: /// /// > --opt 1 2 3 /// /// The following is equivalent and is always valid: /// /// > --opt 1 --opt 2 --opt 3 /// /// public bool AllowMultipleArgumentsPerToken { get; set; } ///

/// Indicates whether the option is required when its parent command is invoked. ///

/// When an option is required and its parent command is invoked without it, an error results. public bool IsRequired { get; set; } ///

/// Gets the unique set of strings that can be used on the command line to specify the Option. ///

/// The collection does not contain the of the Option. public ICollection Aliases { get; } } public class CliOption : CliOption { /// The name of the option. It's used for parsing, displaying Help and creating parse errors.> /// Optional aliases. Used for parsing, suggestions and displayed in Help. public Option(string name, params string[] aliases); public Func? DefaultValueFactory { get; set; } public Func? CustomParser { get; set; } public void AcceptOnlyFromAmong(params string[] values); public void AcceptLegalFilePathsOnly(); public void AcceptLegalFileNamesOnly(); } ///

/// Represents a specific action that the application performs. ///

/// public class CliCommand : CliSymbol, IEnumerable { ///

/// Initializes a new instance of the Command class. ///

/// The name of the command. /// The description of the command, shown in help. public CliCommand(string name, string? description = null); public IList Arguments { get; } public IList Options { get; } public IList Subcommands { get; } public IEnumerable Children { get; } public List> Validators { get; } public ICollection Aliases { get; } // we want to hide from intellisense, it's public for C# duck typing // Command ping = new () // { // new Argument("target"), // new Option("--count") // } [EditorBrowsable(EditorBrowsableState.Never)] public void Add(CliSymbol symbol); ///

/// Gets or sets a value that indicates whether unmatched tokens should be treated as errors. For example, /// if set to and an extra command or argument is provided, validation will fail. ///

public bool TreatUnmatchedTokensAsErrors { get; set; } = true; public ParseResult Parse(IReadOnlyList args, CommandLineConfiguration? configuration = null); /// The command line string input will be split into tokens as if it had been passed on the command line. public ParseResult Parse(string commandLine, CommandLineConfiguration? configuration = null); } } namespace System.CommandLine.Completions { ///

/// Provides details about a command line completion item. ///

public class CompletionItem : IEquatable { /// The label value, which is the text displayed to users and, unless is set, is also used to populate the property. /// The kind of completion item. /// The value used to sort the completion item in a list. If this is not provided, then is used. /// The text to be inserted by this completion item. If this is not provided, then is used. /// Documentation about the completion item. /// Additional details regarding the completion item. public CompletionItem(string label, string kind = "value", string? sortText = null, string? insertText = null, string? documentation = null, string? detail = null); ///

/// The label value, which is the text displayed to users. ///

public string Label { get; } ///

/// The kind of completion item. ///

public string? Kind { get; } ///

/// The value used to sort the completion item in a list. ///

public string SortText { get; } ///

/// The text to be inserted by this completion item. ///

public string? InsertText { get; } ///

/// Documentation about the completion item. ///

public string? Documentation { get; set; } ///

/// Additional details regarding the completion item. ///

public string? Detail { get; } } ///

/// Supports command line completion operations. ///

public abstract class CompletionContext { /// The text of the word to be completed, if any. public string WordToComplete { get; } /// The parse result for which completions are being requested. public ParseResult ParseResult { get; } ///

/// Gets an empty CompletionContext. ///

/// Can be used for testing purposes. public static CompletionContext Empty { get; } } ///

/// Provides details for getting completions when the complete text of the original command line is not available. ///

public class TokenCompletionContext : CompletionContext { } ///

/// Provides details for calculating completions in the context of complete, unsplit command line text. ///

public class TextCompletionContext : CompletionContext { ///

/// The position of the cursor within the command line. ///

public int CursorPosition { get; } ///

/// The complete text of the command line prior to splitting, including any additional whitespace. ///

public string CommandLineText { get; } ///

/// Creates a new instance of at the specified cursor position. ///

/// The cursor position at which completions are calculated. public TextCompletionContext AtCursorPosition(int position); } } namespace System.CommandLine.Parsing { ///

/// Identifies the type of a . ///

public enum CliTokenType { Argument, Command, Option, ///

/// A double dash (--) token, which changes the meaning of subsequent tokens. ///

DoubleDash, Directive } ///

/// A unit of significant text on the command line. ///

public sealed class CliToken : IEquatable { /// The string value of the token. /// The type of the token. /// The symbol represented by the token public Token(string? value, TokenType type, Symbol symbol); public string Value { get; } public CliTokenType Type { get; } } ///

/// A result produced during parsing for a specific symbol. ///

public abstract class SymbolResult { ///

/// The parent symbol result in the parse tree. ///

public SymbolResult? Parent { get; } ///

/// The list of tokens associated with this symbol result during parsing. ///

public IReadOnlyList Tokens { get; } /// Adds an error message for this symbol result to it's parse tree. /// /// Setting an error will cause the parser to indicate an error for the user and prevent invocation of the command line. public virtual void AddError(string errorMessage); ///

/// Finds a result for the specific argument anywhere in the parse tree, including parent and child symbol results. ///

public ArgumentResult? FindResultFor(CliArgument argument); public CommandResult? FindResultFor(CliCommand command); public OptionResult? FindResultFor(CliOption option); ///

/// Gets the parsed or default value for the specified argument. ///

/// The parsed value or a configured default. public T? GetValue(Argument argument); public T? GetValue(Option option); public T? GetValue(string name); } ///

/// A result produced when parsing an . ///

public sealed class ArgumentResult : SymbolResult { ///

/// The argument to which the result applies. ///

public CliArgument Argument { get; } ///

/// Gets the parsed value or the default value for . ///

/// The parsed value or the default value for public T GetValueOrDefault(); ///

/// Specifies the maximum number of tokens to consume for the argument. Remaining tokens are passed on and can be consumed by later arguments, or will otherwise be added to ///

/// The number of tokens to take. The rest are passed on. /// numberOfTokens - Value must be at least 1. /// Thrown if this method is called more than once. /// Thrown if this method is called by Option-owned ArgumentResult. public void OnlyTake(int numberOfTokens); } ///

/// A result produced when parsing an . ///

public sealed class OptionResult : SymbolResult { ///

/// The option to which the result applies. ///

public CliOption Option { get; } ///

/// Indicates whether the result was created implicitly and not due to the option being specified on the command line. ///

/// Implicit results commonly result from options having a default value. public bool IsImplicit { get; } ///

/// The token that was parsed to specify the option. ///

public CliToken? Token { get; } public T GetValueOrDefault(); } ///

/// A result produced when parsing a . ///

public sealed class CommandResult : SymbolResult { ///

/// The command to which the result applies. ///

public CliCommand Command { get; } ///

/// The token that was parsed to specify the command. ///

public CliToken Token { get; } ///

/// Child symbol results in the parse tree. ///

public IEnumerable Children { get; } } ///

/// Describes an error that occurs while parsing command line input. ///

public sealed class CliParseError { ///

/// A message to explain the error to a user. ///

public string Message { get; } ///

/// The symbol result detailing the symbol that failed to parse and the tokens involved. ///

public SymbolResult? SymbolResult { get; } } ///

/// Parses command line input. ///

public static class CliParser { ///

/// Parses a list of arguments. ///

public static ParseResult Parse(Command command, IReadOnlyList args, CommandLineConfiguration? configuration = null); ///

/// Parses a command line string. ///

public static ParseResult Parse(Command command, string commandLine, CommandLineConfiguration? configuration = null); ///

/// Splits a string into a sequence of strings based on whitespace and quotation marks. ///

/// A command line input string. /// A sequence of strings. public static IEnumerable SplitCommandLine(string commandLine); } ///

/// Describes the results of parsing a command line input based on a specific parser configuration. ///

public sealed class ParseResult { ///

/// A result indicating the command specified in the command line input. ///

public CommandResult CommandResult { get; } ///

/// The configuration used to produce the parse result. ///

public CommandLineConfiguration Configuration { get; } ///

/// Gets the root command result. ///

public CommandResult RootCommandResult { get; } ///

/// Gets the parse errors found while parsing command line input. ///

public IReadOnlyList Errors { get; } ///

/// Gets the tokens identified while parsing command line input. ///

public IReadOnlyList Tokens { get; } ///

/// Gets the list of tokens used on the command line that were not matched by the parser. ///

public IReadOnlyList UnmatchedTokens { get; } ///

/// Gets the completion context for the parse result. ///

public CompletionContext GetCompletionContext(); ///

/// Gets the parsed or default value for the specified argument. ///

/// The argument for which to get a value. /// The parsed value or a configured default. public T? GetValue(Argument argument); public T? GetValue(Option option); public T? GetValue(string name); ///

/// Gets the result, if any, for the specified argument. ///

/// The argument for which to find a result. /// A result for the specified argument, or if it was not provided and no default was configured. public ArgumentResult? FindResultFor(Argument argument); public CommandResult? FindResultFor(Command command); public OptionResult? FindResultFor(Option option); public SymbolResult? FindResultFor(Symbol symbol); ///

/// Gets completions based on a given parse result. ///

/// The position at which completions are requested. /// A set of completions for completion. public IEnumerable GetCompletions(int? position = null); } } ```

API Usage

Building dotnet build with S.CL:

```cs // Sample: "dotnet build" CliCommand dotnetBuild = new CliCommand("build") { new CliArgument("file") { Description = "The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.", HelpName = "PROJECT | SOLUTION", DefaultValueFactory = (argumentResult) => { FileInfo? first = new DirectoryInfo(Directory.GetCurrentDirectory()).EnumerateFiles("*.sln|*.proj").FirstOrDefault(); if (first is null) { argumentResult.AddError("Unable to find project or a solution file"); } return first; } }, new CliOption("--use-current-runtime", "--ucr") { Description = "Use current runtime as the target runtime." }, new CliOption("--framework", "-f") { Description = "The target framework to build for. The target framework must also be specified in the project file.", HelpName = "FRAMEWORK", }, new CliOption("--arch", "-a") { Description = "The target architecture.", HelpName = "arch", // Enums don't require a custom parser, it's for example purposes CustomParser = (argumentResult) => Enum.Parse(argumentResult.Tokens[^1]), DefaultValueFactory = (_) => RuntimeInformation.OSArchitecture, }, new CliOption("--os") { Description = "The target operating system.", HelpName = "os", CustomParser = GetOsName, DefaultValueFactory = GetOsName, }, new CliOption("--help") { Description = "Show command line help.", // just to show that this syntax is allowed Aliases = { "-h", "-?" } } }; // an example of both a parser and a custom value provider static string GetOsName(ArgumentResult argumentResult) { if (argumentResult.Tokens.Count > 0) { string provided = argumentResult.Tokens[^1]; if (provided is "win" or "lin" or "osx") { return provided; } argumentResult.AddError($"Unknown Operating System: {provided}"); } return OperatingSystem.IsWindows() ? "win" : OperatingSystem.IsLinux() ? "lin" : "osx"; } ```

Implementing ping utility:

```cs static void Main(string[] args) { Command command = new("ping") { new Argument("target"), new Option("-n") { DefaultValueFactory = (_) => 4, Description = "Number of echo requests to send." } }; ParseResult parseResult = command.Parse(args); string target = parseResult.GetValue("target"); int count = parseResult.GetValue("-n"); using Ping ping = new(); for (int i = 0; i < count; i++) { PingReply pingReply = ping.Send(target); Console.WriteLine($"{i}, Status: {pingReply.Status}, RoundtripTime: {pingReply.RoundtripTime}"); } } ```

Please keep in mind that the example used above does not use the concept of handler/action that we are going to present in a separate proposal.

Risks

• By calling CliOption an option, we follow POSIX naming convention used by vast majority of the OSS parsers. Some users might think that it's an optional argument, while it's just a named argument. We want to stick with the existing naming convention, despite the fact that it's not perfect.
• Both CliArgument<T> and CliOption<T> do not constrain T. We have considered using IParsable, but it would require introducing dedicated types for collections of IParsable, moreover it would limit us to .NET 7.0+. We want to keep supporting .NET Standard 2.0, as plenty of our users are still on .NET Framework.
• AcceptLegalFilePathsOnly and AcceptLegalFileNamesOnly are not constrained to any specific T, while they make sense only for string, IEnumerable<string>

[jkotas]

Splits a string into a sequence of strings based on whitespace and quotation marks. public static IEnumerable SplitCommandLine(string commandLine);

What are the parsing rules that this is going to follow? Is the same set of parsing rules as https://github.com/dotnet/runtime/blob/732ae12c9cdd8227ab2882f0949d798c3fcb446d/src/libraries/System.Private.CoreLib/src/System/Environment.Windows.cs#L225-L226 or different set of rules?

[jonsequitur]

What are the parsing rules that this is going to follow? Is the same set of parsing rules as

It's very close to that and could potentially be made identical. The use case is a little different. This isn't used in the CLI execution code path (since Main receives an already-split string[]). This method is used in the code completion code path and is also very valuable for testing (since when people have to do their own split in tests, they very frequently get it wrong.) For this reason, the goal is to conform to people's experience at the shell, which includes an additional layer of escaping.

There's more detailed discussion of this here: https://github.com/dotnet/command-line-api/issues/1758.

[jonsequitur]

AcceptLegalFilePathsOnly and AcceptLegalFileNamesOnly are not constrained to any specific T, while they make sense only for string, IEnumerable

These also work for FileInfo, DirectoryInfo, and FileSystemInfo, and types implementing IEnumerable<T> for those types. Handling these types is fundamental to many CLIs.

[iSazonov]

I am surprised that there is no mention of the PowerShell experience, which has had this capability for many years. It uses attributes to describe parameters, their hierarchy and argument validations. It also allows custom completers for external applications.

The use of attributes is quite handy for simple cases, but very verbose for complex ones. That's why I've been voicing the idea for a long time that PowerShell needs a simple parameter description notation that can be translated into attributes. As is this project, too. Why not take a general approach? For example, the following is easy to understand and can be parsed and translated into attributes

> gcm Get-Date -Syntax

Get-Date [[-Date] <datetime>] [-Year <int>] [-Month <int>] [-Day <int>] [-Hour <int>] [-Minute <int>] [-Second <int>] [-Millisecond <int>] [-DisplayHint <DisplayHintType>] [-Format <string>] [-AsUTC] [<CommonParameters>]

Get-Date [[-Date] <datetime>] -UFormat <string> [-Year <int>] [-Month <int>] [-Day <int>] [-Hour <int>] [-Minute <int>] [-Second <int>] [-Millisecond <int>] [-DisplayHint <DisplayHintType>] [-AsUTC] [<CommonParameters>]

Get-Date -UnixTimeSeconds <long> -UFormat <string> [-Year <int>] [-Month <int>] [-Day <int>] [-Hour <int>] [-Minute <int>] [-Second <int>] [-Millisecond <int>] [-DisplayHint <DisplayHintType>] [-AsUTC] [<CommonParameters>]

Get-Date -UnixTimeSeconds <long> [-Year <int>] [-Month <int>] [-Day <int>] [-Hour <int>] [-Minute <int>] [-Second <int>] [-Millisecond <int>] [-DisplayHint <DisplayHintType>] [-Format <string>] [-AsUTC] [<CommonParameters>]

Of course it's not ideal and we should have come up with something better.

Why does PowerShell allow custom completers? While all cmdlets (and .Net assemblies) contain meta-information and PowerShell uses reflection to benefit from it, regular (native C/C++) utilities have no such information at all.

So if this project is attribute-based, then applications based on it could easily be integrated into PowerShell, which could simply read meta-information from application assemblies as it does for cmdlets.

If we look at other shells, such as bash, they prefer custom completers written in bash itself. It is hardly possible to change this (for integration with this project). However, it would be possible to create a universal, simple and fast wrapper that would do the same thing as PowerShell for all applications based on this project and called with the standard complete command from bash.

[jeffhandley]

Some notes on the above APIs.

1. CliSymbol.IsHidden
   • Consider IsHiddenFromHelp
   • Is there a concept of terse and verbose help? Should there be an enum for help inclusion?
2. ArgumentArity.ExactlyOne
   • Why does One have an "Exactly" prefix? Could it just be One?
3. ArgumentArity
   • Is it worthwhile to add a ctor for public ArgumentArity(numberOfValues) : new(numberOfValues, numberOfValues) {}?
4. CliArgument<T>.DefaultValueFactory and CliArgument<T>.CustomParser
   • Was there ever an attempt to merge these two such that when no parse input is provided, the parser is called with a null argument result, thus giving the parser an opportunity to return the default value?
5. CliArgument<T>.AcceptOnlyFromAmong, AcceptLegalFilePathsOnly, and AcceptLegalFileNamesOnly
   • These three validators seem to be getting special treatment, which is odd
   • Why are these three promoted to be baked in vs. being validators that can be easily added to Validators?
6. AcceptOnlyFromAmong
   • We just introduced a new DataAnnotations.AllowedValuesAttribute
   • In whatever form this capability surfaces, we should consider aligning to the AllowedValues name
7. CliCommand.Add(CliSymbol symbol)
   • Why hide it from IntelliSense? It seems useful outside the initialization use case too.
8. CliCommand.TreatUnmatchedTokensAsErrors
   • Consider inverting this with a name change to IgnoreUnmatchedTokens
9. CliArgument.HelpName and CliOption.HelpName
   • The comments have to explain that this "name" isn't actually a "name," it's just used in help output
   • Consider "HelpDisplayName" to make that more obvious

I've reviewed through CliCommand and will resume my review starting at CompletionItem later.

[jonsequitur]

@iSazonov

I am surprised that there is no mention of the PowerShell experience, which has had this capability for many years.

What you're describing makes sense, though at an API layer above System.CommandLine. Attributes are a common API preference and the System.CommandLine source generator will use them. They still need to drive some lower-level API that handles the core parsing. That lower-level API is System.CommandLine. Once it's done, then integration with PowerShell as you describe, as well as other opinionated APIs, become easier.

If we look at other shells, such as bash, they prefer custom completers written in bash itself. It is hardly possible to change this (for integration with this project). However, it would be possible to create a universal, simple and fast wrapper that would do the same thing as PowerShell for all applications based on this project and called with the standard complete command from bash.

System.CommandLine has completion shim scripts for PowerShell, zsh, and bash. In the long run, generating those scripts, rather than using a shim script that forwards completion requests to another process, will provide some performance benefits, but the lack of common conventions makes it a lot of work. A universal wrapper would be very useful and could emerge from this work.

[jonsequitur]

@jeffhandley

1. CliSymbol.IsHidden
   • Is there a concept of terse and verbose help? Should there be an enum for help inclusion?

It's something we've discussed. The conclusion has generally been that abstractions for help will never be able to handle all of the variety people want, and that a templating language at a higher layer (e.g. one that on detects terminal or even non-terminal UI capabilities and emits VT codes, Markdown, etc.) might be more suitable.

3. ArgumentArity
   • Is it worthwhile to add a ctor for public ArgumentArity(numberOfValues) : new(numberOfValues, numberOfValues) {}?

In the large majority of cases, arity is inferred from the generic type parameter, so we kept it out of the constructor for simplicity.

4. CliArgument<T>.DefaultValueFactory and CliArgument<T>.CustomParser
   • Was there ever an attempt to merge these two such that when no parse input is provided, the parser is called with a null argument result, thus giving the parser an opportunity to return the default value?

The previous iterations did exactly that, but it's akward to use:

new Argument<T>(
    parse: argResult => { /* custom parsing logic*/ },
    isDefault: /* call the above delegate even if no tokens matched this symbol during parsing */ 
);

I think we can still improve the ergonomics here.

5. CliArgument<T>.AcceptOnlyFromAmong, AcceptLegalFilePathsOnly, and AcceptLegalFileNamesOnly
   • These three validators seem to be getting special treatment, which is odd
   • Why are these three promoted to be baked in vs. being validators that can be easily added to Validators?

The reasoning is that the need for these is incredibly common in CLI apps. Letting people implement them themselves has a few gotchas for cross-plat as well.

8. CliCommand.TreatUnmatchedTokensAsErrors
   • Consider inverting this with a name change to IgnoreUnmatchedTokens

This is interesting. I could read "ignore" as meaning I won't be able to see them in the parse result, which isn't the case. For a little more context, the use case for this is sort of like a wildcard. You're expecting tokens that the parser has no rules about and you want to handle them at a later phase, often with a separate parser instance. This is how dotnet new handles template-specific parsing, for example.

[KalleOlaviNiemitalo]

Consider IsHiddenFromHelp

IsHidden affects completion too, so IsHiddenFromHelp would be too restrictive.

[iSazonov]

What you're describing makes sense, though at an API layer above System.CommandLine.

System.CommandLine layer is essentially implementation details or engine. In fact, we need a user-friendly (and formally strong) language to describe a set of parameters that translates into attributes that is low level language. Both of these levels should be public. The engine itself (and translator/SG) is essentially implementation details and it doesn't require to expose a public API.

I would suggest contacting the PowerShell developers who designed and implemented this mechanism years ago. I haven't had much contact with them on this subject, but it was enough to appreciate what a great job they did in both analysis and implementation.

I'm surprised this project didn't take PowerShell as a starting point. PowerShell is a unique hybrid application that acts as both a shell and a script engine while also being a natural and inseparable extension of .Net - everything written in .Net is natively embedded in PowerShell. So I would expect this project to evolve in that direction. Once again, in this case - all .Net applications will automatically be embedded in PowerShell. Isn't that what Azure's gigantic infrastructure needs?

For native applications, we could create a translator into native code and at the same time generate a pseudo assembly that PowerShell could also use to get the same meta-information. All we would have to do is create a simple, lightweight handler in the native language that would be called from bash (and others), load this pseudo assembly, and do what PowerShell does.

[jonsequitur]

I would suggest contacting the PowerShell developers ... I'm surprised this project didn't take PowerShell as a starting point.

We've been talking with the PowerShell team from the outset of this project. The goals are different enough that converging solutions isn't likely to be useful.

A crucial point is that System.CommandLine is meant to handle the superset of GNU/POSIX and Windows command line grammars, including support for subcommands. PowerShell is stricter and it can't accommodate these less formalized grammars, which predate PowerShell and are more widely used.

So System.CommandLine logically sits lower down in the stack than PowerShell and is less opinionated about its internal API than about its ability to create unopinionated external API (i.e. your CLI). The System.CommandLine API's ergonomic goal is to be as simple as possible. Different API preferences can be met with an additional layer whether attributes, fluent APIs, or DSLs.

[iSazonov]

I'm not saying that PowerShell should migrate to System.CommandLine. This is not possible and is not necessary. I'm saying that PowerShell needs meta information that allows it to transparently integrate any utility/application and provide at least tab-completion.

Of course we need at least three layers - a parameter description language, an intermediate language (e.g. attributes), a low-level layer. If this project is only the latter and has nothing to do with the rest, then unfortunately it is useless for PowerShell. In general, its usefulness is questionable, because history shows that usually any attempt to create a superset ends up in oblivion. The reason is trivial: a project is not part of the existing ecosystems. If this project does not consider integration with existing ecosystems, the same fate awaits it. If it will be used even in a hundred utilities, this is nothing compared to tens of thousands of utilities in Unix and Windows.

[KalleOlaviNiemitalo]

Generating meta information at build time would not allow completion for things like the MSBuild -target:<targets> option, where the available targets depend on the project file and imported SDKs; or -logger:<logger>, where the supported logger options depend on the logger type. For these, one still needs a protocol that queries completions from application-specific code at run time, like dotnet-suggest does. The application-specific completion code can be written separately for each shell as is traditionally done, but it is more convenient for developers of applications and for users of rare shells if the same implementation can be used for all shells.

[iSazonov]

If the dynamic substitution of arguments requires a full start of the application itself, it is obviously not feasible in the general case. However, PowerShell, for example, sometimes does clever things based on the current context and implementation of the attributes themselves.

[jonsequitur]

If the dynamic substitution of arguments requires a full start of the application itself, it is obviously not feasible in the general case.

It currently does start your process, and performance is acceptable (at least, better than not having completions) but it can definitely be improved. It eventually won't need to start your process, as we'll emit shell-specific completion scripts based on your app's parser. Some shells (zsh, PowerShell) have the ability for completion scripts to call back for dynamic arguments, which the [suggest] directive will still support on an as-needed basis.

[KieranDevvs]

Can someone give me a summary on where this proposal is at? I saw a few weeks / months back that it was in the API review meetings but it looks like it got cut short due to more important API's taking priority, and thus never went back to get it approved. I now see there's a new proposal? I played around with the old previews of System.CommandLine and I've even adopted it into one of my personal projects. What's changed in the new proposal and is there a preview build to play around with the new changes?

[jonsequitur]

@KieranDevvs, here are some threads that help summarize the portions currently being worked on:

• Parser API: https://github.com/dotnet/runtime/issues/68578#issuecomment-1461983285
• Configuration: https://github.com/dotnet/command-line-api/issues/2101
• Invocation: https://github.com/dotnet/command-line-api/issues/2071

We're hoping to have a new preview release incorporating these changes in the coming weeks.

[adamsitnik]

Background and motivation

System.CommandLine has a very ambitious goal. We want to provide a set of simple, intuitive, and performant APIs for parsing of command line arguments, but at the same time we want them to be flexible enough to meet the requirements of users who build complex CLIs like “dotnet”. We basically want to avoid situations where people develop their own parsers because S.CL is missing something important.

The APIs that we want to include in BCL can be grouped into following categories:

• Building a hierarchy of symbols
• Completions
• Parsing the hierarchy for given input
• Execution of the parsed result (an optional step, not included in this proposal)

We expect these APIs to be building blocks for:

• Advanced users who build fully featured CLIs.
• Our incoming source-generator based solution (not included in this proposal), which aims for simplicity and not needing the users to become familiar with most of the concepts related to parsing.

// An example of how incoming source-generator based solution might look like
class Program
{
    static int Main(string target, int count = 4)
    {
        // arguments are already parsed!
    }
}

// The alternative
static int Main(string[] args)
{
    Command pingCommand = new ("ping")
    {
        new Argument<string>("target");
        new Option<int?>("--count")
    };

    ParseResult parseResult = pingCommand.Parse(args);

    string target = parseResult.GetValue<string>("target")
    int count = parseResult.GetValue<int?>("--count") ?? 4;
}

Reviewing by Concept rather than full Type

Symbols

```cs namespace System.CommandLine; ///

/// Defines a named symbol that resides in a hierarchy with parent and child symbols. ///

public abstract class CliSymbol { ///

/// Gets or sets the description of the symbol. ///

public string? Description { get; set; } ///

/// Gets the name of the symbol. ///

public string Name { get; } ///

/// Gets or sets a value indicating whether the symbol is hidden. ///

public bool IsHidden { get; set; } ///

/// Gets the parent symbols. ///

public IEnumerable Parents { get; } } ///

/// A symbol defining a value that can be passed on the command line to a command or option. ///

public abstract class CliArgument : CliSymbol { ///

/// The name used in help output to describe the argument. ///

/// Example: `dotnet build --help` /// Arguments: /// The project or solution file to operate on. /// "PROJECT | SOLUTION" is the HelpName here public string? HelpName { get; set; } ///

/// Gets or sets the that the argument token(s) will be converted to. ///

public abstract Type ValueType { get; } } public class CliArgument : CliArgument { ///

/// Initializes a new instance of the Argument class. ///

/// The name of the argument. It's not used for parsing, only when displaying Help or creating parse errors.> public CliArgument(string name); /// public override Type ValueType => typeof(T); } ///

/// A symbol defining a named parameter and a value for that parameter. ///

public abstract class CliOption : CliSymbol { ///

/// Gets or sets the name of the Option when displayed in help. ///

/// /// The name of the option when displayed in help. /// /// Useful for localization, as it's not used for actual parsing. public string? HelpName { get; set; } ///

/// When set to true, this option will be applied to the command and recursively to subcommands. /// It will not apply to parent commands. ///

public bool AppliesToSelfAndChildren { get; set; } ///

/// Indicates whether the option is required when its parent command is invoked. ///

/// When an option is required and its parent command is invoked without it, an error results. public bool IsRequired { get; set; } ///

/// Gets the unique set of strings that can be used on the command line to specify the Option. ///

/// The collection does not contain the of the Option. public ICollection Aliases { get; } } public class CliOption : CliOption { ///

/// Initializes a new instance of the Option class. ///

/// The name of the option. It's used for parsing, displaying Help and creating parse errors.> /// Optional aliases. Used for parsing, suggestions and displayed in Help. public CliOption(string name, params string[] aliases); } ///

/// Represents a specific action that the application performs. ///

/// /// Use the Command object for actions that correspond to a specific string (the command name). See /// for simple applications that only have one action. For example, dotnet run /// uses run as the command. /// public class CliCommand : CliSymbol, IEnumerable { ///

/// Initializes a new instance of the Command class. ///

/// The name of the command. /// The description of the command, shown in help. public CliCommand(string name, string? description = null); ///

/// Gets the child symbols. ///

public IEnumerable Children { get; } ///

/// Represents all of the arguments for the command. ///

public IList Arguments { get; } ///

/// Represents all of the options for the command, including global options that have been applied to any of the command's ancestors. ///

public IList Options { get; } ///

/// Represents all of the subcommands for the command. ///

public IList Subcommands { get; } ///

/// Gets the unique set of strings that can be used on the command line to specify the command. ///

/// The collection does not contain the of the Command. public ICollection Aliases { get; } ///

/// Adds a to the command. ///

/// The symbol to add to the command. [EditorBrowsable(EditorBrowsableState.Never)] // hide from intellisense, it's public for C# duck typing public void Add(CliSymbol symbol); ///

/// Represents all of the symbols for the command. ///

public IEnumerator GetEnumerator() => Children.GetEnumerator(); /// IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); } ///

/// The purpose of directives is to provide cross-cutting functionality that can apply across command-line apps. /// Because directives are syntactically distinct from the app's own syntax, they can provide functionality that applies across apps. /// /// A directive must conform to the following syntax rules: /// * It's a token on the command line that comes after the app's name but before any subcommands or options. /// * It's enclosed in square brackets. /// * It doesn't contain spaces. ///

public class CliDirective : CliSymbol { ///

/// Initializes a new instance of the Directive class. ///

/// The name of the directive. It can't contain whitespaces. public CliDirective(string name); } ///

/// Enables the use of the [env:key=value] directive, allowing environment variables to be set from the command line during invocation. ///

public sealed class EnvironmentVariablesDirective : CliDirective { public EnvironmentVariablesDirective(); } ///

/// Enables the use of the [suggest] directive which when specified in command line input short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command line completions. ///

/// The dotnet-suggest tool requires the suggest directive to be enabled for an application to provide completions. public sealed class SuggestDirective : CliDirective { public SuggestDirective(); } ///

/// Enables the use of the [diagram] directive, which when specified on the command line will short /// circuit normal command handling and display a diagram explaining the parse result for the command line input. ///

/// Example: dotnet [diagram] build -c Release -f net7.0 /// Output: [ dotnet [ build [ -c ] [ -f ] ] ] public sealed class DiagramDirective : CliDirective { /// If the parse result contains errors, this exit code will be used when the process exits. public DiagramDirective(int errorExitCode = DefaultErrorExitCode); } ```

Parsing

```cs namespace System.CommandLine.Parsing ///

/// Identifies the type of a . ///

public enum TokenType { ///

/// An argument token. ///

/// Argument, ///

/// A command token. ///

/// Command, ///

/// An option token. ///

/// Option, ///

/// A double dash (--) token, which changes the meaning of subsequent tokens. ///

DoubleDash, ///

/// A directive token. ///

/// Directive } ///

/// A unit of significant text on the command line. ///

public sealed class CliToken : IEquatable { /// The string value of the token. /// The type of the token. /// The symbol represented by the token public CliToken(string? value, TokenType type, CliSymbol symbol); ///

/// The string value of the token. ///

public string Value { get; } ///

/// The type of the token. ///

public TokenType Type { get; } } ///

/// Defines the arity of an option or argument. ///

/// The arity refers to the number of values that can be passed on the command line. /// public readonly struct ArgumentArity : IEquatable { ///

/// Initializes a new instance of the ArgumentArity class. ///

/// The minimum number of values required for the argument. /// The maximum number of values allowed for the argument. /// Thrown when is negative. /// Thrown when the maximum number is less than the minimum number or the maximum number is greater than MaximumArity. public ArgumentArity(int minimumNumberOfValues, int maximumNumberOfValues); ///

/// Gets the minimum number of values required for an argument. ///

public int MinimumNumberOfValues { get; } ///

/// Gets the maximum number of values allowed for an argument. ///

public int MaximumNumberOfValues { get; } ///

/// An arity that does not allow any values. ///

public static ArgumentArity Zero => new(0, 0); ///

/// An arity that may have one value, but no more than one. ///

public static ArgumentArity ZeroOrOne => new(0, 1); ///

/// An arity that must have exactly one value. ///

public static ArgumentArity ExactlyOne => new(1, 1); ///

/// An arity that may have multiple values. ///

public static ArgumentArity ZeroOrMore => new(0, MaximumArity); ///

/// An arity that must have at least one value. ///

public static ArgumentArity OneOrMore => new(1, MaximumArity); } ///

/// Describes an error that occurs while parsing command line input. ///

public sealed class ParseError { ///

/// A message to explain the error to a user. ///

public string Message { get; } ///

/// The symbol result detailing the symbol that failed to parse and the tokens involved. ///

public SymbolResult? SymbolResult { get; } } ///

/// A result produced during parsing for a specific symbol. ///

public abstract class SymbolResult { ///

/// The parent symbol result in the parse tree. ///

public SymbolResult? Parent { get; } ///

/// The list of tokens associated with this symbol result during parsing. ///

public IReadOnlyList Tokens { get; } ///

/// Adds an error message for this symbol result to it's parse tree. ///

/// Setting an error will cause the parser to indicate an error for the user and prevent invocation of the command line. public virtual void AddError(string errorMessage); ///

/// Finds a result for the specific argument anywhere in the parse tree, including parent and child symbol results. ///

/// The argument for which to find a result. /// An argument result if the argument was matched by the parser or has a default value; otherwise, null. public ArgumentResult? FindResultFor(CliArgument argument); public CommandResult? FindResultFor(CliCommand command); public OptionResult? FindResultFor(CliOption option); public DirectiveResult? FindResultFor(CliDirective directive); public T? GetValue(CliArgument argument); public T? GetValue(CliOption option); } ///

/// A result produced when parsing an . ///

public sealed class ArgumentResult : SymbolResult { ///

/// The argument to which the result applies. ///

public CliArgument Argument { get; } ///

/// Gets the parsed value or the default value for . ///

/// The parsed value or the default value for public T GetValueOrDefault(); ///

/// Specifies the maximum number of tokens to consume for the argument. Remaining tokens are passed on and can be consumed by later arguments, or will otherwise be added to ///

/// The number of tokens to take. The rest are passed on. /// numberOfTokens - Value must be at least 1. /// Thrown if this method is called more than once. /// Thrown if this method is called by Option-owned ArgumentResult. public void OnlyTake(int numberOfTokens); } ///

/// A result produced when parsing an . ///

public sealed class OptionResult : SymbolResult { ///

/// The option to which the result applies. ///

public CliOption Option { get; } ///

/// Indicates whether the result was created implicitly and not due to the option being specified on the command line. ///

/// Implicit results commonly result from options having a default value. public bool IsImplicit { get; } ///

/// The token that was parsed to specify the option. ///

public CliToken? IdentifierToken { get; } ///

/// Gets the parsed value or the default value for . ///

/// The parsed value or the default value for public T? GetValueOrDefault(); } ///

/// A result produced when parsing an . ///

public sealed class DirectiveResult : SymbolResult { ///

/// Parsed values of [name:value] directive(s). ///

/// Can be empty for [name] directives. public IReadOnlyList Values { get; } ///

/// The directive to which the result applies. ///

public CliDirective Directive { get; } ///

/// The token that was parsed to specify the directive. ///

public CliToken IdentifierToken { get; } } ///

/// A result produced when parsing a . ///

public sealed class CommandResult : SymbolResult { ///

/// The command to which the result applies. ///

public CliCommand Command { get; } ///

/// The token that was parsed to specify the command. ///

public CliToken IdentifierToken { get; } ///

/// Child symbol results in the parse tree. ///

public IEnumerable Children { get; } } public abstract class CliArgument : CliSymbol { ///

/// Gets or sets the arity of the argument. ///

public ArgumentArity Arity { get; set; } ///

/// Specifies if a default value is defined for the argument. ///

public abstract bool HasDefaultValue { get; } ///

/// Gets the default value for the argument. ///

/// Returns the default value for the argument, if defined. Null otherwise. public object? GetDefaultValue(); } public class CliArgument : CliArgument { ///

/// A custom argument parser. ///

/// /// It's invoked when there was parse input provided for given Argument. /// The same instance can be set as , in such case /// the delegate is also invoked when no input was provided. /// public Func? CustomParser { get; set; } ///

/// The delegate to invoke to create the default value. ///

/// /// It's invoked when there was no parse input provided for given Argument. /// The same instance can be set as , in such case /// the delegate is also invoked when an input was provided. /// public Func? DefaultValueFactory { get; set; } } ///

/// A symbol defining a named parameter and a value for that parameter. ///

public abstract class CliOption : CliSymbol { ///

/// Gets or sets the arity of the option. ///

public ArgumentArity Arity { get; set; } ///

/// Gets a value that indicates whether multiple argument tokens are allowed for each option identifier token. ///

/// /// If set to , the following command line is valid for passing multiple arguments: /// /// > --opt 1 2 3 /// /// The following is equivalent and is always valid: /// /// > --opt 1 --opt 2 --opt 3 /// /// public bool AllowMultipleArgumentsPerToken { get; set; } } public class CliOption : CliOption { public Func? DefaultValueFactory { get; set; } public Func? CustomParser { get; set; } } public class CliCommand : CliSymbol, IEnumerable { ///

/// Gets or sets a value that indicates whether unmatched tokens should be treated as errors. For example, /// if set to and an extra command or argument is provided, validation will fail. ///

public bool TreatUnmatchedTokensAsErrors { get; set; } = true; ///

/// Parses an array strings using the command. ///

/// The string arguments to parse. /// The configuration on which the parser's grammar and behaviors are based. /// A parse result describing the outcome of the parse operation. public ParseResult Parse(IReadOnlyList args, CliConfiguration? configuration = null); ///

/// Parses a command line string value using the command. ///

/// The command line string input will be split into tokens as if it had been passed on the command line. /// A command line string to parse, which can include spaces and quotes equivalent to what can be entered into a terminal. /// The configuration on which the parser's grammar and behaviors are based. /// A parse result describing the outcome of the parse operation. public ParseResult Parse(string commandLine, CliConfiguration? configuration = null); } ///

/// Replaces a token with one or more other tokens prior to parsing. ///

public delegate bool TryReplaceToken( string tokenToReplace, out IReadOnlyList? replacementTokens, out string? errorMessage); //

/// Represents the configuration used by the . ///

public class CliConfiguration { ///

/// Initializes a new instance of the class. ///

/// The root command for the parser. public CliConfiguration(CliCommand rootCommand); ///

/// Gets a mutable list of the enabled directives. /// Currently only is enabled by default. ///

public List Directives { get; } ///

/// Enables the parser to recognize and expand POSIX-style bundled options. ///

/// to parse POSIX bundles; otherwise, . /// /// POSIX conventions recommend that single-character options be allowed to be specified together after a single - prefix. When is set to , the following command lines are equivalent: /// /// /// > myapp -a -b -c /// > myapp -abc /// /// /// If an argument is provided after an option bundle, it applies to the last option in the bundle. When is set to , all of the following command lines are equivalent: /// /// > myapp -a -b -c arg /// > myapp -abc arg /// > myapp -abcarg /// /// /// public bool EnablePosixBundling { get; set; } = true; ///

/// Enables a default exception handler to catch any unhandled exceptions thrown during invocation. Enabled by default. ///

public bool EnableDefaultExceptionHandler { get; set; } = true; ///

/// Configures the command line to write error information to standard error when there are errors parsing command line input. Enabled by default. ///

public bool EnableParseErrorReporting { get; set; } = true; ///

/// Configures the application to provide alternative suggestions when a parse error is detected. Disabled by default. ///

public bool EnableTypoCorrections { get; set; } = false; ///

/// Enables signaling and handling of process termination (Ctrl+C, SIGINT, SIGTERM) via a /// that can be passed to a during invocation. /// If not provided, a default timeout of 2 seconds is enforced. ///

public TimeSpan? ProcessTerminationTimeout { get; set; } = TimeSpan.FromSeconds(2); ///

/// Response file token replacer, enabled by default. /// To disable response files support, this property needs to be set to null. ///

/// /// When enabled, any token prefixed with @ can be replaced with zero or more other tokens. This is mostly commonly used to expand tokens from response files and interpolate them into a command line prior to parsing. /// public TryReplaceToken? ResponseFileTokenReplacer { get; set; } ///

/// Gets the root command. ///

public CliCommand RootCommand { get; } ///

/// The standard output. Used by Help and other facilities that write non-error information. /// By default it's set to . /// For testing purposes, it can be set to a new instance of . /// If you want to disable the output, please set it to . ///

public TextWriter Output { get; set; } = Console.Out; ///

/// The standard error. Used for printing error information like parse errors. /// By default it's set to . /// For testing purposes, it can be set to a new instance of . ///

public TextWriter Error { get; set; } = Console.Error; ///

/// Parses an array strings using the configured . ///

/// The string arguments to parse. /// A parse result describing the outcome of the parse operation. public ParseResult Parse(IReadOnlyList args); ///

/// Parses a command line string value using the configured . ///

/// The command line string input will be split into tokens as if it had been passed on the command line. /// A command line string to parse, which can include spaces and quotes equivalent to what can be entered into a terminal. /// A parse result describing the outcome of the parse operation. public ParseResult Parse(string commandLine); } ///

/// Parses command line input. ///

public static class CliParser { ///

/// Parses a list of arguments. ///

/// The command to use to parse the command line input. /// The string array typically passed to a program's Main method. /// The configuration on which the parser's grammar and behaviors are based. /// A providing details about the parse operation. public static ParseResult Parse(CliCommand command, IReadOnlyList args, CliConfiguration? configuration = null); ///

/// Parses a command line string. ///

/// The command to use to parse the command line input. /// The complete command line input prior to splitting and tokenization. This input is not typically available when the parser is called from Program.Main. It is primarily used when calculating completions via the dotnet-suggest tool. /// The configuration on which the parser's grammar and behaviors are based. /// The command line string input will be split into tokens as if it had been passed on the command line. /// A providing details about the parse operation. public static ParseResult Parse(CliCommand command, string commandLine, CliConfiguration? configuration = null); ///

/// Splits a string into a sequence of strings based on whitespace and quotation marks. ///

/// A command line input string. /// A sequence of strings. public static IEnumerable SplitCommandLine(string commandLine); } ///

/// Describes the results of parsing a command line input based on a specific parser configuration. ///

public sealed class ParseResult { ///

/// A result indicating the command specified in the command line input. ///

public CommandResult CommandResult { get; } ///

/// The configuration used to produce the parse result. ///

public CliConfiguration Configuration { get; } ///

/// Gets the root command result. ///

public CommandResult RootCommandResult { get; } ///

/// Gets the parse errors found while parsing command line input. ///

public IReadOnlyList Errors { get; } ///

/// Gets the tokens identified while parsing command line input. ///

public IReadOnlyList Tokens { get; } ///

/// Gets the list of tokens used on the command line that were not matched by the parser. ///

public string[] UnmatchedTokens { get; } ///

/// Gets the completion context for the parse result. ///

public CompletionContext GetCompletionContext(); ///

/// Gets the parsed or default value for the specified argument. ///

/// The argument for which to get a value. /// The parsed value or a configured default. public T? GetValue(CliArgument argument); ///

/// Gets the parsed or default value for the specified option. ///

/// The option for which to get a value. /// The parsed value or a configured default. public T? GetValue(CliOption option); ///

/// Gets the parsed or default value for the specified symbol name, in the context of parsed command (not entire symbol tree). ///

/// The name of the Symbol for which to get a value. /// The parsed value or a configured default. /// Thrown when parsing resulted in parse error(s). /// Thrown when there was no symbol defined for given name for the parsed command. /// Thrown when parsed result can not be casted to . public T? GetValue(string name); ///

/// Gets the result, if any, for the specified argument. ///

/// The argument for which to find a result. /// A result for the specified argument, or if it was not provided and no default was configured. public ArgumentResult? FindResultFor(CliArgument argument); public CommandResult? FindResultFor(CliCommand command); public OptionResult? FindResultFor(CliOption option); public DirectiveResult? FindResultFor(CliDirective directive); public SymbolResult? FindResultFor(CliSymbol symbol); } ```

Validation

```cs public abstract class CliArgument : CliSymbol { ///

/// Provides a list of argument validators. Validators can be used /// to provide custom errors based on user input. ///

public List> Validators { get; } ///

/// Configures the argument to accept only the specified values, and to suggest them as command line completions. ///

/// The values that are allowed for the argument. public void AcceptOnlyFromAmong(params string[] values); ///

/// Configures the argument to accept only values representing legal file paths. ///

public void AcceptLegalFilePathsOnly(); ///

/// Configures the argument to accept only values representing legal file names. ///

/// A parse error will result, for example, if file path separators are found in the parsed value. public void AcceptLegalFileNamesOnly(); } ///

/// Provides extension methods for . ///

public static class ArgumentValidation { ///

/// Configures an argument to accept only values corresponding to an existing file. ///

/// The argument to configure. /// The configured argument. public static CliArgument AcceptExistingOnly(this CliArgument argument); public static CliArgument AcceptExistingOnly(this CliArgument argument); public static CliArgument AcceptExistingOnly(this CliArgument argument); public static CliArgument AcceptExistingOnly(this CliArgument argument) where T : IEnumerable } public abstract class CliOption : CliSymbol { ///

/// Validators that will be called when the option is matched by the parser. ///

public List> Validators { get; } ///

/// Configures the option to accept only the specified values, and to suggest them as command line completions. ///

/// The values that are allowed for the option. public void AcceptOnlyFromAmong(params string[] values); ///

/// Configures the option to accept only values representing legal file paths. ///

public void AcceptLegalFilePathsOnly(); ///

/// Configures the option to accept only values representing legal file names. ///

/// A parse error will result, for example, if file path separators are found in the parsed value. public void AcceptLegalFileNamesOnly(); } ///

/// Provides extension methods for . ///

public static class OptionValidation { public static CliOption AcceptExistingOnly(this CliOption option); public static CliOption AcceptExistingOnly(this CliOption option); public static CliOption AcceptExistingOnly(this CliOption option); public static CliOption AcceptExistingOnly(this CliOption option) where T : IEnumerable } public class CliCommand : CliSymbol, IEnumerable { ///

/// Validators to the command. Validators can be used /// to create custom validation logic. ///

public List> Validators { get; } } ```

Completions

```cs namespace System.CommandLine.Completions; ///

/// Provides details about a command line completion item. ///

/// reference: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_completion public class CompletionItem : IEquatable { /// The label value, which is the text displayed to users and, unless is set, is also used to populate the property. /// The kind of completion item. /// The value used to sort the completion item in a list. If this is not provided, then is used. /// The text to be inserted by this completion item. If this is not provided, then is used. /// Documentation about the completion item. /// Additional details regarding the completion item. public CompletionItem(string label, string kind = "Value", string? sortText = null, string? insertText = null, string? documentation = null, string? detail = null); ///

/// The label value, which is the text displayed to users. ///

public string Label { get; } ///

/// The kind of completion item. ///

public string? Kind { get; } ///

/// The value used to sort the completion item in a list. ///

public string SortText { get; } ///

/// The text to be inserted by this completion item. ///

public string? InsertText { get; } ///

/// Documentation about the completion item. ///

public string? Documentation { get; set; } ///

/// Additional details regarding the completion item. ///

public string? Detail { get; } } ///

/// Supports command line completion operations. ///

public class CompletionContext { /// The text of the word to be completed, if any. public string WordToComplete { get; } /// The parse result for which completions are being requested. public ParseResult ParseResult { get; } ///

/// Gets an empty CompletionContext. ///

/// Can be used for testing purposes. public static CompletionContext Empty { get; } } ///

/// Provides details for calculating completions in the context of complete, unsplit command line text. ///

public class TextCompletionContext : CompletionContext { ///

/// The position of the cursor within the command line. ///

public int CursorPosition { get; } ///

/// The complete text of the command line prior to splitting, including any additional whitespace. ///

public string CommandLineText { get; } ///

/// Creates a new instance of at the specified cursor position. ///

/// The cursor position at which completions are calculated. public TextCompletionContext AtCursorPosition(int position); } public abstract class CliSymbol { ///

/// Gets completions for the symbol. ///

public abstract IEnumerable GetCompletions(CompletionContext context); } public abstract class CliArgument : CliSymbol { ///

/// Gets the list of completion sources for the argument. ///

public List>> CompletionSources { get; } } public abstract class CliOption : CliSymbol { ///

/// Gets the list of completion sources for the option. ///

public List>> CompletionSources { get; } } public sealed class ParseResult { ///

/// Gets completions based on a given parse result. ///

/// The position at which completions are requested. /// A set of completions for completion. public IEnumerable GetCompletions(int? position = null); } ```

Execution

```cs ///

/// Defines the behavior of a symbol. ///

public abstract class CliAction { ///

/// Performs an action when the associated symbol is invoked on the command line. ///

/// Provides the parse results. /// A value that can be used as the exit code for the process. public abstract int Invoke(ParseResult parseResult); ///

/// Performs an action when the associated symbol is invoked on the command line. ///

/// Provides the parse results. /// The token to monitor for cancellation requests. /// A value that can be used as the exit code for the process. public abstract Task InvokeAsync(ParseResult parseResult, CancellationToken cancellationToken = default); } public abstract class CliOption : CliSymbol { ///

/// Gets or sets the for the Option. The handler represents the action /// that will be performed when the Option is invoked. ///

public virtual CliAction? Action { get; set; } } public sealed class HelpAction : CliAction { // it will expose help customization APIs in the near future } public class CliDirective : CliSymbol { ///

/// Gets or sets the for the Directive. The handler represents the action /// that will be performed when the Directive is invoked. ///

public virtual CliAction? Action { get; set; } } public class CommandAction : CliAction { } public class CliCommand : CliSymbol, IEnumerable { ///

/// Gets or sets the for the Command. The handler represents the action /// that will be performed when the Command is invoked. ///

/// /// Use one of the overloads to construct a handler. /// If the handler is not specified, parser errors will be generated for command line input that /// invokes this Command. public CommandAction? Action { get; set; } ///

/// Sets a synchronous action to be run when the command is invoked. ///

public void SetAction(Action action); ///

/// Sets a synchronous action to be run when the command is invoked. ///

/// The value returned from the delegate can be used to set the process exit code. public void SetAction(Func action); ///

/// Sets an asynchronous action to be run when the command is invoked. ///

public void SetAction(Func action); ///

/// Sets an asynchronous action when the command is invoked. ///

/// The value returned from the delegate can be used to set the process exit code. public void SetAction(Func> action); } public sealed class ParseResult { ///

/// Gets the for parsed result. The handler represents the action /// that will be performed when the parse result is invoked. ///

public CliAction? Action { get; } ///

/// Invokes the appropriate command handler for a parsed command line input. ///

/// A token that can be used to cancel an invocation. /// A task whose result can be used as a process exit code. public Task InvokeAsync(CancellationToken cancellationToken = default); ///

/// Invokes the appropriate command handler for a parsed command line input. ///

/// A value that can be used as a process exit code. public int Invoke() => InvocationPipeline.Invoke(this); } ```

Help customization

TBA