Feature/examples tidy (#1271)

* Make all the examples executable

* Add shebang to all examples

* Remove use of global export as program in examples

* Move .parse onto separate line in examples

* Modify example to more closely match README

* Reference example files where available (and remove require to keep length similar)

* Remove example file which is not showing much, and covered in other files

* Remove example file which is not showing much, and covered in other files

* Add comment on point of file

Readme.md

@@ -41,7 +41,6 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
     - [Override exit handling](#override-exit-handling)
   - [Examples](#examples)
-  - [License](#license)
   - [Support](#support)
     - [Commander for enterprise](#commander-for-enterprise)
 
@@ -88,9 +87,9 @@ Options on the command line are not positional, and can be specified before or a
 
 The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line.
 
-```js
-const { program } = require('commander');
+Example file: [options-common.js](./examples/options-common.js)
 
+```js
 program
   .option('-d, --debug', 'output extra debugging')
   .option('-s, --small', 'small pizza size')
@@ -126,9 +125,9 @@ pizza details:
 
 You can specify a default value for an option which takes a value.
 
-```js
-const { program } = require('commander');
+Example file: [options-defaults.js](./examples/options-defaults.js)
 
+```js
 program
   .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');
 
@@ -152,9 +151,9 @@ Defined alone this also makes the option true by default.
 If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
 otherwise be. You can specify a default boolean value for a boolean flag and it can be overridden on command line.
 
-```js
-const { program } = require('commander');
+Example file: [options-negatable.js](./examples/options-negatable.js)
 
+```js
 program
   .option('--no-sauce', 'Remove sauce')
   .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
@@ -179,9 +178,9 @@ You ordered a pizza with no sauce and no cheese
 
 You can specify an option which functions as a flag but may also take a value (declared using square brackets).
 
-```js
-const { program } = require('commander');
+Example file: [options-flag-or-value.js](./examples/options-flag-or-value.js)
 
+```js
 program
   .option('-c, --cheese [type]', 'Add cheese with optional type');
 
@@ -210,9 +209,9 @@ This allows you to coerce the option value to the desired type, or accumulate va
 
 You can optionally specify the default/starting value for the option after the function.
 
-```js
-const { program } = require('commander');
+Example file: [options-custom-processing.js](./examples/options-custom-processing.js)
 
+```js
 function myParseInt(value, dummyPrevious) {
   // parseInt takes a string and an optional radix
   return parseInt(value);
@@ -264,9 +263,9 @@ $ custom --list x,y,z
 
 You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.
 
-```js
-const { program } = require('commander');
+Example file: [options-required.js](./examples/options-required.js)
 
+```js
 program
   .requiredOption('-c, --cheese <type>', 'pizza must have cheese');
 
@@ -336,9 +335,9 @@ Configuration options can be passed with the call to `.command()` and `.addComma
 
 You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.
 
-```js
-const { program } = require('commander');
+Example file: [env](./examples/env)
 
+```js
 program
   .version('0.1.0')
   .arguments('<cmd> [env]')
@@ -422,25 +421,27 @@ You can specify a custom name with the `executableFile` configuration option.
 
 You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.
 
-```js
-// file: ./examples/pm
-const { program } = require('commander');
+Example file: [pm](./examples/pm)
 
+```js
 program
   .version('0.1.0')
   .command('install [name]', 'install one or more packages')
   .command('search [query]', 'search with optional query')
-  .command('update', 'update installed packages', {executableFile: 'myUpdateSubCommand'})
-  .command('list', 'list packages installed', {isDefault: true})
-  .parse(process.argv);
+  .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
+  .command('list', 'list packages installed', { isDefault: true });
+
+program.parse(process.argv);
 ```
 
 If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.
 
 ## Automated help
 
 The help information is auto-generated based on the information commander already knows about your program. The default
-help option is `-h,--help`. ([example](./examples/pizza))
+help option is `-h,--help`.
+
+Example file: [pizza](./examples/pizza)
 
 ```bash
 $ node ./examples/pizza --help
@@ -469,7 +470,9 @@ shell spawn --help
 
 ### Custom help
 
-You can display extra information by listening for "--help". ([example](./examples/custom-help))
+You can display extra information by listening for "--help".
+
+Example file: [custom-help](./examples/custom-help)
 
 ```js
 program
@@ -597,7 +600,7 @@ There are two new routines to change the behaviour, and the default behaviour ma
 - `passCommandToAction`: whether to pass command to action handler,
 or just the options (specify false)
 
-([example](./examples/storeOptionsAsProperties-action.js))
+Example file: [storeOptionsAsProperties-action.js](./examples/storeOptionsAsProperties-action.js)
 
 ```js
 program
@@ -680,6 +683,8 @@ try {
 
 ## Examples
 
+Example file: [deploy](./examples/deploy)
+
 ```js
 const { program } = require('commander');
 
@@ -719,10 +724,6 @@ program.parse(process.argv);
 
 More Demos can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.
 
-## License
-
-[MIT](https://github.com/tj/commander.js/blob/master/LICENSE)
-
 ## Support
 
 Commander 5.x is fully supported on Long Term Support versions of Node, and is likely to work with Node 6 but not tested.

examples/custom-help

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// This example displays some custom help text after the built-in help.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .option('-f, --foo', 'enable some foo');

examples/custom-help-description

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// This example shows changing the flags and description for the help option.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .helpOption('-c, --HELP', 'custom help message')

examples/custom-version

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// This example shows changing the flags and description for the version option.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .version('0.0.1', '-v, --VERSION', 'new version message')
   .option('-s, --sessions', 'add session support')
-  .option('-t, --template <engine>', 'specify template engine (jade|ejs) [jade]', 'jade')
-  .parse(process.argv);
+  .option('-t, --template <engine>', 'specify template engine (jade|ejs) [jade]', 'jade');
+
+program.parse(process.argv);

examples/defaultCommand.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 // const commander = require('commander'); // (normal include)
 const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();

examples/defaults

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// This example shows adding default values for options.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 function list(val) {
   return val.split(',').map(Number);
@@ -11,8 +14,9 @@ program
   .version('0.0.1')
   .option('-t, --template-engine [engine]', 'Add template [engine] support', 'jade')
   .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
-  .option('-l, --list [items]', 'Specify list items defaulting to 1,2,3', list, [1, 2, 3])
-  .parse(process.argv);
+  .option('-l, --list [items]', 'Specify list items defaulting to 1,2,3', list, [1, 2, 3]);
+
+program.parse(process.argv);
 
 console.log('  - %s template engine', program.templateEngine);
 console.log('  - %s cheese', program.cheese);

examples/deploy

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .version('0.0.1')

examples/description

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// This example shows adding a description which is displayed in the help.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .version('0.0.1')
   .description('Application simple description')
   .option('-f, --foo', 'enable some foo')
   .option('-b, --bar', 'enable some bar')
-  .option('-B, --baz', 'enable some baz')
-  .parse(process.argv);
+  .option('-B, --baz', 'enable some baz');
+
+program.parse(process.argv);
 
 if (!program.args.length) program.help();

examples/env

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// This example shows specifying the arguments for the program to pass to the action handler.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 let cmdValue;
 let envValue;

examples/nestedCommands.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 // const commander = require('commander'); // (normal include)
 const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();

examples/options-negatable.js

@@ -22,8 +22,9 @@ const program = new commander.Command();
 program
   .option('--no-sauce', 'Remove sauce')
   .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
-  .option('--no-cheese', 'plain with no cheese')
-  .parse(process.argv);
+  .option('--no-cheese', 'plain with no cheese');
+
+program.parse(process.argv);
 
 const sauceStr = program.sauce ? 'sauce' : 'no sauce';
 const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`;

examples/pizza

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .version('0.0.1')
   .description('An application for pizzas ordering')
   .option('-p, --peppers', 'Add peppers')
   .option('-c, --cheese <type>', 'Add the specified type of cheese', 'marble')
-  .option('-C, --no-cheese', 'You do not want any cheese')
-  .parse(process.argv);
+  .option('-C, --no-cheese', 'You do not want any cheese');
+
+program.parse(process.argv);
 
 console.log('you ordered a pizza with:');
 if (program.peppers) console.log('  - peppers');

examples/pm

@@ -1,25 +1,27 @@
 #!/usr/bin/env node
 
-// const program = require('commander'); // (normal include)
-const program = require('../'); // include commander in git clone of commander repo
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 program
   .version('0.0.1')
   .description('Fake package manager')
   .command('install [name]', 'install one or more packages').alias('i')
   .command('search [query]', 'search with optional query').alias('s')
-  .command('list', 'list packages installed')
-  .command('publish', 'publish the package').alias('p')
-  .parse(process.argv);
+  .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
+  .command('list', 'list packages installed', { isDefault: true });
+
+program.parse(process.argv);
 
 // here .command() is invoked with a description,
 // and no .action(callback) calls to handle sub-commands.
 // this tells commander that you're going to use separate
 // executables for sub-commands, much like git(1) and other
 // popular tools.
 
-// here only ./pm-install(1) is implemented, however you
-// would define ./pm-search(1) and ./pm-list(1) etc.
+// here only ./pm-install(1) and ./pm-list(1) are implemented, however you
+// would define ./pm-search(1) etc.
 
 // Try the following:
 //   ./examples/pm