working on a new API for commands that creates less redundant code

[bcoe]

I'm working on a new API for commands that makes writing them less redundant:

• commands now accept two functions a builder for describing command-specific help, and a handler that will get argv passed to it.
• the concept of global options is being introduced, to eliminate the need for setting the same option over and over again on each command.
• positional argument parsing: foo <foo> [bar] is being introduced.
• Builder/Handler Pattern.

The definition of commands has now been split into a:

• builder: which is used to describe a command.
• handler: which is used to handle a command when it is invoked.

var argv = require('yargs')
  .command(
    'push', 
    'push to a URL', 
    function (yargs) {
      // build command specific yargs object.
    },
    function (argv) {
      // handle the parsed options.
   })
   .help('help')
  .argv

• Providing a Module For Commands

I would like to make it so that you could also provide a module to command, you would write a module like this:

exports.builder = function (yargs) {
  return yargs.option('f', {})
}
exports.handler = function (argv) {
// do something with argv.
}

And would provide it to a command like this:

yargs.command('foo', 'my awesome foo command', require('./test-module')).

I think this is pretty killer, and splitting out the builder and handler makes this possible what do you think @nexdrew?

• Global Options

You can now specify global options using .global() or the global: true shorthand on options.

These options will not be reset when passed to commands, by default help, version, are treated this way (since this is the behavior folks usually want).

• Parsing Positional Arguments

see: #363, #362

[maxrimue]

Do we really need a new dependency for that? Why not just use process.platform !== 'win32'?

[wraithan]

Big fan of the new style, looking forward to taking advantage of it in a couple little tools I've written.

Mostly it is the module style that I'll be using, will be able to more cleanly divide up my code. The globals I'll probably lean on in very simple tools and stay away from in more complex ones.

[lrlna]

I think it may be better to stick with the same structure of an example that we use above, i.e:

var argv = require('yargs')
  .command('get', 'make a get HTTP request', {
    url: {
      default: 'http://yargs.js.org/'
    }
  })
  .help()
  .argv

The change in structure might confuse people (even though you mention that this is a yargs instance), and knowing people don't always read text and skip to code, we might run into some trouble :o What do you think?

Edit: same goes for L484-487

[bcoe]

@lrlna I've updated the documentation for command modules which I think are the most elegant approach we can direct people towards.

[lrlna]

@bcoe 🆒, I like it.

[pscanf]

@bcoe a maybe-trivial clarification on the API: the intended purpose of the handler function is to kick off my command logic execution, correct?

Example:

#!/usr/bin/env node

import yargs from 'yargs';
import do_a from './do_a.js';
import do_b from './do_b.js';

yargs
  .command('do_a', 'Does A', {/* a options */}, do_a)
  .command('do_b', 'Does B', {/* b options */}, do_b);

(I ask because in the example you save in a variable the argv object, which I guess has little use at that point though)

[pluma]

Is there any way to specify the equivalent of the last argument to demand (i.e. an error message) when defining commands with positional arguments this way? The default error message is pretty meaningless for mortals.