CommandDotNet v5 road map

[drewburlingame]

We're working on some great additions to CommandDotNet.

Additions

• #314 enriching IConsole and extracting it to an independent package used by CommandDotNet
• #315 ReadLine functionality for a better navigation experience when entering prompts
• #316 REPL sessions will use the updated console and ReadLine functionality to provide a rich REPL experience
• [x] #352
  • [x] beta
• [x] #354
• [x] AnsiConsole support
• [x] Better prompting for missing arguments
• [x] #317
  • also supports numeric option names, so short names could be -1 -2 -3, etc.
• [x] #250
• [ ] #251

Breaking changes

With these updates, there will be a few breaking changes

• we'll take this opportunity to remove all members marked with [Obsolete]
• Token parsing has been updated to support #317. We can no longer determine if a token is an option before parsing, so...
  • TokenType.Option removed
  • TokenType.Value renamed TokenType.Argument
  • Token.OptionTokenType and OptionTokenType removed
  • behavior change: we no longer try to prevent a user from entering an option without a value because a value could look like an option. We let the context of the command determine if what is valid. Result: '-a -1' will no longer throw an error and neither will '--optionA --some-value'.
• IArgumentTypeDescriptor.Parse signature will change to support nesting descriptors. This is required to support dictionary types and other tuple types.

[drewburlingame]

Roadmap update. It's been a busy year and I find myself with less time so I'm refocusing priorities. I will not be extracting IConsole into it's own repo and developing a better ReadLine. This puts the REPL sessions on hold.

Instead, I'll keep an eye out for other packages that do this better. For example, I'm currently working on a package to integrate Spectre's IAnsiConsole into CommandDotNet. It's turning out to be pretty simple. I'm looking into an option to use their prompter for missing arguments too.

[drewburlingame]

We're having some difficulties with our documentation.

CommandDotNet

5.0.1

remove nuget package refs no longer required after move to net5.0

5.0.0

Highlights

NRT

CommandDotNet now supports Nullable reference types (NRT) when calculating Arity. Arityfor.Minimum will be 0 for NRTs.

target net5.0

CommandDotNet targets net5.0 instead of netstandard2.0. This will allow us to take advantage of new framework features. We're holding off on net6.0 at the moment because it's new enough many companies will not be able to adopt it yet. We are eager to take advantage of Source Generators though so we will likely also target net6.0 in early 2022.

Windows and Powershell conventions

Added support for Windows and Powershell conventions when using options

• backslash /help and /h for windows conventions
• single hypen -help for long names for powershell conventions

These are not enabled by default. Enable by setting AppSettings.Parser.AllowBackslashOptionPrefix and/or AppSettings.Parser.AllowSingleHyphenForLongNames = true.

Support negative numbers as arguments

Previously, negative numbers were only support when proceeded by : or =, eg --amount=-15 which meant they could only be used with options. CommandDotNet now supports --amount -15 or -15 as an operand.

IConsole

Overhaul of IConsole, now covering most the System.Console members. Converted In, Out and Error to TextReader and TextWriter to match System.Console. This includes updates to the TestConsole and AnsiTestConsole for the Spectre integration.

Overhaul of IConsole, now covering most the System.Console members. Converted In, Out and Error to TextReader and TextWriter to match System.Console. This includes updates to the TestConsole and AnsiTestConsole for the Spectre integration.

Breaking Changes in behavior

NRT support

The behavior for calculating Arity and prompting on missing arguments changes as these arguments were not previously considered nullable and so the Arity has changed to expect a minimum of 0 instead of 1

Using the UseArgumentPrompter will now work as expected when using NRTs. They will no longer prompt the user.

ArgumentArity.AllowsNone() change

This has been a confusing method. It currently evaluates as arity.Maximum == 0 but it intuitively it makes more sense as arity.Minimum == 0.

ArgumentArity.AllowsNone() has been changed to arity.Minimum == 0

ArgumentArity.RequiresNone() has been added for arity.Maximum == 0.

Breaking Changes in API

For application developers

Obsoleted cleanup

