Parse rework for nested commands

[shadowspawn]

Pull Request

Going wide and trying to unify and improve behaviours at same time as adding support for nested commands.

Problem

The parsing is a collection of accumulated behaviours, making it difficult to add new features, and in particular nested commands. For example:

• action handlers and executable subcommands have individual historical behaviours
• validation of options done in action handler support rather than independent
• the parsing is scattered between multiple routines

Using the Event Emitter for internal processing is a complication and introduces possible interaction with user defined listeners in middle of internal processing.

Commander started out being flexible and leaving things to caller, but as Commander has become more structured and full featured there is an expectation that some behaviours should be included (e.g. error when subcommand not found, due to typo).

References

Commander does not support nested commands (without using git-style executables):

• Issue: nested subcommands #1 Support more than one level of subcommands #63 command with multiple words #655 Subcommands syntax and usage #764
• Related PR: Completed nested command support. #245 [WIP] Forward subcommands (action-like subcommands) #1024

Allow a non-executable to be set as the default command: #742

Implicit help command: #205 #256 #350 #892
but not when an argument: #1153

Implicit help not working for alias: #948

Built-in error when unrecognised command: #432 #1088

Help displayed for missing command: #1088

Built-in error for missing arguments: #995

Asterisk handler getting called for executable subcommands: #809

Solution

Rework parsing, big time:

• do not use events for internal command processing (still used for option processing)
• explicitly handle just one of action vs executable
• parse command independent of whether action handler attached
• recursive parsing, for nested command support
• recursive parsing, with intention top level command is less special
• treat action/executable subcommands more symmetrically
• add error and/or help for missing and unknown commands (for all subcommands, not just executable)

ChangeLog

Added

• allow a non-executable to be set as the default command (Allow a non-executable to be set as the default command #742 Parse rework for nested commands #1149)
• support nested sub-commands with action-handlers (nested subcommands #1 Subcommands syntax and usage #764 Parse rework for nested commands #1149)
• automatic implicit help command for all subcommands (not just executables) (Parse rework for nested commands #1149)
• customise implicit help command with .addHelpCommand() (Parse rework for nested commands #1149)
• Breaking display error message for unknown subcommand (running an unknown subcommand does not fail #432 Triage: detecting missing or unknown commands #1088 Parse rework for nested commands #1149)
• Breaking display help for missing subcommand (Triage: detecting missing or unknown commands #1088 Parse rework for nested commands #1149)

Changed

• Breaking display error if required argument for command is missing (The Command.prototype.parse() method has issues. #995 Parse rework for nested commands #1149)

Fixed

• only add implicit help command when it will not conflict with other arguments (about commander -h and help command #1153 Parse rework for nested commands #1149)
• do not emit command:* for executable subcommands (Using sub-command always invokes *  #809 Parse rework for nested commands #1149)
• implicit help command works with aliases (Built-in help subcommand does not work with aliased git-style commands #948 Parse rework for nested commands #1149)
• options are validated whether or not there is an action handler (Parse rework for nested commands #1149)

Removed

• parseExpectedArgs is now private (Parse rework for nested commands #1149)

Migration tips

If you use .on('command:*') or more complicated tests to detect an unrecognised subcommand, you may be able to delete the code and rely on the default behaviour.

If you use program.args or more complicated tests to detect a missing subcommand, you may be able to delete the code and rely on the default behaviour.

If you use .command('*') to add a default command, you may be be able to use isDefault:true with a normal command instead.