commander 2.9.0 → 2.12.1

package/{History.md → CHANGELOG.md}

@@ -1,4 +1,64 @@
 
+2.12.1 / 2017-11-23
+==================
+
+  * Move @types/node to dev dependency
+
+2.12.0 / 2017-11-22
+==================
+
+  * add attributeName() method to Option objects
+  * Documentation updated for options with --no prefix
+  * typings: `outputHelp` takes a string as the first parameter
+  * typings: use overloads
+  * feat(typings): update to match js api
+  * Print default value in option help
+  * Fix translation error
+  * Fail when using same command and alias (#491)
+  * feat(typings): add help callback
+  * fix bug when description is add after command with options (#662)
+  * Format js code
+  * Rename History.md to CHANGELOG.md (#668)
+  * feat(typings): add typings to support TypeScript (#646)
+  * use current node
+
+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
 ==================
 

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')
@@ -44,6 +44,25 @@ console.log('  - %s cheese', program.cheese);
 
  Short flags may be passed as a single arg, for example `-abc` is equivalent to `-a -b -c`. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc.
 
+Note that multi-word options starting with `--no` prefix negate the boolean value of the following word. For example, `--no-sauce` sets the value of `program.sauce` to false. 
+
+```js
+#!/usr/bin/env node
+
+/**
+ * Module dependencies.
+ */
+
+var program = require('commander');
+
+program
+  .option('--no-sauce', 'Remove sauce')
+  .parse(process.argv);
+
+console.log('you ordered a pizza');
+if (program.sauce) console.log('  with sauce');
+else console.log(' without sauce');
+```
 
 ## Coercion
 
@@ -66,7 +85,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 +110,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 +134,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 +156,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,15 +175,16 @@ 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', {isDefault: true})
@@ -226,7 +246,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');
@@ -280,13 +300,13 @@ 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(make_red);
-  }
+if (!process.argv.slice(2).length) {
+  program.outputHelp(make_red);
+}
 
 function make_red(txt) {
   return colors.red(txt); //display the help text in red on the console
@@ -304,10 +324,10 @@ function make_red(txt) {
 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]')
@@ -348,4 +368,3 @@ More Demos can be found in the [examples](https://github.com/tj/commander.js/tre
 ## License
 
 MIT
-

package/index.js

@@ -4,7 +4,6 @@
 
 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;
@@ -60,6 +59,18 @@ Option.prototype.name = function() {
     .replace('no-', '');
 };
 
+/**
+ * Return option name, in a camelcase format that can be used
+ * as a object attribute key.
+ *
+ * @return {String}
+ * @api private
+ */
+
+Option.prototype.attributeName = function() {
+  return camelcase( this.name() );
+};
+
 /**
  * Check if `arg` matches the short or long flag.
  *
@@ -156,6 +167,10 @@ Command.prototype.__proto__ = EventEmitter.prototype;
  */
 
 Command.prototype.command = function(name, desc, opts) {
+  if(typeof desc === 'object' && desc !== null){
+    opts = desc;
+    desc = null;
+  }
   opts = opts || {};
   var args = name.split(/ +/);
   var cmd = new Command(args.shift());
@@ -166,7 +181,6 @@ Command.prototype.command = function(name, desc, opts) {
     this._execs[cmd._name] = true;
     if (opts.isDefault) this.defaultExecutable = cmd._name;
   }
-
   cmd._noHelp = !!opts.noHelp;
   this.commands.push(cmd);
   cmd.parseExpectedArgs(args);
@@ -302,8 +316,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 +364,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
  */
@@ -360,7 +374,7 @@ Command.prototype.option = function(flags, description, fn, defaultValue) {
   var self = this
     , option = new Option(flags, description)
     , oname = option.name()
-    , name = camelcase(oname);
+    , name = option.attributeName();
 
   // default as 3rd arg
   if (typeof fn != 'function') {
@@ -382,7 +396,10 @@ Command.prototype.option = function(flags, description, fn, defaultValue) {
     // when --no-* we make sure default is true
     if (false == option.bool) defaultValue = true;
     // preassign only if we have a default
-    if (undefined !== defaultValue) self[name] = defaultValue;
+    if (undefined !== defaultValue) {
+      self[name] = defaultValue;
+      option.defaultValue = defaultValue;
+    }
   }
 
   // register the option
@@ -390,7 +407,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
@@ -459,11 +476,24 @@ 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(name = this.defaultExecutable);
+    args.unshift(this.defaultExecutable);
     return this.executeSubCommand(argv, args, parsed.unknown);
   }
 
@@ -500,7 +530,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) !== '/') {
@@ -525,19 +555,27 @@ 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);
 
-      proc = spawn('node', args, { stdio: 'inherit', customFds: [0, 1, 2] });
+      proc = spawn(process.argv[0], args, { stdio: 'inherit', customFds: [0, 1, 2] });
     } else {
       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") {
@@ -611,10 +649,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);
@@ -668,13 +706,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;
     }
 
@@ -687,7 +725,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];
@@ -696,10 +734,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;
     }
@@ -735,7 +773,7 @@ Command.prototype.opts = function() {
     , len = this.options.length;
 
   for (var i = 0 ; i < len; i++) {
-    var key = camelcase(this.options[i].name());
+    var key = this.options[i].attributeName();
     result[key] = key === 'version' ? this._version : this[key];
   }
   return result;
@@ -810,7 +848,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
  */
@@ -820,7 +858,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);
   });
@@ -850,8 +888,16 @@ 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;
+
+  if (alias === command._name) throw new Error('Command alias can\'t be the same as its name');
+
+  command._alias = alias;
   return this;
 };
 
@@ -879,15 +925,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;
 };
 
 /**
@@ -913,12 +961,12 @@ 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) + '  ' + option.description;
-      }))
-      .join('\n');
+  // Append the help information
+  return this.options.map(function(option) {
+      return pad(option.flags, width) + '  ' + option.description
+        + (option.defaultValue !== undefined ? ' (default: ' + option.defaultValue + ')' : '');
+  }).concat([pad('-h, --help', width) + '  ' + 'output usage information'])
+    .join('\n');
 };
 
 /**
@@ -943,7 +991,7 @@ Command.prototype.commandHelp = function() {
         + (cmd._alias ? '|' + cmd._alias : '')
         + (cmd.options.length ? ' [options]' : '')
         + ' ' + args
-      , cmd.description()
+      , cmd._description
     ];
   });
 
@@ -994,17 +1042,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');
 };
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "commander",
-  "version": "2.9.0",
+  "version": "2.12.1",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
+    "commander",
     "command",
     "option",
     "parser"
@@ -13,21 +14,20 @@
     "type": "git",
     "url": "https://github.com/tj/commander.js.git"
   },
-  "devDependencies": {
-    "should": ">= 0.0.1",
-    "sinon": ">=1.17.1"
-  },
   "scripts": {
-    "test": "make test"
+    "test": "make test && npm run test-typings",
+    "test-typings": "node_modules/typescript/bin/tsc -p tsconfig.json"
   },
   "main": "index",
-  "engines": {
-    "node": ">= 0.6.x"
-  },
   "files": [
     "index.js"
   ],
-  "dependencies": {
-    "graceful-readlink": ">= 1.0.0"
-  }
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^7.0.48",
+    "should": "^11.2.1",
+    "sinon": "^2.4.1",
+    "typescript": "^2.6.1"
+  },
+  "typings": "typings/index.d.ts"
 }