• removed DefaultMethodAttribute. Use DefaultCommandAttribute instead.
• removed appRunner.UsePrompting(...) extension method. Use .UseIPrompter and .UseArgumentPrompter instead.
• removed BooleanMode.Unknown. Use either Implicit, Explicit, or BooleanMode? instead.

Localizable Resources

Several updates to localizeable Resources. Changed a few member names for clarity and anded a several new members.

AppSettings

• Added AppSettings.Parser
• Moved IgnoreUexpectedOperands to AppSettings.Parser.IgnoreUnexpectedOperands

For middleware developers

IArgument updates

• added BooleanMode properties to help determine the Arity for an argument.
• BooleanMode will only be set for boolean arguments

IConsole updates

• added numerous members to bring closer to parity with System.Console
• removed StandardStreamReader and StandardStreamWriter
• added ForwardingTextWriter to support integrations where text forwards to another console utility, such as Spectre's AnsiConsole
• SystemConsole and TestConsole can be inherited for simpler adaptation resiliant to breakimg changes in IConsole if new members are added

DefaultSources.AppSetting.GetKeysFromConvention

Now takes AppSettings to support / and - option prefixes.

TokenType.Option removed

To support negative numbers and prefixing options with / and -, we needed more context from the command definition so determining if a token is an option or value has been moved to the command parser. Token transformation no longer distinguishes options vs values.

• TokenType.Option and TokenType.Value have merged into TokenType.Argument
• OptionTokenType and Token.OptionTokenType have been removed
• Clubbed options are no longer split during token transformation
• Option assignments are no longer separated during token transformation
• Tokenizer.TryTokenizeOption has been removed

IInvocation updates

added IsInterceptor property to distinguish between command and interceptor invocations

Obsoleted cleanup

• removed ArgumentArity.Default(Type, ...). Use ArgumentArity.Default(IArgument) instead. This is a reversal of previous direction, but the addition of IArgument.BooleanMode makes this reliable.
• removed FindOption(string alias). Use Find<Option>(string alias) instead.
• removed command.GetIgnoreUnexpectedOperands(AppSettings). Use command.IgnoreUnexpectedOperands as it now defaults from AppSettings.
• removed command.GetArgumentSeparatorStrategy(AppSettings). Use command.ArgumentSeparatorStrategy as it now defaults from AppSettings.
• removed Option.ShowInHelp. Use Option.Hidden instead. There were cases where this had meaning outside of generating help.

CommandDotNet.FluentValidations

5.0.0

remove nuget package refs no longer required after move to net5.0

Breaking Changes

Upgraded to latest FluentValidator 10.3.4 (from 8.0.0).

The ValidatorAttribute was deprecated in v8 so we dropped support for it. The assemblies containg the IArgModels will be scanned for validators if they aren't registered with a DI container.

Alternatively, you can provide a factory func via .UseFluentValidation(validatorFactory:...)

4.0.0

CommandDotNet.FluentValidation targets net5.0 instead of netstandard2.0. This will allow us to take advantage of new framework features. We're holding off on net6.0 at the moment because it's new enough many companies will not be able to adopt it yet.

CommandDotNet.Testing

4.0.1

remove nuget package refs no longer required after move to net5.0

4.0.0

target net5.0

CommandDotNet.TestTools targets net5.0 instead of netstandard2.0. This will allow us to take advantage of new framework features. We're holding off on net6.0 at the moment because it's new enough many companies will not be able to adopt it yet.

Breaking Changes

TrackingInvocation implements new IInvocation.IsInterceptor property

TestConsole updated to support new IConsole members. In, Out, and Error now implement TextReader and TextWriter. SystemConsole and TestConsole can be inherited for simpler adaptation resiliant to breakimg changes in IConsole if new members are added.

Removed Obsoleted

• Removed TestConcolse constructor containing mock paramters. Use the Mock methods instead.

All others

targets net5.0 instead of netstandard2.0. This will allow us to take advantage of new framework features. We're holding off on net6.0 at the moment because it's new enough many companies will not be able to adopt it yet.

remove nuget package refs no longer required after move to net5.0