cmdln - npm Package Versions

[Backward incompatible change] Change the signature of a <cmdln>.fini method from:

  MyCLI.prototype.fini = function fini(subcmd, cb) {

to:

  MyCLI.prototype.fini = function fini(subcmd, err, cb) {

where err is the error returned by the invocation of the CLI. This allows a fini method to use or deal with that error, if necessary.

Update cmdln.main(...) to support a showErr boolean as an option or on the <Cmdln> instance. For example, this could allow a fini method to suppress printing an error. By default errors from subcommands are shown (i.e. the same current behaviour by default).

Make sure to carry over all properties set on a sub-subcommand handler class to the implicit handler function created. E.g., myCustomFlag in the following:

  Git.prototype.do_remote = GitRemote;
  Git.prototype.do_remote.myCustomFlag = true;

Support sub-subcommands (like git remote add|rename|remove ...) simply by setting do_<subcmd> to another Cmdln subclass for the subcommand. Basically like this:

  function GitRemote(parent) {
      this.parent = parent;
      Cmdln.call(this, {
          name: 'git remote',
          // ...
      });
  }
  util.inherits(GitRemote, Cmdln);

  GitRemote.prototype.emptyLine = function (cb) {
      // ... implement `git remote`
  };

  GitRemote.prototype.do_add = function (subcmd, opts, args, cb) {
      // ... implment `git remote add`
      cb();
  };


  function Git() {
      Cmdln.call(this, {
          name: 'git',
          // ...
      });
  }
  util.inherits(Git, Cmdln);

  Git.prototype.do_remote = GitRemote;

See examples/fauxgit.js for a more complete example.

Improvements to the cmdln.main() function:

• The call signature has changed to take a Cmdln subclass instance rather than the constructor function. This allows one to initialize it with parameters if necessary. The new signature is:

    function main(<cli-instance>, <options>)
  

• Added the options.showErrStack option to force the printing of the full error stack for a shown exit error. Instead, <cli>.showErrStack can be set true to show the full stack on error. One can use the latter to control error stack printing in the <cli>.init() method, e.g. from a --verbose option or an envvar (see this test command for an example).

• The default handling of NoCommandError, i.e. calling the CLI with no subcommand, has changed to not show an error string (a la git, brew and others). The new options.showNoCommandErr option was added. Set it to true to get the old behaviour.

Note on backward compatibility: If the old call signature is used, then cmdln.main() will function as before. However, please upgrade to the new form. From this:

  cmdln.main(CLI, argv, options);  # old

to this:

  var cli = new CLI();
  cmdln.main(cli, {argv: argv, ...other options...});  # new

Add <Cmdln>.fini(...) hook method run after a subcommand handler -- to complement <Cmdln>.init(...).

Reduce the npm package size (drop tests, examples, build tools, etc.)

Add <Cmdln>.handlerFromSubcmd(<subcmd>) hook. For example this could allow a user's Cmdln subclass to lookup attributes on the handler functions during <Cmdln>.init().

Don't process.exit(0) in cmdln.main for success to allow open listeners to continue.

Add a Cmdln.emptyLine hook that is called when no argv is given, i.e. when your command is called with no args:

  $ mycmd

The default behaviour (as before) is to print help output. A change in default behaviour is that this will now exit non-zero. If you want different behaviour, then override emptyLine() in your Cmdln subclass.

Improve the cmdln.main convenience function's printing of error messages. An options.showCode has been added to allow printing error instances' code attribute, if defined. E.g., with this usage:

  cmdln.main(MyCmd, process.argv, {showCode: true});

You get this output for errors (in this example the error is an unknown subcommand):

  $ node mycmd.js bogus
  mycmd bogus: error (UnknownCommand): unknown command: "bogus"