feat: make positional arguments fully configurable

[bcoe]

Introduces the .positional() method, which makes positional arguments fully configurable (but wait there's more, positional arguments will also be included separately in help output):

TODO:

• make it so we default the settings demanded and array based on the command string.
• accept the argument $0 to represent a default command (so that it's more intuitive that commands can be used to handle top-level operations).
• add documentation.
• get translations for Positionals: (help wanted!). we can do this post-hoc.
• finish adding tests.

see: #541, #570, #959, etc

cc: @tkarls, @hax, @sloanlance, @iarna, etc.

[bcoe]

perhaps refactor the population of these parser options into a separate helper based on the command string, since they're also required for .positional().

[bcoe]

@jeffijoe @ruimarinho @tkarls @atian25 @popomore @matatk @sloanlance

I just took on this major refactor of how we parse commands in yargs to try to:

1. make commands first class citizens that have most of the same parsing hints as flag options.
2. make the command API a bit less confusing (by improving documentation, and adding a logical command for configuring commands .positional()).

I would love your feedback -- I'm feeling pretty excited about this update to commands.

[jeffijoe]

@bcoe very nice, great work!

[Morishiri]

Nice work :)

[zkat]

😎

[bcoe]

@popomore, @hax, @Morishiri, @zkat, @jeffijoe this work is now available on the candidate release of yargs@10.0.0; I would love some help testing (since this is one of the bigger overhauls to yargs' functionality in a while).

You can play with it by running:

npm i yargs@next

[matatk]

Thanks for working on this; it is looking very promising. I have two questions...

1. It seems that I cannot declare a positional argument without declaring a command. The following is invalid code. Is there a way to have positional arguments without having to declare a command?

   const argv = require('yargs')
   	.usage('$0 greeting')
   	.positional('greeting', {
   		describe: 'what you would like the program to say',
   		type: 'string'
   	})
   	.help()
   	.argv
   
   console.log(argv)

2. When argv gets returned, it comes back as an object such as { _: [ 'moo' ], version: false, help: false, '$0': 'index.js' }. When positional arguments are in use, will we be able to use their name, rather than just _ to refer to them? Being able to name the arguments would make code that uses yargs more readable. (There's an original issue along these lines that brought me here, and this was the root of it.)

[bcoe]

@matatk try this on the most recent branch (npm yargs@next):

const argv = require('./')
  .command('$0 [port]', 'start the server', (yargs) => {
    yargs
      .positional('port', {
        describe: 'port to bind on',
        default: 5000
      })
   })
   .argv

I could imagine an alias for this that looks like this:

const argv = require('./')
  .usage('$0 [port]', (yargs) => {
    yargs
      .positional('port', {
        describe: 'port to bind on',
        default: 5000
      })
   })
   .argv

I wonder if this might be overkill though -- my feeling is it's probably better to encourage people to move towards using command('$0') rather than .usage() when they're describing the properties of positional arguments.

[matatk]

@bcoe that's brill; just what I was after—super-easy to configure positional arguments for the implicit default command and I get to refer to the positional arguments by name; thanks :-).

[iarna]

@bcoe This looks great! Just be sure to xref in the docs for .usage() and I think it's fine to keep them apart. =)