From 3cd59d2d9e6909c59f23345f3478a03d045d2739 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Mon, 11 Apr 2022 10:34:12 -0700 Subject: [PATCH 1/2] Add seealso links --- src/System.CommandLine/Argument.cs | 17 ++++++++++-- src/System.CommandLine/ArgumentArity.cs | 11 +++++++- src/System.CommandLine/ArgumentExtensions.cs | 15 +++++++++++ src/System.CommandLine/Argument{T}.cs | 5 ++++ .../Binding/BinderBase{T}.cs | 3 +++ .../Binding/BindingContext.cs | 2 ++ src/System.CommandLine/Binding/BoundValue.cs | 1 + .../Builder/CommandLineBuilder.cs | 1 + src/System.CommandLine/Command.cs | 17 ++++++++++++ src/System.CommandLine/CommandExtensions.cs | 6 +++++ .../CommandLineConfiguration.cs | 2 ++ .../CompletionSourceExtensions.cs | 6 ++++- .../CompletionSourceList.cs | 2 ++ .../Completions/CompletionContext.cs | 3 ++- .../Completions/CompletionDelegate.cs | 1 + .../Completions/CompletionItem.cs | 1 + .../Completions/ICompletionSource.cs | 1 + .../Completions/TextCompletionContext.cs | 1 + .../Completions/TokenCompletionContext.cs | 1 + src/System.CommandLine/DirectiveCollection.cs | 3 +++ src/System.CommandLine/Handler.Action.cs | 18 +++++++++++++ src/System.CommandLine/Handler.Func.cs | 17 ++++++++++++ .../Help/HelpBuilder.Default.cs | 1 + src/System.CommandLine/Help/HelpBuilder.cs | 1 + .../Help/HelpBuilderExtensions.cs | 1 + src/System.CommandLine/Help/HelpContext.cs | 1 + .../Help/HelpSectionDelegate.cs | 1 + .../Help/TwoColumnHelpRow.cs | 1 + src/System.CommandLine/IdentifierSymbol.cs | 8 ++++-- .../Invocation/ICommandHandler.cs | 1 + .../Invocation/IInvocationResult.cs | 1 + .../Invocation/InvocationContext.cs | 1 + .../Invocation/InvocationMiddleware.cs | 1 + .../Invocation/MiddlewareOrder.cs | 1 + src/System.CommandLine/Option.cs | 16 ++++++++++- src/System.CommandLine/OptionExtensions.cs | 27 ++++++++++++++++++- src/System.CommandLine/Option{T}.cs | 1 + .../Parsing/ArgumentResult.cs | 1 + .../Parsing/CommandLineStringSplitter.cs | 1 + .../Parsing/CommandResult.cs | 1 + .../Parsing/OptionResult.cs | 1 + .../Parsing/ParseArgument{T}.cs | 1 + src/System.CommandLine/Parsing/ParseError.cs | 1 + src/System.CommandLine/Parsing/ParseResult.cs | 1 + .../Parsing/ParseResultExtensions.cs | 4 +++ src/System.CommandLine/Parsing/Parser.cs | 1 + .../Parsing/ParserExtensions.cs | 5 ++++ .../Parsing/ResponseFileHandling.cs | 1 + src/System.CommandLine/Parsing/Token.cs | 2 ++ src/System.CommandLine/Parsing/TokenType.cs | 1 + .../Parsing/TokenizeError.cs | 1 + .../Parsing/ValidateSymbolResult.cs | 1 + src/System.CommandLine/RootCommand.cs | 1 + src/System.CommandLine/Symbol.cs | 5 ++++ 54 files changed, 217 insertions(+), 9 deletions(-) diff --git a/src/System.CommandLine/Argument.cs b/src/System.CommandLine/Argument.cs index 8cdce978a8..8c8ccf7c09 100644 --- a/src/System.CommandLine/Argument.cs +++ b/src/System.CommandLine/Argument.cs @@ -12,6 +12,8 @@ namespace System.CommandLine /// /// A symbol defining a value that can be passed on the command line to a command or option. /// + /// Command-line syntax overview + /// How to define commands, options, and arguments public abstract class Argument : Symbol, IValueDescriptor { private Func? _defaultValueFactory; @@ -23,6 +25,7 @@ public abstract class Argument : Symbol, IValueDescriptor /// /// Initializes a new instance of the Argument class. /// + /// How to define commands, options, and arguments protected Argument() { } @@ -32,6 +35,7 @@ protected Argument() /// /// The name of the argument. /// The description of the argument, shown in help. + /// How to define commands, options, and arguments protected Argument(string? name = null, string? description = null) { Name = name!; @@ -41,8 +45,9 @@ protected Argument(string? name = null, string? description = null) internal HashSet? AllowedValues { get; private set; } /// - /// Gets or sets the arity of the argument. + /// Gets or sets the arity of the argument. /// + /// How to define commands, options, and arguments public ArgumentArity Arity { get @@ -63,6 +68,7 @@ public ArgumentArity Arity /// /// The name used in help output to describe the argument. /// + /// How to customize help public string? HelpName { get; set; } internal TryConvertArgument? ConvertArguments @@ -83,6 +89,7 @@ internal TryConvertArgument? ConvertArguments /// /// Gets or sets the that the argument token(s) will be converted to. /// + /// How to define commands, options, and arguments public abstract Type ValueType { get; } private protected override string DefaultName @@ -111,13 +118,15 @@ private protected override string DefaultName /// to provide custom errors based on user input. /// /// The delegate to validate the parsed argument. + /// How to bind arguments to handlers - Custom validation and binding public void AddValidator(ValidateSymbolResult validate) => Validators.Add(validate); /// /// Gets the default value for the argument. /// /// Returns the default value for the argument, if defined. Null otherwise. - public object? GetDefaultValue() + /// How to define commands, options, and arguments + public object? GetDefaultValue() { return GetDefaultValue(new ArgumentResult(this, null)); } @@ -136,6 +145,7 @@ private protected override string DefaultName /// Sets the default value for the argument. /// /// The default value for the argument. + /// How to define commands, options, and arguments public void SetDefaultValue(object? value) { SetDefaultValueFactory(() => value); @@ -146,6 +156,7 @@ public void SetDefaultValue(object? value) /// /// The delegate to invoke to return the default value. /// Thrown when is null. + /// How to define commands, options, and arguments public void SetDefaultValueFactory(Func getDefaultValue) { if (getDefaultValue is null) @@ -161,6 +172,7 @@ public void SetDefaultValueFactory(Func getDefaultValue) /// /// The delegate to invoke to return the default value. /// In this overload, the is provided to the delegate. + /// How to define commands, options, and arguments public void SetDefaultValueFactory(Func getDefaultValue) { _defaultValueFactory = getDefaultValue ?? throw new ArgumentNullException(nameof(getDefaultValue)); @@ -169,6 +181,7 @@ public void SetDefaultValueFactory(Func getDefaultValue /// /// Specifies if a default value is defined for the argument. /// + /// How to define commands, options, and arguments public bool HasDefaultValue => _defaultValueFactory is not null; internal virtual bool HasCustomParser => false; diff --git a/src/System.CommandLine/ArgumentArity.cs b/src/System.CommandLine/ArgumentArity.cs index c0153fc86e..ef0230e24c 100644 --- a/src/System.CommandLine/ArgumentArity.cs +++ b/src/System.CommandLine/ArgumentArity.cs @@ -9,10 +9,11 @@ namespace System.CommandLine { /// - /// Defines the arity of an option or argument. + /// Defines the arity of an option or argument. /// /// The arity refers to the number of values that can be passed on the command line. /// + /// Command-line syntax overview [DebuggerDisplay("\\{{" + nameof(MinimumNumberOfValues) + "},{" + nameof(MaximumNumberOfValues) + "}\\}")] public readonly struct ArgumentArity : IEquatable { @@ -25,6 +26,7 @@ namespace System.CommandLine /// 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. + /// Command-line syntax overview public ArgumentArity(int minimumNumberOfValues, int maximumNumberOfValues) { if (minimumNumberOfValues < 0) @@ -50,11 +52,13 @@ public ArgumentArity(int minimumNumberOfValues, int maximumNumberOfValues) /// /// Gets the minimum number of values required for an argument. /// + /// Command-line syntax overview public int MinimumNumberOfValues { get; } /// /// Gets the maximum number of values allowed for an argument. /// + /// Command-line syntax overview public int MaximumNumberOfValues { get; } internal bool IsNonDefault { get; } @@ -119,26 +123,31 @@ public override int GetHashCode() /// /// An arity that does not allow any values. /// + /// Command-line syntax overview public static ArgumentArity Zero => new(0, 0); /// /// An arity that may have one value, but no more than one. /// + /// Command-line syntax overview public static ArgumentArity ZeroOrOne => new(0, 1); /// /// An arity that must have exactly one value. /// + /// Command-line syntax overview public static ArgumentArity ExactlyOne => new(1, 1); /// /// An arity that may have multiple values. /// + /// Command-line syntax overview public static ArgumentArity ZeroOrMore => new(0, MaximumArity); /// /// An arity that must have at least one value. /// + /// Command-line syntax overview public static ArgumentArity OneOrMore => new(1, MaximumArity); internal static ArgumentArity Default(Type type, Argument argument, ParentNode? firstParent) diff --git a/src/System.CommandLine/ArgumentExtensions.cs b/src/System.CommandLine/ArgumentExtensions.cs index 3d153dd346..247fdb0b91 100644 --- a/src/System.CommandLine/ArgumentExtensions.cs +++ b/src/System.CommandLine/ArgumentExtensions.cs @@ -11,6 +11,8 @@ namespace System.CommandLine /// /// Provides extension methods for . /// + /// Command-line syntax overview + /// How to define commands, options, and arguments public static class ArgumentExtensions { /// @@ -20,6 +22,7 @@ public static class ArgumentExtensions /// The argument for which to add completions. /// The completions to add. /// The configured argument. + /// Tab completion public static TArgument AddCompletions( this TArgument argument, params string[] values) @@ -37,6 +40,7 @@ public static TArgument AddCompletions( /// The argument for which to add completions. /// A that will be called to provide completions. /// The option being extended. + /// Tab completion public static TArgument AddCompletions( this TArgument argument, Func> complete) @@ -54,6 +58,7 @@ public static TArgument AddCompletions( /// The argument for which to add completions. /// A that will be called to provide completions. /// The configured argument. + /// Tab completion public static TArgument AddCompletions( this TArgument argument, CompletionDelegate complete) @@ -71,6 +76,8 @@ public static TArgument AddCompletions( /// The values that are allowed for the argument. /// The type of the argument. /// The configured argument. + /// How to define commands, options, and arguments + /// Tab completion public static TArgument FromAmong( this TArgument argument, params string[] values) @@ -87,6 +94,7 @@ public static TArgument FromAmong( /// /// The argument to configure. /// The configured argument. + /// How to bind arguments to handlers public static Argument ExistingOnly(this Argument argument) { argument.AddValidator(Validate.FileExists); @@ -98,6 +106,7 @@ public static Argument ExistingOnly(this Argument argument) /// /// The argument to configure. /// The configured argument. + /// How to bind arguments to handlers public static Argument ExistingOnly(this Argument argument) { argument.AddValidator(Validate.DirectoryExists); @@ -109,6 +118,7 @@ public static Argument ExistingOnly(this Argument /// /// The argument to configure. /// The configured argument. + /// How to bind arguments to handlers public static Argument ExistingOnly(this Argument argument) { argument.AddValidator(Validate.FileOrDirectoryExists); @@ -120,6 +130,7 @@ public static Argument ExistingOnly(this Argument /// The argument to configure. /// The configured argument. + /// How to bind arguments to handlers public static Argument ExistingOnly(this Argument argument) where T : IEnumerable { @@ -144,6 +155,7 @@ public static Argument ExistingOnly(this Argument argument) /// /// The argument to configure. /// The configured argument. + /// How to bind arguments to handlers public static TArgument LegalFilePathsOnly( this TArgument argument) where TArgument : Argument @@ -176,6 +188,7 @@ public static TArgument LegalFilePathsOnly( /// A parse error will result, for example, if file path separators are found in the parsed value. /// The argument to configure. /// The configured argument. + /// How to bind arguments to handlers public static TArgument LegalFileNamesOnly( this TArgument argument) where TArgument : Argument @@ -206,6 +219,7 @@ public static TArgument LegalFileNamesOnly( /// The argument to use to parse the command line input. /// 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. + /// Command-line syntax overview - Directives public static ParseResult Parse( this Argument argument, string commandLine) => @@ -217,6 +231,7 @@ public static ParseResult Parse( /// The argument to use to parse the command line input. /// The string arguments to parse. /// A parse result describing the outcome of the parse operation. + /// Command-line syntax overview - Directives public static ParseResult Parse( this Argument argument, string[] args) => diff --git a/src/System.CommandLine/Argument{T}.cs b/src/System.CommandLine/Argument{T}.cs index 1746281d69..cffc54b5ee 100644 --- a/src/System.CommandLine/Argument{T}.cs +++ b/src/System.CommandLine/Argument{T}.cs @@ -14,6 +14,7 @@ public class Argument : Argument, IValueDescriptor /// /// Initializes a new instance of the Argument class. /// + /// How to define commands, options, and arguments public Argument() { } @@ -32,6 +33,7 @@ public Argument( /// The delegate to invoke to return the default value. /// The description of the argument, shown in help. /// Thrown when is null. + /// How to define commands, options, and arguments public Argument( string name, Func getDefaultValue, @@ -50,6 +52,7 @@ public Argument( /// /// The delegate to invoke to return the default value. /// Thrown when is null. + /// How to define commands, options, and arguments public Argument(Func getDefaultValue) : this() { if (getDefaultValue is null) @@ -68,6 +71,7 @@ public Argument(Func getDefaultValue) : this() /// to use the result as default value. /// The description of the argument, shown in help. /// Thrown when is null. + /// How to define commands, options, and arguments public Argument( string? name, ParseArgument parse, @@ -108,6 +112,7 @@ public Argument( /// /// A custom argument parser. /// to use the result as default value. + /// How to define commands, options, and arguments public Argument(ParseArgument parse, bool isDefault = false) : this(null!, parse, isDefault) { } diff --git a/src/System.CommandLine/Binding/BinderBase{T}.cs b/src/System.CommandLine/Binding/BinderBase{T}.cs index 31dcb1baac..c10e3654ed 100644 --- a/src/System.CommandLine/Binding/BinderBase{T}.cs +++ b/src/System.CommandLine/Binding/BinderBase{T}.cs @@ -4,6 +4,8 @@ /// Supports binding of custom types. /// /// The type to be bound. +/// Model binding more than 16 options and arguments + public abstract class BinderBase : IValueDescriptor, IValueSource @@ -13,6 +15,7 @@ public abstract class BinderBase : /// /// /// + /// Model binding more than 16 options and arguments protected abstract T GetBoundValue(BindingContext bindingContext); string IValueDescriptor.ValueName => GetType().Name; diff --git a/src/System.CommandLine/Binding/BindingContext.cs b/src/System.CommandLine/Binding/BindingContext.cs index 7f2cbb5ca3..c3efef50e4 100644 --- a/src/System.CommandLine/Binding/BindingContext.cs +++ b/src/System.CommandLine/Binding/BindingContext.cs @@ -14,6 +14,8 @@ namespace System.CommandLine.Binding /// /// Creates object instances based on command line parser results, injected services, and other value sources. /// + /// How to bind arguments to handlers + public sealed class BindingContext : IServiceProvider { private HelpBuilder? _helpBuilder; diff --git a/src/System.CommandLine/Binding/BoundValue.cs b/src/System.CommandLine/Binding/BoundValue.cs index ba50a45a4e..f50a574111 100644 --- a/src/System.CommandLine/Binding/BoundValue.cs +++ b/src/System.CommandLine/Binding/BoundValue.cs @@ -6,6 +6,7 @@ namespace System.CommandLine.Binding /// /// A value created by binding command line input. /// + /// How to bind arguments to handlers public readonly struct BoundValue { internal BoundValue( diff --git a/src/System.CommandLine/Builder/CommandLineBuilder.cs b/src/System.CommandLine/Builder/CommandLineBuilder.cs index 959fcecdca..c7da738420 100644 --- a/src/System.CommandLine/Builder/CommandLineBuilder.cs +++ b/src/System.CommandLine/Builder/CommandLineBuilder.cs @@ -12,6 +12,7 @@ namespace System.CommandLine.Builder /// /// Enables composition of command line configurations. /// + /// How to customize help public class CommandLineBuilder { // for every generic type with type argument being struct JIT needs to compile a dedicated version diff --git a/src/System.CommandLine/Command.cs b/src/System.CommandLine/Command.cs index 4f9cfc7cd8..43f6b0f133 100644 --- a/src/System.CommandLine/Command.cs +++ b/src/System.CommandLine/Command.cs @@ -18,6 +18,7 @@ namespace System.CommandLine /// for simple applications that only have one action. For example, dotnet run /// uses run as the command. /// + /// Command-line syntax overview public class Command : IdentifierSymbol, IEnumerable { private List? _arguments; @@ -30,6 +31,7 @@ public class Command : IdentifierSymbol, IEnumerable /// /// The name of the command. /// The description of the command, shown in help. + /// Command-line syntax overview public Command(string name, string? description = null) : base(name, description) { } @@ -37,6 +39,7 @@ public Command(string name, string? description = null) : base(name, description /// /// Gets the child symbols. /// + /// Command-line syntax overview public IEnumerable Children { get @@ -55,6 +58,7 @@ public IEnumerable Children /// /// Represents all of the arguments for the command. /// + /// Command-line syntax overview public IReadOnlyList Arguments => _arguments is not null ? _arguments : Array.Empty(); internal bool HasArguments => _arguments is not null; @@ -62,11 +66,13 @@ public IEnumerable Children /// /// Represents all of the options for the command, including global options that have been applied to any of the command's ancestors. /// + /// Command-line syntax overview public IReadOnlyList