add choices to arguments

[Niryo]

is it possible to have choices for arguments?

createCommand('pickColor').arguments('<color>'); //color choices: ['red', 'blue', 'green']

[shadowspawn]

No, choices for command-arguments are not supported.

(But an alternative is to make color an option instead of an argument.)

[Niryo]

Is it intentionally not supported or is it in the backlog? If it's in the backlog we can discuss about the api and maybe i could create a PR

[shadowspawn]

At this stage it is a new suggestion.

I see .choices() as just one of the things that option-arguments support that command-arguments do not: default value, custom option processing (coerce), and choices.

Do any other CLI frameworks support any of these for command-arguments?

[shadowspawn]

I had a quick look at argparse, and it configures command-arguments and option-arguments the same way:

• https://docs.python.org/3/library/argparse.html#the-add-argument-method
• https://docs.python.org/3/library/argparse.html#choices

Looks like also support in yargs via positional, which supports choices:

• https://github.com/yargs/yargs/blob/master/docs/api.md#positionalkey-opt

This is very different to how Commander currently works!

[shadowspawn]

Previous related issue: #971

[Niryo]

My first intuition was that arguments should be treated the same as options in terms of validation and api, so it will be quite natural to have addArguments(new Argument().choices()), same as options, don't you think?

btw, just as a side note, you need to be aware that commander becomes (I would say even already) the top of his kind (at least among js tools), so soon you will not be able to check other solutions for understanding the standard, commander is on the point where it can define the standard:)

[shadowspawn]

I think following the option syntax may work pretty well, allowing description in a more consistent way, and defaults and coercion, and the extensible syntax to allow choices. Specifying the arguments with .arguments() or along with the command name in .command() still works fine as a shortcut for the simple cases. Reworking examples from the README:

// arguments and description
oldProgram
  .arguments('<username> [password]')
  .description('test command', {
    username: 'user to login',
    password: 'password for user, if required'
  });
newProgram
  .description('test command')
  .argument('<username>', 'user to login')
  .argument('[password]', 'password for user, if required');

// default
cmdUsingOpt
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');
cmdUsingArg
  .argument('[cheese-type]', 'add the specified type of cheese', 'blue')

// coerce
cmdUsingOpt
  .option('-f, --float <number>', 'float argument', parseFloat)
cmdUsingArg
  .argument('<number>', 'float argument', parseFloat)

// choices
cmdUsingOpt
  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']));
cmdUsingArg
  .addArgument(new CommandArgument('<drink-size>', 'drink size').choices(['small', 'medium', 'large']));

[Niryo]

what is/are the correct test suite for testing the arguments? I want to duplicate all the relevant tests and make sure they are passing with the new syntax

[shadowspawn]

Be warned: I am not sure yet whether there is enough value to make what I suspect will be a lot of code changes. I have not seen many requests for the features this would add, so will be watching to see if this issue gets many 👍 .

You may want to open a PR with some code to show and discuss, but just warning you not to expect it will be accepted.

Is there a particular area you are interested in experimenting with first? You did ask about choices, but that does need quite a lot of new syntax with what we are considering, so you may have to start elsewhere.

There are base argument tests in:

• command.action.test.js
• command.variadic.test.js

But there are related tests in lots of other files, including the help related tests and the new .allowExcessArguments(). Command-arguments and options are the base building blocks of the CLI.

[Niryo]

sure, I know you have the right to reject the pr:)
anyways, I think the value is not only the features themselves, the biggest value I see is making the API more concise. I am new to this lib, and it was quite un-intuitive for me to understand the difference between arguments and options, in term of API. after learning the Options api, I would expect to have the same things for arguments. also, I have a complex program with many sub-commands, and it's nice to have common arguments, just like I have common options (many commands use the same options and same arguments, like fileName argument). sadly, with the current implementation of arguments I can't have common arguments. Adding Choices and all the other sweet stuff is a nice bonus also:)

So I think I will start by introducing the new API without adding new capabilities like choices, and later I'll them.

[shadowspawn]

.argument() added in #1467 #1490 #1497 for Commander v8

[shadowspawn]

The support for defaults and custom parsing with .argument() has landed on release/8.x, which makes .choices() a simpler addition.

[shadowspawn]

Would you like to have first go at this @Niryo ?

[Niryo]

@shadowspawn sure. i'll notice here when I am starting to work on it (until then if anyone see this and want to start working on it, you are welcome to do so)

[shadowspawn]

I have made a start on this.

[shadowspawn]

Released in Commander v8.