commander 2.15.1 → 2.18.0

package/CHANGELOG.md

@@ -1,4 +1,37 @@
 
+2.18.0 / 2018-09-07
+==================
+
+  * Standardize help output (#853)
+  * chmod 644 travis.yml (#851)
+  * add support for execute typescript subcommand via ts-node (#849)
+
+2.17.1 / 2018-08-07
+==================
+
+  * Fix bug in command emit (#844)
+
+2.17.0 / 2018-08-03
+==================
+
+  * fixed newline output after help information (#833)
+  * Fix to emit the action even without command (#778)
+  * npm update (#823)
+
+2.16.0 / 2018-06-29
+==================
+
+  * Remove Makefile and `test/run` (#821)
+  * Make 'npm test' run on Windows (#820)
+  * Add badge to display install size (#807)
+  * chore: cache node_modules (#814)
+  * chore: remove Node.js 4 (EOL), add Node.js 10 (#813)
+  * fixed typo in readme (#812)
+  * Fix types (#804)
+  * Update eslint to resolve vulnerabilities in lodash (#799)
+  * updated readme with custom event listeners. (#791)
+  * fix tests (#794)
+
 2.15.0 / 2018-03-07
 ==================
 

package/Readme.md

@@ -4,6 +4,7 @@
 [![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://npmcharts.com/compare/commander?minimal=true)
+[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=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/commander-rb/commander).  
@@ -44,7 +45,7 @@ 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. 
+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
@@ -152,7 +153,7 @@ program
   .option('-s --size <size>', 'Pizza size', /^(large|medium|small)$/i, 'medium')
   .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i)
   .parse(process.argv);
-  
+
 console.log(' size: %j', program.size);
 console.log(' drink: %j', program.drink);
 ```
@@ -232,7 +233,7 @@ program
 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.
+Options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the subcommand 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`.
 
@@ -247,22 +248,20 @@ You can enable `--harmony` option in two ways:
  The help information is auto-generated based on the information commander already knows about your program, so the following `--help` info is for free:
 
 ```  
- $ ./examples/pizza --help
-
-   Usage: pizza [options]
+$ ./examples/pizza --help
+Usage: pizza [options]
 
-   An application for pizzas ordering
+An application for pizzas ordering
 
-   Options:
-
-     -h, --help           output usage information
-     -V, --version        output the version number
-     -p, --peppers        Add peppers
-     -P, --pineapple      Add pineapple
-     -b, --bbq            Add bbq sauce
-     -c, --cheese <type>  Add the specified type of cheese [marble]
-     -C, --no-cheese      You do not want any cheese
+Options:
 
+  -h, --help           output usage information
+  -V, --version        output the version number
+  -p, --peppers        Add peppers
+  -P, --pineapple      Add pineapple
+  -b, --bbq            Add bbq sauce
+  -c, --cheese <type>  Add the specified type of cheese [marble]
+  -C, --no-cheese      You do not want any cheese
 ```
 
 ## Custom help
@@ -270,7 +269,7 @@ You can enable `--harmony` option in two ways:
  You can display arbitrary `-h, --help` information
  by listening for "--help". Commander will automatically
  exit once you are done so that the remainder of your program
- does not execute causing undesired behaviours, for example
+ does not execute causing undesired behaviors, for example
  in the following executable "stuff" will not output when
  `--help` is used.
 
@@ -293,11 +292,11 @@ program
 // node's emit() is immediate
 
 program.on('--help', function(){
-  console.log('  Examples:');
-  console.log('');
-  console.log('    $ custom-help --help');
-  console.log('    $ custom-help -h');
+  console.log('')
+  console.log('Examples:');
   console.log('');
+  console.log('  $ custom-help --help');
+  console.log('  $ custom-help -h');
 });
 
 program.parse(process.argv);
@@ -308,7 +307,6 @@ console.log('stuff');
 Yields the following help output when `node script-name.js -h` or `node script-name.js --help` are run:
 
 ```
-
 Usage: custom-help [options]
 
 Options:
@@ -323,7 +321,6 @@ Examples:
 
   $ custom-help --help
   $ custom-help -h
-
 ```
 
 ## .outputHelp(cb)
@@ -356,6 +353,22 @@ function make_red(txt) {
   Output help information and exit immediately.
   Optional callback cb allows post-processing of help text before it is displayed.
 
+
+## Custom event listeners
+ You can execute custom actions by listening to command and option events.
+
+```js
+program.on('option:verbose', function () {
+  process.env.VERBOSE = this.verbose;
+});
+
+// error on unknown commands
+program.on('command:*', function () {
+  console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));
+  process.exit(1);
+});
+```
+
 ## Examples
 
 ```js
@@ -385,11 +398,11 @@ program
   .action(function(cmd, options){
     console.log('exec "%s" using %s mode', cmd, options.exec_mode);
   }).on('--help', function() {
-    console.log('  Examples:');
-    console.log();
-    console.log('    $ deploy exec sequential');
-    console.log('    $ deploy exec async');
-    console.log();
+    console.log('');
+    console.log('Examples:');
+    console.log('');
+    console.log('  $ deploy exec sequential');
+    console.log('  $ deploy exec async');
   });
 
 program

package/index.js

@@ -43,9 +43,9 @@ exports.Option = Option;
 
 function Option(flags, description) {
   this.flags = flags;
-  this.required = ~flags.indexOf('<');
-  this.optional = ~flags.indexOf('[');
-  this.bool = !~flags.indexOf('-no-');
+  this.required = flags.indexOf('<') >= 0;
+  this.optional = flags.indexOf('[') >= 0;
+  this.bool = flags.indexOf('-no-') === -1;
   flags = flags.split(/[ ,|]+/);
   if (flags.length > 1 && !/^[[<]/.test(flags[1])) this.short = flags.shift();
   this.long = flags.shift();
@@ -523,7 +523,7 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
   // executable
   var f = argv[1];
   // name of the subcommand, link `pm-install`
-  var bin = basename(f, '.js') + '-' + args[0];
+  var bin = basename(f, path.extname(f)) + '-' + args[0];
 
   // In case of globally installed, get the base dir where executable
   //  subcommand file should be located at
@@ -539,11 +539,14 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
   // prefer local `./<bin>` to bin in the $PATH
   var localBin = path.join(baseDir, bin);
 
-  // whether bin file is a js script with explicit `.js` extension
+  // whether bin file is a js script with explicit `.js` or `.ts` extension
   var isExplicitJS = false;
   if (exists(localBin + '.js')) {
     bin = localBin + '.js';
     isExplicitJS = true;
+  } else if (exists(localBin + '.ts')) {
+    bin = localBin + '.ts';
+    isExplicitJS = true;
   } else if (exists(localBin)) {
     bin = localBin;
   }
@@ -577,9 +580,9 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) {
   proc.on('close', process.exit.bind(process));
   proc.on('error', function(err) {
     if (err.code === 'ENOENT') {
-      console.error('\n  %s(1) does not exist, try --help\n', bin);
+      console.error('%s(1) does not exist, try --help', bin);
     } else if (err.code === 'EACCES') {
-      console.error('\n  %s(1) not executable. try chmod or run with root\n', bin);
+      console.error('%s(1) not executable. try chmod or run with root', bin);
     }
     process.exit(1);
   });
@@ -660,6 +663,10 @@ Command.prototype.parseArgs = function(args, unknown) {
     if (unknown.length > 0) {
       this.unknownOption(unknown[0]);
     }
+    if (this.commands.length === 0 &&
+        this._args.filter(function(a) { return a.required }).length === 0) {
+      this.emit('command:*');
+    }
   }
 
   return this;
@@ -1065,12 +1072,12 @@ Command.prototype.commandHelp = function() {
   var width = this.padWidth();
 
   return [
-    '  Commands:',
+    'Commands:',
     '',
     commands.map(function(cmd) {
       var desc = cmd[1] ? '  ' + cmd[1] : '';
       return (desc ? pad(cmd[0], width) : cmd[0]) + desc;
-    }).join('\n').replace(/^/gm, '    '),
+    }).join('\n').replace(/^/gm, '  '),
     ''
   ].join('\n');
 };
@@ -1086,17 +1093,17 @@ Command.prototype.helpInformation = function() {
   var desc = [];
   if (this._description) {
     desc = [
-      '  ' + this._description,
+      this._description,
       ''
     ];
 
     var argsDescription = this._argsDescription;
     if (argsDescription && this._args.length) {
       var width = this.padWidth();
-      desc.push('  Arguments:');
+      desc.push('Arguments:');
       desc.push('');
       this._args.forEach(function(arg) {
-        desc.push('    ' + pad(arg.name, width) + '  ' + argsDescription[arg.name]);
+        desc.push('  ' + pad(arg.name, width) + '  ' + argsDescription[arg.name]);
       });
       desc.push('');
     }
@@ -1107,8 +1114,7 @@ Command.prototype.helpInformation = function() {
     cmdName = cmdName + '|' + this._alias;
   }
   var usage = [
-    '',
-    '  Usage: ' + cmdName + ' ' + this.usage(),
+    'Usage: ' + cmdName + ' ' + this.usage(),
     ''
   ];
 
@@ -1117,9 +1123,9 @@ Command.prototype.helpInformation = function() {
   if (commandHelp) cmds = [commandHelp];
 
   var options = [
-    '  Options:',
+    'Options:',
     '',
-    '' + this.optionHelp().replace(/^/gm, '    '),
+    '' + this.optionHelp().replace(/^/gm, '  '),
     ''
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "2.15.1",
+  "version": "2.18.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -16,8 +16,8 @@
   },
   "scripts": {
     "lint": "eslint index.js",
-    "test": "make test && npm run test-typings",
-    "test-typings": "node_modules/typescript/bin/tsc -p tsconfig.json"
+    "test": "node test/run.js && npm run test-typings",
+    "test-typings": "tsc -p tsconfig.json"
   },
   "main": "index",
   "files": [
@@ -26,12 +26,13 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@types/node": "^7.0.55",
-    "eslint": "^3.19.0",
-    "should": "^11.2.1",
-    "sinon": "^2.4.1",
-    "standard": "^10.0.3",
-    "typescript": "^2.7.2"
+    "@types/node": "^10.9.4",
+    "eslint": "^5.5.0",
+    "should": "^13.2.3",
+    "sinon": "^6.2.0",
+    "standard": "^12.0.1",
+    "ts-node": "^7.0.1",
+    "typescript": "^2.9.2"
   },
   "typings": "typings/index.d.ts"
 }

package/typings/index.d.ts

@@ -218,9 +218,9 @@ declare namespace local {
     /**
      * Return an object containing options as key-value pairs
      *
-     * @returns {{[key: string]: string}}
+     * @returns {{[key: string]: any}}
      */
-    opts(): { [key: string]: string };
+    opts(): { [key: string]: any };
 
     /**
      * Set the description to `str`.
@@ -275,7 +275,7 @@ declare namespace local {
      *
      * @param {(str: string) => string} [cb]
      */
-    help(cb?: (str: string) => string): void;
+    help(cb?: (str: string) => string): never;
   }
 
 }