commander 2.7.0 → 2.9.0

package/History.md

@@ -1,5 +1,32 @@
 
-2.7.0 / 2015-03-07
+2.9.0 / 2015-10-13
+==================
+
+  * 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
+==================
+
+  * Add `process.execArg` support, execution args like `--harmony` will be passed to sub-commands #387 @DigitalIO @zhiyelee
+  * Fix bug in Git-style sub-commands #372 @zhiyelee
+  * Allow commands to be hidden from help #383 @tonylukasavage
+  * When git-style sub-commands are in use, yet none are called, display help #382 @claylo
+  * Add ability to specify arguments syntax for top-level command #258 @rrthomas
+  * Support multiline descriptions #208 @zxqfox
+
+2.7.1 / 2015-03-11
+==================
+
+ * Revert #347 (fix collisions when option and first arg have same name) which causes a bug in #367.
+
+2.7.0 / 2015-03-09
 ==================
 
  * Fix git-style bug when installed globally. Close #335 #349 @zhiyelee

package/Readme.md

@@ -31,14 +31,14 @@ program
   .version('0.0.1')
   .option('-p, --peppers', 'Add peppers')
   .option('-P, --pineapple', 'Add pineapple')
-  .option('-b, --bbq', 'Add bbq sauce')
+  .option('-b, --bbq-sauce', 'Add bbq sauce')
   .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
   .parse(process.argv);
 
 console.log('you ordered a pizza with:');
 if (program.peppers) console.log('  - peppers');
 if (program.pineapple) console.log('  - pineapple');
-if (program.bbq) console.log('  - bbq');
+if (program.bbqSauce) console.log('  - bbq');
 console.log('  - %s cheese', program.cheese);
 ```
 
@@ -132,6 +132,31 @@ program.parse(process.argv);
  An `Array` is used for the value of a variadic argument.  This applies to `program.args` as well as the argument passed
  to your action as demonstrated above.
 
+## Specify the argument syntax
+
+```js
+#!/usr/bin/env node
+
+var program = require('../');
+
+program
+  .version('0.0.1')
+  .arguments('<cmd> [env]')
+  .action(function (cmd, env) {
+     cmdValue = cmd;
+     envValue = env;
+  });
+
+program.parse(process.argv);
+
+if (typeof cmdValue === 'undefined') {
+   console.error('no command given!');
+   process.exit(1);
+}
+console.log('command:', cmdValue);
+console.log('environment:', envValue || "no environment given");
+```
+
 ## Git-style sub-commands
 
 ```js
@@ -142,14 +167,22 @@ 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`.
 
-If the program is designed to installed globally, make sure the executables have proper modes, like `755`.
+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`
+
+You can enable `--harmony` option in two ways:
+* Use `#! /usr/bin/env node --harmony` in the sub-commands scripts. Note some os version don’t support this pattern.
+* Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning sub-command process.
 
 ## Automated --help
 
@@ -235,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')
@@ -250,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 || '';
 }
 
 /**
@@ -156,7 +155,8 @@ Command.prototype.__proto__ = EventEmitter.prototype;
  * @api public
  */
 
