commander 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). (Format adopted after v3.0.0.)
+
+## [3.0.1] (2019-08-30)
+
+### Added
+
+* .name and .usage to README ([#1010])
+* Table of Contents to README ([#1010])
+* TypeScript definition for `executableFile` in CommandOptions ([#1028])
+
+### Changed
+
+* consistently use `const` rather than `var` in README ([#1026])
+
+### Fixed
+
+* help for sub commands with custom executableFile ([#1018])
+
 3.0.0 / 2019-08-08
 =================
 
@@ -47,20 +70,6 @@ program
   .command('action2', { noHelp: true }) // Correct
 ```
 
- [#599]: https://github.com/tj/commander.js/issues/599
- [#611]: https://github.com/tj/commander.js/issues/611
- [#697]: https://github.com/tj/commander.js/issues/697
- [#795]: https://github.com/tj/commander.js/issues/795
- [#915]: https://github.com/tj/commander.js/issues/915
- [#938]: https://github.com/tj/commander.js/issues/938
- [#963]: https://github.com/tj/commander.js/issues/963
- [#974]: https://github.com/tj/commander.js/issues/974
- [#980]: https://github.com/tj/commander.js/issues/980
- [#987]: https://github.com/tj/commander.js/issues/987
- [#990]: https://github.com/tj/commander.js/issues/990
- [#991]: https://github.com/tj/commander.js/issues/991
- [#999]: https://github.com/tj/commander.js/issues/999
-
 3.0.0-0 Prerelease / 2019-07-28
 ==============================
 
@@ -473,3 +482,24 @@ program
 ==================
 
   * Initial release
+
+[#599]: https://github.com/tj/commander.js/issues/599
+[#611]: https://github.com/tj/commander.js/issues/611
+[#697]: https://github.com/tj/commander.js/issues/697
+[#795]: https://github.com/tj/commander.js/issues/795
+[#915]: https://github.com/tj/commander.js/issues/915
+[#938]: https://github.com/tj/commander.js/issues/938
+[#963]: https://github.com/tj/commander.js/issues/963
+[#974]: https://github.com/tj/commander.js/issues/974
+[#980]: https://github.com/tj/commander.js/issues/980
+[#987]: https://github.com/tj/commander.js/issues/987
+[#990]: https://github.com/tj/commander.js/issues/990
+[#991]: https://github.com/tj/commander.js/issues/991
+[#999]: https://github.com/tj/commander.js/issues/999
+[#1010]: https://github.com/tj/commander.js/pull/1010
+[#1018]: https://github.com/tj/commander.js/pull/1018
+[#1026]: https://github.com/tj/commander.js/pull/1026
+[#1028]: https://github.com/tj/commander.js/pull/1028
+
+[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[3.0.1]: https://github.com/tj/commander.js/compare/v3.0.0...v3.0.1

package/Readme.md

@@ -7,9 +7,39 @@
 
 The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).
 
+- [Commander.js](#commanderjs)
+  - [Installation](#installation)
+  - [Declaring _program_ variable](#declaring-program-variable)
+  - [Options](#options)
+    - [Common option types, boolean and value](#common-option-types-boolean-and-value)
+    - [Default option value](#default-option-value)
+    - [Other option types, negatable boolean and flag|value](#other-option-types-negatable-boolean-and-flagvalue)
+    - [Custom option processing](#custom-option-processing)
+    - [Version option](#version-option)
+  - [Commands](#commands)
+    - [Specify the argument syntax](#specify-the-argument-syntax)
+    - [Action handler (sub)commands](#action-handler-subcommands)
+    - [Git-style executable (sub)commands](#git-style-executable-subcommands)
+  - [Automated --help](#automated---help)
+    - [Custom help](#custom-help)
+    - [.usage and .name](#usage-and-name)
+    - [.outputHelp(cb)](#outputhelpcb)
+    - [.helpOption(flags, description)](#helpoptionflags-description)
+    - [.help(cb)](#helpcb)
+  - [Custom event listeners](#custom-event-listeners)
+  - [Bits and pieces](#bits-and-pieces)
+    - [TypeScript](#typescript)
+    - [Node options such as `--harmony`](#node-options-such-as---harmony)
+    - [Node debugging](#node-debugging)
+  - [Examples](#examples)
+  - [License](#license)
+  - [Support](#support)
+
 ## Installation
 
-    $ npm install commander
+```bash
+npm install commander
+```
 
 ## Declaring _program_ variable
 
@@ -29,7 +59,6 @@ For larger programs which may use commander in multiple ways, including unit tes
  program.version('0.0.1');
  ```
 
-
 ## Options
 
 Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space.
@@ -119,7 +148,7 @@ console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
 ```
 
 ```bash
-$ pizza-options 
+$ pizza-options
 You ordered a pizza with sauce and mozzarella cheese
 $ pizza-options --sauce
 error: unknown option '--sauce'
@@ -155,7 +184,7 @@ add cheese type mozzarella
 
 ### Custom option processing
 
-You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the 
+You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the
 previous value for the option. It returns the new value for the option.
 
 This allows you to coerce the option value to the desired type, or accumulate values, or do entirely custom processing.
@@ -259,9 +288,8 @@ program
 
 You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.
 
-
 ```js
-var program = require('commander');
+const program = require('commander');
 
 program
   .version('0.1.0')
@@ -285,7 +313,7 @@ console.log('environment:', envValue || "no environment given");
  append `...` to the argument name. For example:
 
 ```js
-var program = require('commander');
+const program = require('commander');
 
 program
   .version('0.1.0')
@@ -311,7 +339,7 @@ The action handler gets passed a parameter for each argument you declared, and o
 command object itself. This command argument has the values for the command-specific options added as properties.
 
 ```js
-var program = require('commander');
+const program = require('commander');
 
 program
   .command('rm <dir>')
@@ -337,7 +365,7 @@ You handle the options for an executable (sub)command in the executable, and don
 
 ```js
 // file: ./examples/pm
-var program = require('commander');
+const program = require('commander');
 
 program
   .version('0.1.0')
@@ -357,7 +385,7 @@ If the program is designed to be installed globally, make sure the executables h
 
  The help information is auto-generated based on the information commander already knows about your program, so the following `--help` info is for free:
 
-```  
+```bash
 $ ./examples/pizza --help
 Usage: pizza [options]
 
@@ -373,7 +401,7 @@ Options:
   -h, --help           output usage information
 ```
 
-## Custom help
+### Custom help
 
  You can display arbitrary `-h, --help` information
  by listening for "--help". Commander will automatically
@@ -385,11 +413,7 @@ Options:
 ```js
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('commander');
+const program = require('commander');
 
 program
   .version('0.1.0')
@@ -414,7 +438,7 @@ console.log('stuff');
 
 Yields the following help output when `node script-name.js -h` or `node script-name.js --help` are run:
 
-```
+```Text
 Usage: custom-help [options]
 
 Options:
@@ -429,7 +453,24 @@ Examples:
   $ custom-help -h
 ```
 
-## .outputHelp(cb)
+### .usage and .name
+
+These allow you to customise the usage description in the first line of the help. The name is otherwise
+deduced from the (full) program arguments. Given:
+
+```js
+program
+  .name("my-command")
+  .usage("[global options] command")
+```
+
+The help will start with:
+
+```Text
+Usage: my-command [global options] command
+```
+
+### .outputHelp(cb)
 
 Output help information without exiting.
 Optional callback cb allows post-processing of help text before it is displayed.
@@ -437,8 +478,8 @@ 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');
+const program = require('commander');
+const colors = require('colors');
 
 program
   .version('0.1.0')
@@ -454,7 +495,7 @@ function make_red(txt) {
 }
 ```
 
-## .helpOption(flags, description)
+### .helpOption(flags, description)
 
   Override the default help flags and description.
 
@@ -463,13 +504,13 @@ program
   .helpOption('-e, --HELP', 'read more information');
 ```
 
-## .help(cb)
+### .help(cb)
 
   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
@@ -504,8 +545,9 @@ node -r ts-node/register pm.ts
 ### Node options such as `--harmony`
 
 You can enable `--harmony` option in two ways:
-* Use `#! /usr/bin/env node --harmony` in the sub-commands scripts. (Note Windows does not support this pattern.)
-* Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning sub-command process.
+
+- Use `#! /usr/bin/env node --harmony` in the sub-commands scripts. (Note Windows does not support this pattern.)
+- Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning sub-command process.
 
 ### Node debugging
 
@@ -515,7 +557,7 @@ the inspector port is incremented by 1 for the spawned subcommand.
 ## Examples
 
 ```js
-var program = require('commander');
+const program = require('commander');
 
 program
   .version('0.1.0')
@@ -528,7 +570,7 @@ program
   .description('run setup commands for all envs')
   .option("-s, --setup_mode [mode]", "Which setup mode to use")
   .action(function(env, options){
-    var mode = options.setup_mode || "normal";
+    const mode = options.setup_mode || "normal";
     env = env || 'all';
     console.log('setup for %s env(s) with %s mode', env, mode);
   });

package/index.js

@@ -458,6 +458,14 @@ Command.prototype.parse = function(argv) {
 
   var result = this.parseArgs(this.args, parsed.unknown);
 
+  if (args[0] === 'help' && args.length === 1) this.help();
+
+  // <cmd> --help
+  if (args[0] === 'help') {
+    args[0] = args[1];
+    args[1] = this._helpLongFlag;
+  }
+
   // executable sub-commands
   // (Debugging note for future: args[0] is not right if an action has been called)
   var name = result.args[0];
@@ -511,13 +519,6 @@ Command.prototype.executeSubCommand = function(argv, args, unknown, executableFi
   args = args.concat(unknown);
 
   if (!args.length) this.help();
-  if (args[0] === 'help' && args.length === 1) this.help();
-
-  // <cmd> --help
-  if (args[0] === 'help') {
-    args[0] = args[1];
-    args[1] = this._helpLongFlag;
-  }
 
   var isExplicitJS = false; // Whether to use node to launch "executable"
 
@@ -1258,7 +1259,7 @@ function outputHelpIfNecessary(cmd, options) {
 }
 
 /**
- * Takes an argument an returns its human readable equivalent for help usage.
+ * Takes an argument and returns its human readable equivalent for help usage.
  *
  * @param {Object} arg
  * @return {String}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -26,11 +26,11 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@types/node": "^12.6.2",
-    "eslint": "^6.0.1",
+    "@types/node": "^12.7.2",
+    "eslint": "^6.1.0",
     "should": "^13.2.3",
-    "sinon": "^7.3.2",
-    "standard": "^13.0.1",
+    "sinon": "^7.4.1",
+    "standard": "^13.1.0",
     "ts-node": "^8.3.0",
     "typescript": "^3.5.3"
   },

package/typings/index.d.ts

@@ -279,6 +279,7 @@ declare namespace commander {
     interface CommandOptions {
         noHelp?: boolean;
         isDefault?: boolean;
+        executableFile?: string;
     }
 
     interface ParseOptionsResult {