commander 2.10.0 → 2.12.2

package/{History.md → CHANGELOG.md}

@@ -1,6 +1,51 @@
 
+2.12.2 / 2017-11-28
+==================
+
+  * fix: typings are not shipped
+
+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

package/Readme.md

@@ -6,7 +6,7 @@
 [![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/)
 
 
@@ -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
 
@@ -285,9 +304,9 @@ program
   .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
@@ -349,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;
 };
 
@@ -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
@@ -513,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) !== '/') {
@@ -542,7 +559,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
       // 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] });
     }
@@ -551,6 +568,14 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
     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") {
@@ -624,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);
@@ -700,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];
@@ -709,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;
     }
@@ -748,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;
@@ -833,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);
   });
@@ -870,6 +895,8 @@ Command.prototype.alias = function(alias) {
 
   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;
 };
@@ -898,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;
 };
 
 /**
@@ -932,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');
 };
 
 /**
@@ -1013,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,6 +1,6 @@
 {
   "name": "commander",
-  "version": "2.10.0",
+  "version": "2.12.2",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -14,21 +14,21 @@
     "type": "git",
     "url": "https://github.com/tj/commander.js.git"
   },
-  "devDependencies": {
-    "should": ">= 0.0.1 <9.0.0",
-    "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"
+    "index.js",
+    "typings/index.d.ts"
   ],
-  "dependencies": {
-    "graceful-readlink": ">= 1.0.0"
-  }
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^7.0.48",
+    "should": "^11.2.1",
+    "sinon": "^2.4.1",
+    "typescript": "^2.6.2"
+  },
+  "typings": "typings/index.d.ts"
 }

package/typings/index.d.ts

@@ -0,0 +1,295 @@
+// Project: https://github.com/visionmedia/commander.js
+// Definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>
+
+declare class Option {
+    flags: string;
+    required: boolean;
+    optional: boolean;
+    bool: boolean;
+    short?: string;
+    long: string;
+    description: string;
+
+    /**
+     * Initialize a new `Option` with the given `flags` and `description`.
+     *
+     * @param {string} flags
+     * @param {string} [description]
+     */
+    constructor(flags: string, description?: string);
+}
+
+declare class Command extends NodeJS.EventEmitter {
+    [key: string]: any;
+
+    args: string[];
+
+    /**
+     * Initialize a new `Command`.
+     *
+     * @param {string} [name]
+     */
+    constructor(name?: string);
+
+    /**
+     * Set the program version to `str`.
+     *
+     * This method auto-registers the "-V, --version" flag
+     * which will print the version number when passed.
+     *
+     * @param {string} str
+     * @param {string} [flags]
+     * @returns {Command} for chaining
+     */
+    version(str: string, flags?: string): Command;
+
+    /**
+     * Add command `name`.
+     *
+     * The `.action()` callback is invoked when the
+     * command `name` is specified via __ARGV__,
+     * and the remaining arguments are applied to the
+     * function for access.
+     *
+     * When the `name` is "*" an un-matched command
+     * will be passed as the first arg, followed by
+     * the rest of __ARGV__ remaining.
+     *
+     * @example
+     *      program
+     *        .version('0.0.1')
+     *        .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')
+     *
+     *      program
+     *        .command('setup')
+     *        .description('run remote setup commands')
+     *        .action(function() {
+     *          console.log('setup');
+     *        });
+     *
+     *      program
+     *        .command('exec <cmd>')
+     *        .description('run the given remote command')
+     *        .action(function(cmd) {
+     *          console.log('exec "%s"', cmd);
+     *        });
+     *
+     *      program
+     *        .command('teardown <dir> [otherDirs...]')
+     *        .description('run teardown commands')
+     *        .action(function(dir, otherDirs) {
+     *          console.log('dir "%s"', dir);
+     *          if (otherDirs) {
+     *            otherDirs.forEach(function (oDir) {
+     *              console.log('dir "%s"', oDir);
+     *            });
+     *          }
+     *        });
+     *
+     *      program
+     *        .command('*')
+     *        .description('deploy the given env')
+     *        .action(function(env) {
+     *          console.log('deploying "%s"', env);
+     *        });
+     *
+     *      program.parse(process.argv);
+     *
+     * @param {string} name
+     * @param {string} [desc] for git-style sub-commands
+     * @param {CommandOptions} [opts] command options
+     * @returns {Command} the new command
+     */
+    command(name: string, desc?: string, opts?: commander.CommandOptions): Command;
+
+    /**
+     * Define argument syntax for the top-level command.
+     *
+     * @param {string} desc
+     * @returns {Command} for chaining
+     */
+    arguments(desc: string): Command;
+
+    /**
+     * Parse expected `args`.
+     *
+     * For example `["[type]"]` becomes `[{ required: false, name: 'type' }]`.
+     *
+     * @param {string[]} args
+     * @returns {Command} for chaining
+     */
+    parseExpectedArgs(args: string[]): Command;
+    /**
+     * Register callback `fn` for the command.
+     *
+     * @example
+     *      program
+     *        .command('help')
+     *        .description('display verbose help')
+     *        .action(function() {
+     *           // output help here
+     *        });
+     *
+     * @param {(...args: any[]) => void} fn
+     * @returns {Command} for chaining
+     */
+    action(fn: (...args: any[]) => void): Command;
+
+    /**
+     * Define option with `flags`, `description` and optional
+     * coercion `fn`.
+     *
+     * The `flags` string should contain both the short and long flags,
+     * separated by comma, a pipe or space. The following are all valid
+     * all will output this way when `--help` is used.
+     *
+     *    "-p, --pepper"
+     *    "-p|--pepper"
+     *    "-p --pepper"
+     *
+     * @example
+     *     // simple boolean defaulting to false
+     *     program.option('-p, --pepper', 'add pepper');
+     *
+     *     --pepper
+     *     program.pepper
+     *     // => Boolean
+     *
+     *     // simple boolean defaulting to true
+     *     program.option('-C, --no-cheese', 'remove cheese');
+     *
+     *     program.cheese
+     *     // => true
+     *
+     *     --no-cheese
+     *     program.cheese
+     *     // => false
+     *
+     *     // required argument
+     *     program.option('-C, --chdir <path>', 'change the working directory');
+     *
+     *     --chdir /tmp
+     *     program.chdir
+     *     // => "/tmp"
+     *
+     *     // optional argument
+     *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+     *
+     * @param {string} flags
+     * @param {string} [description]
+     * @param {((arg1: any, arg2: any) => void) | RegExp} [fn] function or default
+     * @param {*} [defaultValue]
+     * @returns {Command} for chaining
+     */
+    option(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command;
+    option(flags: string, description?: string, defaultValue?: any): Command;
+
+    /**
+     * Allow unknown options on the command line.
+     *
+     * @param {boolean} [arg] if `true` or omitted, no error will be thrown for unknown options.
+     * @returns {Command} for chaining
+     */
+    allowUnknownOption(arg?: boolean): Command;
+
+    /**
+     * Parse `argv`, settings options and invoking commands when defined.
+     *
+     * @param {string[]} argv
+     * @returns {Command} for chaining
+     */
+    parse(argv: string[]): Command;
+
+    /**
+     * Parse options from `argv` returning `argv` void of these options.
+     *
+     * @param {string[]} argv
+     * @returns {ParseOptionsResult}
+     */
+    parseOptions(argv: string[]): commander.ParseOptionsResult;
+
+    /**
+     * Return an object containing options as key-value pairs
+     *
+     * @returns {{[key: string]: string}}
+     */
+    opts(): { [key: string]: string };
+
+    /**
+     * Set the description to `str`.
+     *
+     * @param {string} str
+     * @return {(Command | string)}
+     */
+    description(str: string): Command;
+    description(): string;
+
+    /**
+     * Set an alias for the command.
+     *
+     * @param {string} alias
+     * @return {(Command | string)}
+     */
+    alias(alias: string): Command;
+    alias(): string;
+
+    /**
+     * Set or get the command usage.
+     *
+     * @param {string} str
+     * @return {(Command | string)}
+     */
+    usage(str: string): Command;
+    usage(): string;
+
+    /**
+     * Set the name of the command.
+     *
+     * @param {string} str
+     * @return {Command}
+     */
+    name(str: string): Command;
+
+    /**
+     * Get the name of the command.
+     *
+     * @return {string}
+     */
+    name(): string;
+
+    /**
+     * Output help information for this command.
+     *
+     * @param {(str: string) => string} [cb] 
+     */
+    outputHelp(cb?: (str: string) => string): void;
+
+    /** Output help information and exit. */
+    help(): void;
+}
+
+declare namespace commander {
+
+    interface CommandOptions {
+        noHelp?: boolean;
+        isDefault?: boolean;
+    }
+
+    interface ParseOptionsResult {
+        args: string[];
+        unknown: string[];
+    }
+
+    interface CommanderStatic extends Command {
+        Command: typeof Command;
+        Option: typeof Option;
+        CommandOptions: CommandOptions;
+        ParseOptionsResult: ParseOptionsResult;
+    }
+
+}
+
+declare const commander: commander.CommanderStatic;
+export = commander;