cmdln - npm Package Versions

errHelp fix: If the handler function for a subcmd didn't have a <func>.name (i.e. it was anonymous), e.g. the former in:

  MyCli.prototype.do_foo = function (subcmd, opts, args, cb) {};  # anon
  MyCli.prototype.do_foo = function do_foo(subcmd, opts, args, cb) {};

then UsageError.cmdlnErrHelpFromErr would not correctly determine the subcmd name for interpolation of a {{cmd}} template var in the handlers synopses. Fix that.

[Potentially backward incompatible change] Change cmdln.main() behaviour on complete to attempt to "soft exit", by which I mean attempt to avoid calling process.exit(code), because with node.js that means std handles won't necessarily be flushed before process exit. Starting in node.js 0.12 process.exitCode was added to set the exit code without the hard exit.

Warning: A side-effect of avoiding process.exit() is that apps using cmdln.main() that have active handles open will now hang instead of exiting. To get the old behaviour, use:

  cmdln.main(cli, {finale: 'exit'});

[issue #11] Add finale and callback options to cmdln.main(<cli>, <options>). finale defines what to do when done. Valid values are:

• "softexit" (the default): set process.exitCode if the node.js version supports it (node v0.12 and above do), else call process.exit(). Note the warning above that a process with open handles (e.g. a setTimeout) will hang.
• "exit": call process.exit() which can result in std handles not being flushed
• "callback": call the given options.callback
• "none": Do nothing

[Backward incompatible change] The signature of the callback from <cmdln instance>.main(argv, callback) changed from: function (err, subcmd) # old to: function (err) # new in v4 The subcmd value was not always set and, when nested Cmdln instances were used (e.g. a multi-subcmd tool, triton instance list ...), the subcmd value was unhelpfully only the last one (list in the example). Instead, the err object (if there was an error) is assigned some cmdln state to assist with getting error details. Read on.

When err is returned from <cmdln instance>.main()'s callback, it now has properties (private props prefixed with _cmdln) that identify on what cmdln handler the error occurred. Two new functions can work with this info:

• cmdln.nameFromErr(err) will give the full command name to where the error occurred (e.g. "triton instance list" in the example above).
• cmdln.errHelpFromErr(err) will attempt to construct an appropriate "errHelp" string for the error. Read on.

The concepts of command synopses and errHelp have been added to this module. errHelp is a brief message after a printed error, giving potentially helpful info. Some examples from familiar commands (marked here with >):

      $ ls -D
      ls: illegal option -- D
  >   usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

      $ git foo
      git: 'foo' is not a git command. See 'git --help'.

  >   Did you mean this?
  >          fo

synopses are short usage statements that outline how to call a command (e.g. the SYNOPSIS section of a typical man page). There are a few changes in this module that make it easy for your tools to get these kinds of error help.

See the "errHelp and Errors" section of the README for how to use this.

Bash completion: Add completionArgtypes: CLI.prototype.do_<subcmd>.completionArgtypes = <array>;` to be able to define custom completion types for positional args.

Also update to dashdash 1.12.2 for bash completion improvements. Of note, this changes so that mytool <TAB> does not offer options as completions, mytool -<TAB> does. See dashdash's changelog.

See "examples/conan.js" for an example:

  $ alias conan="node examples/conan.js"
  $ conan completion > /usr/local/etc/bash_completion.d/conan
  $ source /usr/local/etc/bash_completion.d/conan

  $ conan crush --weapon
  bow-and-array  mattock        spear          sword
  $ conan crush --weapon spear
  King-Osric    Subotai       Thulsa-Doom   _mbsetupuser  trentm

Guard against collisions in subcmd aliases.

Change the Cmdln.prototype.dispatch call signature (the old signature is still supported) to allow calling with unprocessed argv (as before) and with process argv (i.e. with args and opts). This enables better handling of "shortcut" commands.

E.g. the triton uses this to define a top-level triton images that is a shortcut for triton image list like this:

  function do_images(subcmd, opts, args, callback) {
      // Hand off processing to 'image list' handler:
      this.handlerFromSubcmd('image').dispatch({
          subcmd: 'list',
          opts: opts,
          args: args
      }, callback);
  }

  // Help specific to the shortcut:
  do_images.help = 'A shortcut for "triton image list".';

  // Present the same options (important for Bash completion generation):
  do_images.options = require('./do_image/do_list').options;

  module.exports = do_images;