Adds sort to command usage help output

[trevorlinton]

When showing the usage (if no command is available) the order of commands isn't sorted, this might be a undesirable and could be put into a config setting, but I'd like to see the tolerance to default to sorted rather than as-defined.

[bcoe]

@trevorlinton the nice thing about not applying sorting, is folks can control the ordering of commands by definition order.

my concern with this change is it would break a lot of downstream consumers of yargs, and would need to be a breaking change; and I feel we'd need to then introduce an API method that allowed people to control the sorting of commands (as they'd now always be sorted, and folks might be picky).

@boneskull any opinion?

[trevorlinton]

can I add it as an optional config (disabled by default?) the particular issue I'm under is I don't have control with the timing when new commands are registered, so the ordering can at times be random.

[bcoe]

@trevorlinton that's an interesting requirement; I'd be open to this, I've been chatting with @cspotcode about adding the ability to configure compiler settings with a flag like .yargsConfig which would pass config to the yargs-parser; what if we allowed certain yargs settings in the non-parser layer to be configured with this too, e.g., sort-commands which defaults to false.

FYI, I think you can use String.localeCompare() to perform the sortinng.

[bcoe]

@trevorlinton see #1262, I'm comfortable with sort-commands being a configuration option that can be passed to yargs via parserConfiguration.

[trevorlinton]

@evocateur @bcoe I added in the sort-commands based on the work done in #1262 is there a common branch I can do a PR/rebase into on yargs? otherwise I'm going to be pulling in all the commits/changes from #1262 and our merges become very similar (or, alternatively, merge #1262 first and leave this be until then).

[bcoe]

@trevorlinton I'll get #1262 landed ASAP, and then you can rebase against master 👍

[evocateur]

LGTM pending rebase

[bcoe]

@trevorlinton thanks for your patience, if you don't mind rebasing I'll give this a final review 👍

one note, we'll want to make sure we document the new API method configuration options appropriately.

[trevorlinton]

@bcoe I've rebased on master, you can review the file changes, it may be prudent to squash this merge considering all of the conflicts/rebasing that occurred by merging in a unmerged PR and diverging. I've added some notes in api.md on the config option, but I'm not sure how we should document this properly, I'm hoping what's there is good enough or now.

[bcoe]

This is looking great 👍 just a few minor requests for edits.

Thank you for taking this work on.

[bcoe]

let's make this:

"parserConfiguration() allows you to configure advanced yargs features:"

[trevorlinton]

done.

[bcoe]

let's change this to:

obj accepts the following configuration options:

[trevorlinton]

done.

[trevorlinton]

@bcoe I've made the changes to the docs requested.

[bcoe]

@trevorlinton 👍 thank you; I'm excited that we now have a way to configure edge-case output options for folks (just like we do with the parser).

[bcoe]

@trevorlinton please try:

npm i yargs@next

and let me know if it does the trick for you.

[bcoe]

this is now available in yargs@13.1.0.