More consistent way of adding command arguments

[shadowspawn]

Pull Request

Problem

The syntax for adding command arguments which have help descriptions is quite different from the rest of the API, and arguments and options are added quite differently although they could be similar. (Prompted by discussion about offering .choices() for arguments in #1458)

Related: #1458 #1467 #1471

Solution

This builds on PR #1467. With positive feedback about the new method in #1471., switching over "normal" way of adding an argument in README and examples and tests from .arguments() to .argument().

• .argument(name, description) method
  • c.f. .option(flags, description)
• addArgument(arg) method for future expansion
  • c.f. .addOption(opt)
• deprecate cmd.description(cmdDescription, argsDescription)

ChangeLog

• added: cmd.argument(name, description) for adding command-arguments
• changed: deprecate second parameter of cmd.description(desc, argDescriptions) for adding argument descriptions (removed from README)
• changed: Help .visibleArguments() returns array of Argument

[shadowspawn]

Allowing no brackets around argument name and defaulting to required option, but not documenting for now.

i.e. foo treated same as <foo>

[shadowspawn]

Not documenting .addArgument() in README yet, as not interesting until has some extra behaviours (like .choices()!).

[shadowspawn]

Might be done! (Edit: no, was not done!) I am going to have a look at the Argument data property names, but they are consistent with Option and Command. Having a plain data property name like required means we can't have a method called required() in the future (well, without it being a breaking change).

Mentioned property names in #1467 (comment)

Update: keep properties private for now (Like Command.)
Update 2: change back, closely follow example of Option

[shadowspawn]

Also I will have another look at the README introduction of the arguments, as the "inline" form with command-name <arg1> [arg2] is the only one that can be used when declaring stand-alone executables from the parent command. .argument() does not replace this. (Not all the patterns work for program vs subcommand, and action handler vs stand-alone executable.)

[shadowspawn]

I have had another go at the README to try and tidily cover the multiple approaches to specifying command-arguments.

[abetomo]

8️⃣