commander 2.8.0 → 2.11.0

package/History.md

@@ -1,4 +1,53 @@
 
+2.11.0 / 2017-07-03
+==================
+
+  * Fix help section order and padding (#652)
+  * feature: support for signals to subcommands (#632)
+  * Fixed #37, --help should not display first (#447)
+  * Fix translation errors. (#570)
+  * Add package-lock.json
+  * Remove engines
+  * Upgrade package version
+  * Prefix events to prevent conflicts between commands and options (#494)
+  * Removing dependency on graceful-readlink
+  * Support setting name in #name function and make it chainable
+  * Add .vscode directory to .gitignore (Visual Studio Code metadata)
+  * Updated link to ruby commander in readme files
+
+2.10.0 / 2017-06-19
+==================
+
+  * Update .travis.yml. drop support for older node.js versions.
+  * Fix require arguments in README.md
+  * On SemVer you do not start from 0.0.1
+  * Add missing semi colon in readme
+  * Add save param to npm install
+  * node v6 travis test
+  * Update Readme_zh-CN.md
+  * Allow literal '--' to be passed-through as an argument
+  * Test subcommand alias help
+  * link build badge to master branch
+  * Support the alias of Git style sub-command
+  * added keyword commander for better search result on npm
+  * Fix Sub-Subcommands
+  * test node.js stable
+  * Fixes TypeError when a command has an option called `--description`
+  * Update README.md to make it beginner friendly and elaborate on the difference between angled and square brackets.
+  * Add chinese Readme file
+
+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
 ==================
 

package/Readme.md

@@ -1,18 +1,18 @@
 # Commander.js
 
 
-[![Build Status](https://api.travis-ci.org/tj/commander.js.svg)](http://travis-ci.org/tj/commander.js)
+[![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)
 [![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/tj/commander).  
+  The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).  
   [API documentation](http://tj.github.com/commander.js/)
 
 
 ## Installation
 
-    $ npm install commander
+    $ npm install commander --save
 
 ## Option parsing
 
@@ -28,7 +28,7 @@
 var program = require('commander');
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .option('-p, --peppers', 'Add peppers')
   .option('-P, --pineapple', 'Add pineapple')
   .option('-b, --bbq-sauce', 'Add bbq sauce')
@@ -66,7 +66,7 @@ function increaseVerbosity(v, total) {
 }
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .usage('[options] <file ...>')
   .option('-i, --integer <n>', 'An integer argument', parseInt)
   .option('-f, --float <n>', 'A float argument', parseFloat)
@@ -91,7 +91,7 @@ console.log(' args: %j', program.args);
 ## Regular Expression
 ```js
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .option('-s --size <size>', 'Pizza size', /^(large|medium|small)$/i, 'medium')
   .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i)
   .parse(process.argv);
@@ -115,7 +115,7 @@ console.log(' drink: %j', program.drink);
 var program = require('commander');
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .command('rmdir <dir> [otherDirs...]')
   .action(function (dir, otherDirs) {
     console.log('rmdir %s', dir);
@@ -137,10 +137,10 @@ program.parse(process.argv);
 ```js
 #!/usr/bin/env node
 
-var program = require('../');
+var program = require('commander');
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .arguments('<cmd> [env]')
   .action(function (cmd, env) {
      cmdValue = cmd;
@@ -156,24 +156,27 @@ if (typeof cmdValue === 'undefined') {
 console.log('command:', cmdValue);
 console.log('environment:', envValue || "no environment given");
 ```
+Angled brackets (e.g. `<cmd>`) indicate required input. Square brackets (e.g. `[env]`) indicate optional input.
 
 ## Git-style sub-commands
 
 ```js
 // file: ./examples/pm
-var program = require('..');
+var program = require('commander');
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .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`
@@ -200,8 +203,7 @@ You can enable `--harmony` option in two ways:
      -p, --peppers        Add peppers
      -P, --pineapple      Add pineapple
      -b, --bbq            Add bbq sauce
-     -c, --cheese <type>  Add the specified type
-                          of cheese [marble]
+     -c, --cheese <type>  Add the specified type of cheese [marble]
      -C, --no-cheese      You do not want any cheese
 
 ```
@@ -225,7 +227,7 @@ You can enable `--harmony` option in two ways:
 var program = require('commander');
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .option('-f, --foo', 'enable some foo')
   .option('-b, --bar', 'enable some bar')
   .option('-B, --baz', 'enable some baz');
@@ -267,28 +269,35 @@ 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')
+  .version('0.1.0')
   .command('getstream [url]', 'get stream URL')
   .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
 
@@ -296,10 +305,10 @@ program
 var program = require('commander');
 
 program
-  .version('0.0.1')
+  .version('0.1.0')
   .option('-C, --chdir <path>', 'change the working directory')
   .option('-c, --config <path>', 'set config path. defaults to ./deploy.conf')
-  .option('-T, --no-tests', 'ignore test hook')
+  .option('-T, --no-tests', 'ignore test hook');
 
 program
   .command('setup [env]')
@@ -340,4 +349,3 @@ More Demos can be found in the [examples](https://github.com/tj/commander.js/tre
 ## License
 
 MIT
-

package/index.js

@@ -1,11 +1,9 @@
-
 /**
  * Module dependencies.
  */
 
 var EventEmitter = require('events').EventEmitter;
 var spawn = require('child_process').spawn;
-var readlink = require('graceful-readlink').readlinkSync;
 var path = require('path');
 var dirname = path.dirname;
 var basename = path.basename;
@@ -83,10 +81,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 +163,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 +183,7 @@ Command.prototype.command = function(name, desc, opts) {
 
 Command.prototype.arguments = function (desc) {
   return this.parseExpectedArgs(desc.split(/ +/));
-}
+};
 
 /**
  * Add an implicit `help [cmd]` subcommand
@@ -302,8 +301,8 @@ Command.prototype.action = function(fn) {
   };
   var parent = this.parent || this;
   var name = parent === this ? '*' : this._name;
-  parent.on(name, listener);
-  if (this._alias) parent.on(this._alias, listener);
+  parent.on('command:' + name, listener);
+  if (this._alias) parent.on('command:' + this._alias, listener);
   return this;
 };
 
@@ -350,8 +349,8 @@ Command.prototype.action = function(fn) {
  *
  * @param {String} flags
  * @param {String} description
- * @param {Function|Mixed} fn or default
- * @param {Mixed} defaultValue
+ * @param {Function|*} [fn] or default
+ * @param {*} [defaultValue]
  * @return {Command} for chaining
  * @api public
  */
@@ -390,7 +389,7 @@ Command.prototype.option = function(flags, description, fn, defaultValue) {
 
   // when it's passed assign the value
   // and conditionally invoke the callback
-  this.on(oname, function(val) {
+  this.on('option:' + oname, function(val) {
     // coercion
     if (null !== val && fn) val = fn(val, undefined === self[name]
       ? defaultValue
@@ -446,7 +445,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');
   }
@@ -459,8 +458,25 @@ Command.prototype.parse = function(argv) {
 
   // executable sub-commands
   var name = result.args[0];
+
+  var aliasCommand = null;
+  // check alias of sub commands
+  if (name) {
+    aliasCommand = this.commands.filter(function(command) {
+      return command.alias() === name;
+    })[0];
+  }
+
   if (this._execs[name] && typeof this._execs[name] != "function") {
     return this.executeSubCommand(argv, args, parsed.unknown);
+  } else if (aliasCommand) {
+    // is alias of a subCommand
+    args[0] = aliasCommand._name;
+    return this.executeSubCommand(argv, args, parsed.unknown);
+  } else if (this.defaultExecutable) {
+    // use the default subcommand
+    args.unshift(this.defaultExecutable);
+    return this.executeSubCommand(argv, args, parsed.unknown);
   }
 
   return result;
@@ -496,7 +512,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
   // In case of globally installed, get the base dir where executable
   //  subcommand file should be located at
   var baseDir
-    , link = readlink(f);
+    , link = fs.lstatSync(f).isSymbolicLink() ? fs.readlinkSync(f) : f;
 
   // when symbolink is relative path
   if (link !== f && link.charAt(0) !== '/') {
@@ -521,7 +537,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
   var proc;
   if (process.platform !== 'win32') {
     if (isExplicitJS) {
-      args.unshift(localBin);
+      args.unshift(bin);
       // add executable arguments to spawn
       args = (process.execArgv || []).concat(args);
 
@@ -530,10 +546,18 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
       proc = spawn(bin, args, { stdio: 'inherit', customFds: [0, 1, 2] });
     }
   } else {
-    args.unshift(localBin);
+    args.unshift(bin);
     proc = spawn(process.execPath, args, { stdio: 'inherit'});
   }
 
+  var signals = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP'];
+  signals.forEach(function(signal) {
+    process.on(signal, function(){
+      if ((proc.killed === false) && (proc.exitCode === null)){
+        proc.kill(signal);
+      }
+    });
+  });
   proc.on('close', process.exit.bind(process));
   proc.on('error', function(err) {
     if (err.code == "ENOENT") {
@@ -544,6 +568,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
     process.exit(1);
   });
 
+  // Store the reference to the child process
   this.runningCommand = proc;
 };
 
@@ -606,10 +631,10 @@ Command.prototype.parseArgs = function(args, unknown) {
 
   if (args.length) {
     name = args[0];
-    if (this.listeners(name).length) {
-      this.emit(args.shift(), args, unknown);
+    if (this.listeners('command:' + name).length) {
+      this.emit('command:' + args.shift(), args, unknown);
     } else {
-      this.emit('*', args);
+      this.emit('command:*', args);
     }
   } else {
     outputHelpIfNecessary(this, unknown);
@@ -663,13 +688,13 @@ Command.prototype.parseOptions = function(argv) {
     arg = argv[i];
 
     // literal args after --
-    if ('--' == arg) {
-      literal = true;
+    if (literal) {
+      args.push(arg);
       continue;
     }
 
-    if (literal) {
-      args.push(arg);
+    if ('--' == arg) {
+      literal = true;
       continue;
     }
 
@@ -682,7 +707,7 @@ Command.prototype.parseOptions = function(argv) {
       if (option.required) {
         arg = argv[++i];
         if (null == arg) return this.optionMissingArgument(option);
-        this.emit(option.name(), arg);
+        this.emit('option:' + option.name(), arg);
       // optional arg
       } else if (option.optional) {
         arg = argv[i+1];
@@ -691,10 +716,10 @@ Command.prototype.parseOptions = function(argv) {
         } else {
           ++i;
         }
-        this.emit(option.name(), arg);
+        this.emit('option:' + option.name(), arg);
       // bool
       } else {
-        this.emit(option.name());
+        this.emit('option:' + option.name());
       }
       continue;
     }
@@ -805,7 +830,7 @@ Command.prototype.variadicArgNotLast = function(name) {
  * which will print the version number when passed.
  *
  * @param {String} str
- * @param {String} flags
+ * @param {String} [flags]
  * @return {Command} for chaining
  * @api public
  */
@@ -815,7 +840,7 @@ Command.prototype.version = function(str, flags) {
   this._version = str;
   flags = flags || '-V, --version';
   this.option(flags, 'output the version number');
-  this.on('version', function() {
+  this.on('option:version', function() {
     process.stdout.write(str + '\n');
     process.exit(0);
   });
@@ -831,7 +856,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;
 };
@@ -845,8 +870,14 @@ Command.prototype.description = function(str) {
  */
 
 Command.prototype.alias = function(alias) {
-  if (0 == arguments.length) return this._alias;
-  this._alias = alias;
+  var command = this;
+  if(this.commands.length !== 0) {
+    command = this.commands[this.commands.length - 1]
+  }
+
+  if (arguments.length === 0) return command._alias;
+
+  command._alias = alias;
   return this;
 };
 
@@ -874,15 +905,17 @@ Command.prototype.usage = function(str) {
 };
 
 /**
- * Get the name of the command
+ * Get or set the name of the command
  *
- * @param {String} name
+ * @param {String} str
  * @return {String|Command}
  * @api public
  */
 
-Command.prototype.name = function() {
-  return this._name;
+Command.prototype.name = function(str) {
+  if (0 === arguments.length) return this._name;
+  this._name = str;
+  return this;
 };
 
 /**
@@ -908,11 +941,10 @@ Command.prototype.largestOptionLength = function() {
 Command.prototype.optionHelp = function() {
   var width = this.largestOptionLength();
 
-  // Prepend the help information
-  return [pad('-h, --help', width) + '  ' + 'output usage information']
-    .concat(this.options.map(function(option) {
-      return pad(option.flags, width) + '  ' + offset(option.description, width + 2);
-      }))
+  // Append the help information
+  return this.options.map(function(option) {
+      return pad(option.flags, width) + '  ' + option.description;
+    }).concat([pad('-h, --help', width) + '  ' + 'output usage information'])
     .join('\n');
 };
 
@@ -935,14 +967,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 +979,12 @@ Command.prototype.commandHelp = function() {
   }, 0);
 
   return [
-      ''
+    ''
     , '  Commands:'
     , ''
     , commands.map(function(cmd) {
-      return pad(cmd[0], width) + '  ' + offset(cmd[1], width + 2);
+      var desc = cmd[1] ? '  ' + cmd[1] : '';
+      return pad(cmd[0], width) + desc;
     }).join('\n').replace(/^/gm, '    ')
     , ''
   ].join('\n');
@@ -983,7 +1012,7 @@ Command.prototype.helpInformation = function() {
   }
   var usage = [
     ''
-    ,'  Usage: ' + cmdName + ' ' + offset(this.usage(), 9)
+    ,'  Usage: ' + cmdName + ' ' + this.usage()
     , ''
   ];
 
@@ -992,17 +1021,17 @@ Command.prototype.helpInformation = function() {
   if (commandHelp) cmds = [commandHelp];
 
   var options = [
-    '  Options:'
+    ''
+    , '  Options:'
     , ''
     , '' + this.optionHelp().replace(/^/gm, '    ')
     , ''
-    , ''
   ];
 
   return usage
-    .concat(cmds)
     .concat(desc)
     .concat(options)
+    .concat(cmds)
     .join('\n');
 };
 
@@ -1012,8 +1041,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 +1057,8 @@ Command.prototype.outputHelp = function() {
  * @api public
  */
 
-Command.prototype.help = function() {
-  this.outputHelp();
+Command.prototype.help = function(cb) {
+  this.outputHelp(cb);
   process.exit();
 };
 
@@ -1056,23 +1090,6 @@ function pad(str, width) {
   return str + Array(len + 1).join(' ');
 }
 
-/**
- * Prepend to each line of `str` spaced string of `offset` length.
- *
- * @param {String} str
- * @param {Number} offset
- * @param {Boolean} skipFirstLine
- * @return {String}
- * @api private
- */
-function offset(str, offset, skipFirstLine) {
-  var res = String(str || '').replace(/^/gm, pad('', offset));
-  if (!skipFirstLine) {
-    res = res.replace(/^\s+/, '');
-  }
-  return res;
-}
-
 /**
  * Output help information if necessary
  *
@@ -1087,9 +1104,6 @@ function outputHelpIfNecessary(cmd, options) {
     if (options[i] == '--help' || options[i] == '-h') {
       cmd.outputHelp();
       process.exit(0);
-
-      // used for test flow only
-      options.splice(i, 1);
     }
   }
 }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "commander",
-  "version": "2.8.0",
+  "version": "2.11.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
+    "commander",
     "command",
     "option",
     "parser"
@@ -14,20 +15,15 @@
     "url": "https://github.com/tj/commander.js.git"
   },
   "devDependencies": {
-    "should": ">= 0.0.1",
-    "sinon": ">= 1.13.0"
+    "should": "^11.2.1",
+    "sinon": "^2.3.5"
   },
   "scripts": {
     "test": "make test"
   },
   "main": "index",
-  "engines": {
-    "node": ">= 0.6.x"
-  },
   "files": [
     "index.js"
   ],
-  "dependencies": {
-    "graceful-readlink": ">= 1.0.0"
-  }
+  "dependencies": {}
 }