diff options
Diffstat (limited to 'node_modules/commander/Readme.md')
| -rw-r--r-- | node_modules/commander/Readme.md | 88 |
1 files changed, 81 insertions, 7 deletions
diff --git a/node_modules/commander/Readme.md b/node_modules/commander/Readme.md index 3135a9443..5897d371a 100644 --- a/node_modules/commander/Readme.md +++ b/node_modules/commander/Readme.md @@ -3,7 +3,8 @@ [](http://travis-ci.org/tj/commander.js) [](https://www.npmjs.org/package/commander) -[](https://www.npmjs.org/package/commander) +[](https://npmcharts.com/compare/commander?minimal=true) +[](https://packagephobia.now.sh/result?p=commander) [](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). @@ -16,7 +17,7 @@ ## Option parsing - Options with commander are defined with the `.option()` method, also serving as documentation for the options. The example below parses args and options from `process.argv`, leaving remaining args as the `program.args` array which were not consumed by options. +Options with commander are defined with the `.option()` method, also serving as documentation for the options. The example below parses args and options from `process.argv`, leaving remaining args as the `program.args` array which were not consumed by options. ```js #!/usr/bin/env node @@ -42,8 +43,65 @@ if (program.bbqSauce) console.log(' - bbq'); 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. +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'); +``` + +## Version option + +Calling the `version` implicitly adds the `-V` and `--version` options to the command. +When either of these options is present, the command prints the version number and exits. + + $ ./examples/pizza -V + 0.0.1 + +If you want your program to respond to the `-v` option instead of the `-V` option, simply pass custom flags to the `version` method using the same syntax as the `option` method. + +```js +program + .version('0.0.1', '-v, --version') +``` + +The version flags can be named anything, but the long option is required. + +## Command-specific options + +You can attach options to a command. + +```js +#!/usr/bin/env node + +var program = require('commander'); + +program + .command('rm <dir>') + .option('-r, --recursive', 'Remove recursively') + .action(function (dir, cmd) { + console.log('remove ' + dir + (cmd.recursive ? ' recursively' : '')) + }) + +program.parse(process.argv) +``` + +A command's options are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated. ## Coercion @@ -175,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`. @@ -285,9 +343,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 @@ -299,6 +357,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 |