parseOptions rework phase 1

[shadowspawn]

Pull Request

Rework option handling to preserve argument order and make more consistent in face of unknown options, including during Commander's own processing before dispatching to subcommands.

Problem

The previous handling of unknown options assumed that unknown options can be removed and tracked separately by assuming that they all take a value. This leads to problems particularly since the unknown option may turn out to be a plain boolean flag. This causes bugs with reordered or dropped arguments after unknown options are encountered.

Issues: #508 #962 #1032 #1039

Historical issues: #56 #75

When the undocumented .allowUnknownOption was used, the unknown options were not available from an action handler or after .parse called.

Issue: #802 #903

Solution

.parseOptions() removes the known options and splits the remaining arguments into operands (non-options) and unknown without changing the order of the remaining arguments, and without making assumptions about whether unknown options take values or are flags.

The unknown options are included along with other arguments to action handlers et al for processing by later commands.

NB: this does significantly change the value of .args after .parse() and the behaviour when the undocumented .allowUnknownOption() is used, and affects client usage of those features.

ChangeLog

Fixed

• preserve argument order in subcommands (git-style subcommands mess up argument order when using boolean flags #508 Subcommand destroys ordering of options #962 parseOptions rework phase 1 #1138)
• program.args has arguments with just top level options removed (Passing command option leaves content in args #1032 parseOptions rework phase 1 #1138)
• unknown options included in .args and action handler arguments (Get remaining arguments #802 parseOptions rework phase 1 #1138)

Changed

• Breaking .args contains command arguments with just recognised options removed (parseOptions rework phase 1 #1138)
• Breaking .parseOptions() (parseOptions rework phase 1 #1138)
  • args in returned result renamed operands and does not include anything after first unknown option
  • unknown in returned result has arguments after first unknown option including operands, not just options and values
• Breaking .on('command:*', callback) and other command events passed (changed) results from .parseOptions, i.e. operands and unknown (parseOptions rework phase 1 #1138)
• Breaking when .allowUnknownOption() used, any unknown options are included in arguments passed to command action handler (parseOptions rework phase 1 #1138)

[abetomo]

LGTM!

[shadowspawn]

Thanks @abetomo ! 👍

I'll update branches and merge with some care... 🛠