commander 2.14.0 → 2.16.0

package/CHANGELOG.md

@@ -1,4 +1,29 @@
 
+2.16.0 / 2018-06-29
+==================
+
+  * Remove Makefile and `test/run` (#821)
+  * Make 'npm test' run on Windows (#820)
+  * Add badge to display install size (#807)
+  * chore: cache node_modules (#814)
+  * chore: remove Node.js 4 (EOL), add Node.js 10 (#813)
+  * fixed typo in readme (#812)
+  * Fix types (#804)
+  * Update eslint to resolve vulnerabilities in lodash (#799)
+  * updated readme with custom event listeners. (#791)
+  * fix tests (#794)
+
+2.15.0 / 2018-03-07
+==================
+
+  * Update downloads badge to point to graph of downloads over time instead of duplicating link to npm
+  * Arguments description
+
+2.14.1 / 2018-02-07
+==================
+
+  * Fix typing of help function
+
 2.14.0 / 2018-02-05
 ==================
 

package/Readme.md

@@ -3,7 +3,8 @@
 
 [![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js)
 [![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
-[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
+[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
+[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)
 [![Join the chat at https://gitter.im/tj/commander.js](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tj/commander.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
   The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).  
@@ -232,7 +233,7 @@ program
 When `.command()` is invoked with a description argument, no `.action(callback)` should be called to handle sub-commands, otherwise there will be an error. This tells commander that you're going to use separate executables for sub-commands, much like `git(1)` and other popular tools.  
 The commander will try to search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-command`, like `pm-install`, `pm-search`.
 
-Options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the option from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified.
+Options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the subcommand from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified.
 
 If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.
 
@@ -356,6 +357,22 @@ function make_red(txt) {
   Output help information and exit immediately.
   Optional callback cb allows post-processing of help text before it is displayed.
 
+
+## Custom event listeners
+ You can execute custom actions by listening to command and option events.
+
+```js
+program.on('option:verbose', function () {
+  process.env.VERBOSE = this.verbose;
+});
+
+// error on unknown commands
+program.on('command:*', function () {
+  console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));
+  process.exit(1);
+});
+```
+
 ## Examples
 
 ```js

package/index.js

@@ -43,9 +43,9 @@ exports.Option = Option;
 
 function Option(flags, description) {
   this.flags = flags;
-  this.required = ~flags.indexOf('<');
-  this.optional = ~flags.indexOf('[');
-  this.bool = !~flags.indexOf('-no-');
+  this.required = flags.indexOf('<') >= 0;
+  this.optional = flags.indexOf('[') >= 0;
+  this.bool = flags.indexOf('-no-') === -1;
   flags = flags.split(/[ ,|]+/);
   if (flags.length > 1 && !/^[[<]/.test(flags[1])) this.short = flags.shift();
   this.long = flags.shift();
@@ -869,13 +869,15 @@ Command.prototype.version = function(str, flags) {
  * Set the description to `str`.
  *
  * @param {String} str
+ * @param {Object} argsDescription
  * @return {String|Command}
  * @api public
  */
 
-Command.prototype.description = function(str) {
+Command.prototype.description = function(str, argsDescription) {
   if (arguments.length === 0) return this._description;
   this._description = str;
+  this._argsDescription = argsDescription;
   return this;
 };
 
@@ -938,6 +940,45 @@ Command.prototype.name = function(str) {
   return this;
 };
 
+/**
+ * Return prepared commands.
+ *
+ * @return {Array}
+ * @api private
+ */
+
+Command.prototype.prepareCommands = function() {
+  return this.commands.filter(function(cmd) {
+    return !cmd._noHelp;
+  }).map(function(cmd) {
+    var args = cmd._args.map(function(arg) {
+      return humanReadableArgName(arg);
+    }).join(' ');
+
+    return [
+      cmd._name +
+        (cmd._alias ? '|' + cmd._alias : '') +
+        (cmd.options.length ? ' [options]' : '') +
+        (args ? ' ' + args : ''),
+      cmd._description
+    ];
+  });
+};
+
+/**
+ * Return the largest command length.
+ *
+ * @return {Number}
+ * @api private
+ */
+
+Command.prototype.largestCommandLength = function() {
+  var commands = this.prepareCommands();
+  return commands.reduce(function(max, command) {
+    return Math.max(max, command[0].length);
+  }, 0);
+};
+
 /**
  * Return the largest option length.
  *
@@ -946,11 +987,52 @@ Command.prototype.name = function(str) {
  */
 
 Command.prototype.largestOptionLength = function() {
-  return this.options.reduce(function(max, option) {
+  var options = [].slice.call(this.options);
+  options.push({
+    flags: '-h, --help'
+  });
+  return options.reduce(function(max, option) {
     return Math.max(max, option.flags.length);
   }, 0);
 };
 
+/**
+ * Return the largest arg length.
+ *
+ * @return {Number}
+ * @api private
+ */
+
+Command.prototype.largestArgLength = function() {
+  return this._args.reduce(function(max, arg) {
+    return Math.max(max, arg.name.length);
+  }, 0);
+};
+
+/**
+ * Return the pad width.
+ *
+ * @return {Number}
+ * @api private
+ */
+
+Command.prototype.padWidth = function() {
+  var width = this.largestOptionLength();
+  if (this._argsDescription && this._args.length) {
+    if (this.largestArgLength() > width) {
+      width = this.largestArgLength();
+    }
+  }
+
+  if (this.commands && this.commands.length) {
+    if (this.largestCommandLength() > width) {
+      width = this.largestCommandLength();
+    }
+  }
+
+  return width;
+};
+
 /**
  * Return help for options.
  *
@@ -959,7 +1041,7 @@ Command.prototype.largestOptionLength = function() {
  */
 
 Command.prototype.optionHelp = function() {
-  var width = this.largestOptionLength();
+  var width = this.padWidth();
 
   // Append the help information
   return this.options.map(function(option) {
@@ -979,28 +1061,10 @@ Command.prototype.optionHelp = function() {
 Command.prototype.commandHelp = function() {
   if (!this.commands.length) return '';
 
-  var commands = this.commands.filter(function(cmd) {
-    return !cmd._noHelp;
-  }).map(function(cmd) {
-    var args = cmd._args.map(function(arg) {
-      return humanReadableArgName(arg);
-    }).join(' ');
-
-    return [
-      cmd._name +
-        (cmd._alias ? '|' + cmd._alias : '') +
-        (cmd.options.length ? ' [options]' : '') +
-        (args ? ' ' + args : ''),
-      cmd._description
-    ];
-  });
-
-  var width = commands.reduce(function(max, command) {
-    return Math.max(max, command[0].length);
-  }, 0);
+  var commands = this.prepareCommands();
+  var width = this.padWidth();
 
   return [
-    '',
     '  Commands:',
     '',
     commands.map(function(cmd) {
@@ -1025,6 +1089,17 @@ Command.prototype.helpInformation = function() {
       '  ' + this._description,
       ''
     ];
+
+    var argsDescription = this._argsDescription;
+    if (argsDescription && this._args.length) {
+      var width = this.padWidth();
+      desc.push('  Arguments:');
+      desc.push('');
+      this._args.forEach(function(arg) {
+        desc.push('    ' + pad(arg.name, width) + '  ' + argsDescription[arg.name]);
+      });
+      desc.push('');
+    }
   }
 
   var cmdName = this._name;
@@ -1042,7 +1117,6 @@ Command.prototype.helpInformation = function() {
   if (commandHelp) cmds = [commandHelp];
 
   var options = [
-    '',
     '  Options:',
     '',
     '' + this.optionHelp().replace(/^/gm, '    '),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -16,7 +16,7 @@
   },
   "scripts": {
     "lint": "eslint index.js",
-    "test": "make test && npm run test-typings",
+    "test": "node test/run.js && npm run test-typings",
     "test-typings": "node_modules/typescript/bin/tsc -p tsconfig.json"
   },
   "main": "index",
@@ -26,12 +26,12 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@types/node": "^7.0.52",
-    "eslint": "^3.19.0",
+    "@types/node": "^7.0.66",
+    "eslint": "^4.19.1",
     "should": "^11.2.1",
     "sinon": "^2.4.1",
     "standard": "^10.0.3",
-    "typescript": "^2.7.1"
+    "typescript": "^2.9.2"
   },
   "typings": "typings/index.d.ts"
 }

package/typings/index.d.ts

@@ -218,9 +218,9 @@ declare namespace local {
     /**
      * Return an object containing options as key-value pairs
      *
-     * @returns {{[key: string]: string}}
+     * @returns {{[key: string]: any}}
      */
-    opts(): { [key: string]: string };
+    opts(): { [key: string]: any };
 
     /**
      * Set the description to `str`.
@@ -271,8 +271,11 @@ declare namespace local {
      */
     outputHelp(cb?: (str: string) => string): void;
 
-    /** Output help information and exit. */
-    help(): void;
+    /** Output help information and exit.
+     *
+     * @param {(str: string) => string} [cb]
+     */
+    help(cb?: (str: string) => string): never;
   }
 
 }