-Command.prototype.command = function(name, desc) {
+Command.prototype.command = function(name, desc, opts) {
+  opts = opts || {};
   var args = name.split(/ +/);
   var cmd = new Command(args.shift());
 
@@ -164,8 +164,10 @@ Command.prototype.command = function(name, desc) {
     cmd.description(desc);
     this.executables = true;
     this._execs[cmd._name] = true;
+    if (opts.isDefault) this.defaultExecutable = cmd._name;
   }
 
+  cmd._noHelp = !!opts.noHelp;
   this.commands.push(cmd);
   cmd.parseExpectedArgs(args);
   cmd.parent = this;
@@ -174,6 +176,16 @@ Command.prototype.command = function(name, desc) {
   return cmd;
 };
 
+/**
+ * Define argument syntax for the top-level command.
+ *
+ * @api public
+ */
+
+Command.prototype.arguments = function (desc) {
+  return this.parseExpectedArgs(desc.split(/ +/));
+};
+
 /**
  * Add an implicit `help [cmd]` subcommand
  * which invokes `--help` for the given command.
@@ -288,8 +300,10 @@ Command.prototype.action = function(fn) {
 
     fn.apply(self, args);
   };
-  this.parent.on('action_' + this._name, listener);
-  if (this._alias) this.parent.on('action_' + this._alias, listener);
+  var parent = this.parent || this;
+  var name = parent === this ? '*' : this._name;
+  parent.on(name, listener);
+  if (this._alias) parent.on(this._alias, listener);
   return this;
 };
 
@@ -431,6 +445,12 @@ Command.prototype.parse = function(argv) {
   // guess name
   this._name = this._name || basename(argv[1], '.js');
 
+  // github-style sub-commands with no sub-command
+  if (this.executables && argv.length < 3 && !this.defaultExecutable) {
+    // this user needs help
+    argv.push('--help');
+  }
+
   // process argv
   var parsed = this.parseOptions(this.normalize(argv.slice(2)));
   var args = this.args = parsed.args;
@@ -441,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;
@@ -469,30 +493,48 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
 
   // executable
   var f = argv[1];
-  var link = readlink(f);
+  // name of the subcommand, link `pm-install`
+  var bin = basename(f, '.js') + '-' + args[0];
+
+
+  // In case of globally installed, get the base dir where executable
+  //  subcommand file should be located at
+  var baseDir
+    , link = readlink(f);
+
+  // when symbolink is relative path
   if (link !== f && link.charAt(0) !== '/') {
     link = path.join(dirname(f), link)
   }
-  var dir = dirname(link);
-  var bin = basename(f, '.js') + '-' + args[0];
+  baseDir = dirname(link);
 
   // prefer local `./<bin>` to bin in the $PATH
-  var local = path.join(dir, bin);
-  try {
-    // for versions before node v0.8 when there weren't `fs.existsSync`
-    if (fs.statSync(local).isFile()) {
-      bin = local;
-    }
-  } catch (e) {}
+  var localBin = path.join(baseDir, bin);
+
+  // whether bin file is a js script with explicit `.js` extension
+  var isExplicitJS = false;
+  if (exists(localBin + '.js')) {
+    bin = localBin + '.js';
+    isExplicitJS = true;
+  } else if (exists(localBin)) {
+    bin = localBin;
+  }
 
-  // run it
   args = args.slice(1);
 
   var proc;
   if (process.platform !== 'win32') {
-    proc = spawn(bin, args, { stdio: 'inherit', customFds: [0, 1, 2] });
+    if (isExplicitJS) {
+      args.unshift(localBin);
+      // add executable arguments to spawn
+      args = (process.execArgv || []).concat(args);
+
+      proc = spawn('node', args, { stdio: 'inherit', customFds: [0, 1, 2] });
+    } else {
+      proc = spawn(bin, args, { stdio: 'inherit', customFds: [0, 1, 2] });
+    }
   } else {
-    args.unshift(local);
+    args.unshift(localBin);
     proc = spawn(process.execPath, args, { stdio: 'inherit'});
   }
 
@@ -506,6 +548,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
     process.exit(1);
   });
 
+  // Store the reference to the child process
   this.runningCommand = proc;
 };
 
@@ -568,8 +611,8 @@ Command.prototype.parseArgs = function(args, unknown) {
 
   if (args.length) {
     name = args[0];
-    if (this.listeners('action_' + name).length) {
-      this.emit('action_' + args.shift(), args, unknown);
+    if (this.listeners(name).length) {
+      this.emit(args.shift(), args, unknown);
     } else {
       this.emit('*', args);
     }
@@ -793,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;
 };
@@ -872,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');
 };
 
 /**
@@ -888,21 +931,19 @@ Command.prototype.optionHelp = function() {
 Command.prototype.commandHelp = function() {
   if (!this.commands.length) return '';
 
-  var commands = this.commands.map(function(cmd) {
+  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]'
-          : '')
+        + (cmd._alias ? '|' + cmd._alias : '')
+        + (cmd.options.length ? ' [options]' : '')
         + ' ' + args
-    , cmd.description()
+      , cmd.description()
     ];
   });
 
@@ -911,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');
@@ -972,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');
 };
 
@@ -983,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();
 };
 
@@ -1049,3 +1096,15 @@ function humanReadableArgName(arg) {
     ? '<' + nameOutput + '>'
     : '[' + nameOutput + ']'
 }
+
+// for versions before node v0.8 when there weren't `fs.existsSync`
+function exists(file) {
+  try {
+    if (fs.statSync(file).isFile()) {
+      return true;
+    }
+  } catch (e) {
+    return false;
+  }
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "command",
@@ -14,7 +14,8 @@
     "url": "https://github.com/tj/commander.js.git"
   },
   "devDependencies": {
-    "should": ">= 0.0.1"
+    "should": ">= 0.0.1",
+    "sinon": ">=1.17.1"
   },
   "scripts": {
     "test": "make test"