commander 2.11.0 → 2.13.0

package/{History.md → CHANGELOG.md}

@@ -1,4 +1,40 @@
 
+2.13.0 / 2018-01-09
+==================
+
+  * Do not print default for --no-
+  * remove trailing spaces in command help
+  * Update CI's Node.js to LTS and latest version
+  * typedefs: Command and Option types added to commander namespace
+
+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
 ==================
 

package/Readme.md

@@ -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

package/index.js

@@ -59,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.
  *
@@ -155,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());
@@ -165,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);
@@ -359,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') {
@@ -381,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
@@ -541,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] });
     }
@@ -755,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;
@@ -877,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;
 };
@@ -943,8 +963,9 @@ Command.prototype.optionHelp = function() {
 
   // 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'])
+      return pad(option.flags, width) + '  ' + option.description
+        + ((option.bool != false && option.defaultValue !== undefined) ? ' (default: ' + option.defaultValue + ')' : '');
+  }).concat([pad('-h, --help', width) + '  ' + 'output usage information'])
     .join('\n');
 };
 
@@ -969,7 +990,7 @@ Command.prototype.commandHelp = function() {
       cmd._name
         + (cmd._alias ? '|' + cmd._alias : '')
         + (cmd.options.length ? ' [options]' : '')
-        + ' ' + args
+        + (args ? ' ' + args : '')
       , cmd._description
     ];
   });
@@ -984,7 +1005,7 @@ Command.prototype.commandHelp = function() {
     , ''
     , commands.map(function(cmd) {
       var desc = cmd[1] ? '  ' + cmd[1] : '';
-      return pad(cmd[0], width) + desc;
+      return (desc ? pad(cmd[0], width) : cmd[0]) + desc;
     }).join('\n').replace(/^/gm, '    ')
     , ''
   ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -14,16 +14,21 @@
     "type": "git",
     "url": "https://github.com/tj/commander.js.git"
   },
-  "devDependencies": {
-    "should": "^11.2.1",
-    "sinon": "^2.3.5"
-  },
   "scripts": {
-    "test": "make test"
+    "test": "make test && npm run test-typings",
+    "test-typings": "node_modules/typescript/bin/tsc -p tsconfig.json"
   },
   "main": "index",
   "files": [
-    "index.js"
+    "index.js",
+    "typings/index.d.ts"
   ],
-  "dependencies": {}
+  "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,306 @@
+// Type definitions for commander 2.11
+// 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>, Jules Randolph <https://github.com/sveinburne>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+declare namespace local {
+
+  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);
+  }
+
+  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 {
+
+    type Command = local.Command
+
+    type Option = local.Option
+
+    interface CommandOptions {
+        noHelp?: boolean;
+        isDefault?: boolean;
+    }
+
+    interface ParseOptionsResult {
+        args: string[];
+        unknown: string[];
+    }
+
+    interface CommanderStatic extends Command {
+        Command: typeof local.Command;
+        Option: typeof local.Option;
+        CommandOptions: CommandOptions;
+        ParseOptionsResult: ParseOptionsResult;
+    }
+
+}
+
+declare const commander: commander.CommanderStatic;
+export = commander;