Honor user defined order of commands, subcommands and options

[gabrielmaldi]

Currently, HelpBuilder sorts help items, which results in the following behavior:

Example 1

new CommandEx(new[] { "migrations", "mig" })

Commands:
  mig, migrations    Commands to manage migrations.

Example 2

new CommandEx(new[] { "health-checks", "hc" })
new CommandEx(new[] { "mini-profiler", "mp" })

mini-profiler, mp                Generates the MiniProfiler script
hc, health-checks <from> <to>    Generates the HealthChecks script [from: '0' (the initial database), to: the last migration]

---

User defined order should be respected; otherwise, the aliases (hc) can be shown before the main command (health-checks). Also, multiple commands can result in odd ordering: mini-profiler, mp and hc, health-checks (main/alias, alias/main; see Example 2).

---

For completeness:

public CommandEx(string[] aliases, string description)
    : base(aliases.First(), description)
{
    foreach (var alias in aliases.Skip(1))
    {
        AddAlias(alias);
    }
}

[dnfadmin]

All CLA requirements met.

[jonsequitur]

The convention in most command line help (at least for options) is for the short-form aliases to precede the long-form aliases, so the current ordering is deliberate.

There's been discussion though about making help easier to customize, in a way that would accommodate the desire to reorder the aliases.

@Keboo @adamhewitt627 ...thoughts?

[Keboo]

I agree, I think this is another case that needs to be handled with making configuring the help output

[gabrielmaldi]

This is how I'm handling it right now:

new CommandLineBuilder(rootCommand)
    .UseHelpBuilder(context => new HelpBuilderEx(context.Console))
    .UseDefaults()
    .Build()
    .Invoke(args);

public class HelpBuilderEx : HelpBuilder
{
    public HelpBuilderEx(
        IConsole console,
        int? columnGutter = null,
        int? indentationSize = null,
        int? maxWidth = null)
        : base(console, columnGutter, indentationSize, maxWidth)
    {
    }

    protected override string DefaultValueHint(IArgument argument, bool isSingleArgument)
    {
        if (argument is IArgumentEx argumentEx && argumentEx.DefaultValueHintFactory != null)
        {
            var surrogate = new Argument(argument.Name);
            surrogate.SetDefaultValueFactory(argumentEx.DefaultValueHintFactory);
            argument = surrogate;
        }

        return base.DefaultValueHint(argument, isSingleArgument);
    }
}

Which of course is less than ideal. I agree that it would be better to make HelpBuilder more configurable instead of just removing the call to ThenBy. In that regard, I would change this method to protected:

private IEnumerable<HelpItem> GetOptionHelpItems(IIdentifierSymbol symbol)
{
    var rawAliases = symbol
                     .Aliases
                     .Select(r => r.SplitPrefix())
                     .OrderBy(r => r.prefix, StringComparer.OrdinalIgnoreCase)
                     .GroupBy(t => t.alias)
                     .Select(t => t.First())
                     .Select(t => $"{t.prefix}{t.alias}");

And extract this bit (rawAliases) into a new protected method so it can be overridden. I would be happy to submit a new PR and close this one.

[KalleOlaviNiemitalo]

Is this needed after #2073?

CliCommand and CliOption now have both public string Name { get; } and public ICollection<string> Aliases { get; }, and help displays Name before Aliases:

command-line-api/src/System.CommandLine/Help/HelpBuilder.Default.cs

Lines 90 to 98 in e26fc94

	var aliases = aliasSet is null
	? new [] { symbol.Name }
	: new [] {symbol.Name}.Concat(aliasSet)
	.Select(r => r.SplitPrefix())
	.OrderBy(r => r.Prefix, StringComparer.OrdinalIgnoreCase)
	.ThenBy(r => r.Alias, StringComparer.OrdinalIgnoreCase)
	.GroupBy(t => t.Alias)
	.Select(t => t.First())
	.Select(t => $"{t.Prefix}{t.Alias}");

Even if you still need to preserve the order of aliases, you cannot do that just by making HelpBuilder sort the aliases, because AliasSet stores them to HashSet<string> _aliases, which already does not preserve order.