commander 2.8.1 → 2.9.0

package/History.md

@@ -1,10 +1,15 @@
 
-2.8.1 / 2015-04-22
+2.9.0 / 2015-10-13
 ==================
 
- * Back out `support multiline description` Close #396 #397
+  * Add option `isDefault` to set default subcommand #415 @Qix-
+  * Add callback to allow filtering or post-processing of help text #434 @djulien
+  * Fix `undefined` text in help information close #414 #416 @zhiyelee
 
+2.8.1 / 2015-04-22
+==================
 
+ * Back out `support multiline description` Close #396 #397
 
 2.8.0 / 2015-04-07
 ==================

package/Readme.md

@@ -167,13 +167,15 @@ program
   .version('0.0.1')
   .command('install [name]', 'install one or more packages')
   .command('search [query]', 'search with optional query')
-  .command('list', 'list packages installed')
+  .command('list', 'list packages installed', {isDefault: true})
   .parse(process.argv);
 ```
 
 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.
+
 If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.
 
 ### `--harmony`
@@ -266,14 +268,16 @@ Examples:
 
 ```
 
-## .outputHelp()
+## .outputHelp(cb)
 
 Output help information without exiting.
+Optional callback cb allows post-processing of help text before it is displayed.
 
 If you want to display help by default (e.g. if no command was provided), you can use something like:
 
 ```js
 var program = require('commander');
+var colors = require('colors');
 
 program
   .version('0.0.1')
@@ -281,13 +285,18 @@ program
   .parse(process.argv);
 
   if (!process.argv.slice(2).length) {
-    program.outputHelp();
+    program.outputHelp(make_red);
   }
+
+function make_red(txt) {
+  return colors.red(txt); //display the help text in red on the console
+}
 ```
 
-## .help()
+## .help(cb)
 
   Output help information and exit immediately.
+  Optional callback cb allows post-processing of help text before it is displayed.
 
 ## Examples
 

package/index.js

@@ -1,4 +1,3 @@
-
 /**
  * Module dependencies.
  */
@@ -83,10 +82,10 @@ Option.prototype.is = function(arg) {
 function Command(name) {
   this.commands = [];
   this.options = [];
-  this._execs = [];
+  this._execs = {};
   this._allowUnknownOption = false;
   this._args = [];
-  this._name = name;
+  this._name = name || '';
 }
 
 /**
@@ -165,6 +164,7 @@ Command.prototype.command = function(name, desc, opts) {
     cmd.description(desc);
     this.executables = true;
     this._execs[cmd._name] = true;
+    if (opts.isDefault) this.defaultExecutable = cmd._name;
   }
 
   cmd._noHelp = !!opts.noHelp;
@@ -184,7 +184,7 @@ Command.prototype.command = function(name, desc, opts) {
 
 Command.prototype.arguments = function (desc) {
   return this.parseExpectedArgs(desc.split(/ +/));
-}
+};
 
 /**
  * Add an implicit `help [cmd]` subcommand
@@ -446,7 +446,7 @@ Command.prototype.parse = function(argv) {
   this._name = this._name || basename(argv[1], '.js');
 
   // github-style sub-commands with no sub-command
-  if (this.executables && argv.length < 3) {
+  if (this.executables && argv.length < 3 && !this.defaultExecutable) {
     // this user needs help
     argv.push('--help');
   }
@@ -461,6 +461,10 @@ Command.prototype.parse = function(argv) {
   var name = result.args[0];
   if (this._execs[name] && typeof this._execs[name] != "function") {
     return this.executeSubCommand(argv, args, parsed.unknown);
+  } else if (this.defaultExecutable) {
+    // use the default subcommand
+    args.unshift(name = this.defaultExecutable);
+    return this.executeSubCommand(argv, args, parsed.unknown);
   }
 
   return result;
@@ -544,6 +548,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
     process.exit(1);
   });
 
+  // Store the reference to the child process
   this.runningCommand = proc;
 };
 
@@ -831,7 +836,7 @@ Command.prototype.version = function(str, flags) {
  */
 
 Command.prototype.description = function(str) {
-  if (0 == arguments.length) return this._description;
+  if (0 === arguments.length) return this._description;
   this._description = str;
   return this;
 };
@@ -910,10 +915,10 @@ Command.prototype.optionHelp = function() {
 
   // Prepend the help information
   return [pad('-h, --help', width) + '  ' + 'output usage information']
-    .concat(this.options.map(function(option) {
-      return pad(option.flags, width) + '  ' + option.description;
+      .concat(this.options.map(function(option) {
+        return pad(option.flags, width) + '  ' + option.description;
       }))
-    .join('\n');
+      .join('\n');
 };
 
 /**
@@ -935,14 +940,10 @@ Command.prototype.commandHelp = function() {
 
     return [
       cmd._name
-        + (cmd._alias
-          ? '|' + cmd._alias
-          : '')
-        + (cmd.options.length
-          ? ' [options]'
-          : '')
+        + (cmd._alias ? '|' + cmd._alias : '')
+        + (cmd.options.length ? ' [options]' : '')
         + ' ' + args
-    , cmd.description()
+      , cmd.description()
     ];
   });
 
@@ -951,11 +952,12 @@ Command.prototype.commandHelp = function() {
   }, 0);
 
   return [
-      ''
+    ''
     , '  Commands:'
     , ''
     , commands.map(function(cmd) {
-      return pad(cmd[0], width) + '  ' + cmd[1];
+      var desc = cmd[1] ? '  ' + cmd[1] : '';
+      return pad(cmd[0], width) + desc;
     }).join('\n').replace(/^/gm, '    ')
     , ''
   ].join('\n');
@@ -1012,8 +1014,13 @@ Command.prototype.helpInformation = function() {
  * @api public
  */
 
-Command.prototype.outputHelp = function() {
-  process.stdout.write(this.helpInformation());
+Command.prototype.outputHelp = function(cb) {
+  if (!cb) {
+    cb = function(passthru) {
+      return passthru;
+    }
+  }
+  process.stdout.write(cb(this.helpInformation()));
   this.emit('--help');
 };
 
@@ -1023,8 +1030,8 @@ Command.prototype.outputHelp = function() {
  * @api public
  */
 
-Command.prototype.help = function() {
-  this.outputHelp();
+Command.prototype.help = function(cb) {
+  this.outputHelp(cb);
   process.exit();
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "command",
@@ -15,7 +15,7 @@
   },
   "devDependencies": {
     "should": ">= 0.0.1",
-    "sinon": ">= 1.14.1"
+    "sinon": ">=1.17.1"
   },
   "scripts": {
     "test": "make test"