Providing name should be mandatory when creating Argument<T> and Option<T>

[adamsitnik]

Based on our discussion in #2046 we have agreed that:

• Argument<T> should require a mandatory name to be provided in every ctor:
  

  command-line-api/src/System.CommandLine/Argument{T}.cs

  Line 19 in 76437b0

  public Argument()

• Argument.HelpName needs to be removed and Argument.Name should be used instead
• Option<T> should require a mandatory name to be provided in explicit way in every ctor. Currently, when the user provides multiple aliases we are choosing the longest one and removing the prefix. It should be explicit.
  

  command-line-api/src/System.CommandLine/Option{T}.cs

  Lines 23 to 24 in 76437b0

  	public Option(
  	string[] aliases,

• Option.ArgumentHelpName needs to be removed

This issue might seem simple to implement, but I expect it to require a LOT of test changes.

[KalleOlaviNiemitalo]

Will the mandatory name of Option<T> include the / or - or -- prefix, or will that be in aliases only?

[KalleOlaviNiemitalo]

If you remove Argument.HelpName and Option.ArgumentHelpName, then how will applications hide completions from help; will they have to customize via HelpBuilder? #1976, #2038

[adamsitnik]

Will the mandatory name of Option<T> include the / or - or -- prefix, or will that be in aliases only?

Our main motivation for these changes is introducing #2052, which is going to support only lookups by the name specified in the ctor (or via Symbol.Name = value). So whatever is provided as name in explicit way, it will be used for the lookups and displaying help. Lack of prefix would be my personal recommendation, but not something enforced by the library.

[adamsitnik]

If you remove Argument.HelpName and Option.ArgumentHelpName, then how will applications hide completions from help; will they have to customize via HelpBuilder? #1976, #2038

We should definitely not encourage our users to depend on similar implicit behaviours. If it's a common need we should just introduce an API for explicitly requesting that. The question is whether it should be applied to all Symbols in given tree or just specific ones?

BTW since System.CommandLine is going to become a part of Base Class Libraries, it will be close to impossible to change existing APIs in the future. That is why we are most likely going to make the customization of help internal for .NET 8 and introduce a better way of customizing it in .NET 9.

[KalleOlaviNiemitalo]

Aha so if the app is not localised then it can construct Argument<T>(name: "input-file") and use ParseResult.GetValue<FileInfo>("input-file"); but if it is localised and constructs Argument<T>(name: Resources.InputFileArgument), then it has to call ParseResult.GetValue(Argument<T>) instead.

[KalleOlaviNiemitalo]

So whatever is provided as name in explicit way, it will be used for the lookups and displaying help. Lack of prefix would be my personal recommendation

You recommend that help should display options without a prefix?

[adamsitnik]

Aha so if the app is not localised then it can construct Argument<T>(name: "input-file") and use ParseResult.GetValue<FileInfo>("input-file"); but if it is localised and constructs Argument<T>(name: Resources.InputFileArgument), then it has to call ParseResult.GetValue(Argument<T>) instead.

Yes, but to be honest I wonder whether localization of argument/option names is a good thing. Let's say that we have following option:

Option<bool>(name: "help", aliases: new [] { "--help", "-h", "-?" })`

even if somebody translates just the name, they can't used the translated value in the provided string args[].

I am just trying to say that if I were to localize an app, I would translate only the descriptions.

[adamsitnik]

You recommend that help should display options without a prefix?

Help should display whatever was specified in explicit way, according to the author personal preferences.

[KalleOlaviNiemitalo]

The tokens that the parser recognises on the command line should not be localised because localisation makes scripts less reliable. E.g. if the command requires --format=pdf in English but --muoto=pdf in Finnish then scripts have to know all the translations or override the culture somehow.

This concern however does not apply to Argument.Name because it is not referenced in the command line. It is okay to localise for help purposes.

Likewise I'd like help to display --output=file in English but --output=tiedosto in Finnish. This does not hurt scripting as the --output token is invariant.