diff options
Diffstat (limited to 'tools/eslint/node_modules/yargs/README.md')
| -rw-r--r-- | tools/eslint/node_modules/yargs/README.md | 926 |
1 files changed, 0 insertions, 926 deletions
diff --git a/tools/eslint/node_modules/yargs/README.md b/tools/eslint/node_modules/yargs/README.md deleted file mode 100644 index 99086e6e95..0000000000 --- a/tools/eslint/node_modules/yargs/README.md +++ /dev/null @@ -1,926 +0,0 @@ -yargs -======== - -Yargs be a node.js library fer hearties tryin' ter parse optstrings. - -With yargs, ye be havin' a map that leads straight to yer treasure! Treasure of course, being a simple option hash. - -[](https://travis-ci.org/bcoe/yargs) -[](https://gemnasium.com/bcoe/yargs) -[](https://coveralls.io/r/bcoe/yargs?branch=) -[](https://www.npmjs.com/package/yargs) - -> Yargs is the official successor to optimist. Please feel free to submit issues and pull requests. If you'd like to contribute and don't know where to start, have a look at [the issue list](https://github.com/bcoe/yargs/issues) :) - -examples -======== - -With yargs, the options be just a hash! -------------------------------------------------------------------- - -plunder.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs').argv; - -if (argv.ships > 3 && argv.distance < 53.5) { - console.log('Plunder more riffiwobbles!'); -} -else { - console.log('Retreat from the xupptumblers!'); -} -```` - -*** - - $ ./plunder.js --ships=4 --distance=22 - Plunder more riffiwobbles! - - $ ./plunder.js --ships 12 --distance 98.7 - Retreat from the xupptumblers! - - - -But don't walk the plank just yet! There be more! You can do short options: -------------------------------------------------- - -short.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs').argv; -console.log('(%d,%d)', argv.x, argv.y); -```` - -*** - - $ ./short.js -x 10 -y 21 - (10,21) - -And booleans, both long, short, and even grouped: ----------------------------------- - -bool.js: - -````javascript -#!/usr/bin/env node -var util = require('util'); -var argv = require('yargs').argv; - -if (argv.s) { - util.print(argv.fr ? 'Le perroquet dit: ' : 'The parrot says: '); -} -console.log( - (argv.fr ? 'couac' : 'squawk') + (argv.p ? '!' : '') -); -```` - -*** - - $ ./bool.js -s - The parrot says: squawk - - $ ./bool.js -sp - The parrot says: squawk! - - $ ./bool.js -sp --fr - Le perroquet dit: couac! - -And non-hyphenated options too! Just use `argv._`! -------------------------------------------------- - -nonopt.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs').argv; -console.log('(%d,%d)', argv.x, argv.y); -console.log(argv._); -```` - -*** - - $ ./nonopt.js -x 6.82 -y 3.35 rum - (6.82,3.35) - [ 'rum' ] - - $ ./nonopt.js "me hearties" -x 0.54 yo -y 1.12 ho - (0.54,1.12) - [ 'me hearties', 'yo', 'ho' ] - -Yargs even counts your booleans! ----------------------------------------------------------------------- - -count.js - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .count('verbose') - .alias('v', 'verbose') - .argv; - -VERBOSE_LEVEL = argv.verbose; - -function WARN() { VERBOSE_LEVEL >= 0 && console.log.apply(console, arguments); } -function INFO() { VERBOSE_LEVEL >= 1 && console.log.apply(console, arguments); } -function DEBUG() { VERBOSE_LEVEL >= 2 && console.log.apply(console, arguments); } - -WARN("Showing only important stuff"); -INFO("Showing semi-mportant stuff too"); -DEBUG("Extra chatty mode"); -```` - -*** - $ node count.js - Showing only important stuff - - $ node count.js -v - Showing only important stuff - Showing semi-important stuff too - - $ node count.js -vv - Showing only important stuff - Showing semi-important stuff too - Extra chatty mode - - $ node count.js -v --verbose - Showing only important stuff - Showing semi-important stuff too - Extra chatty mode - -Tell users how to use yer options and make demands. -------------------------------------------------- - -area.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .usage('Usage: $0 -w [num] -yh[num]') - .demand(['w','h']) - .argv; - -console.log("The area is:", argv.w * argv.h); -```` - -*** - - $ ./area.js -w 55 -h 11 - 605 - - $ node ./area.js -w 4.91 -w 2.51 - Usage: node ./area.js -w [num] -h [num] - - Options: - -w [required] - -h [required] - - Missing required arguments: h - -After yer demands have been met, demand more! Ask for non-hypenated arguments! ------------------------------------------ - -demand_count.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .demand(2) - .argv; -console.dir(argv) -```` - -*** - - $ ./demand_count.js a - Not enough arguments, expected 2, but only found 1 - $ ./demand_count.js a b - { _: [ 'a', 'b' ], '$0': 'node ./demand_count.js' } - $ ./demand_count.js a b c - { _: [ 'a', 'b', 'c' ], '$0': 'node ./demand_count.js' } - -EVEN MORE SHIVER ME TIMBERS! ------------------- - -default_singles.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .default('x', 10) - .default('y', 10) - .argv -; -console.log(argv.x + argv.y); -```` - -*** - - $ ./default_singles.js -x 5 - 15 - -default_hash.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .default({ x : 10, y : 10 }) - .argv -; -console.log(argv.x + argv.y); -```` - -*** - - $ ./default_hash.js -y 7 - 17 - -And if you really want to get all descriptive about it... ---------------------------------------------------------- - -boolean_single.js - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .boolean('v') - .argv -; -console.dir(argv.v); -console.dir(argv._); -```` - -*** - - $ ./boolean_single.js -v "me hearties" yo ho - true - [ 'me hearties', 'yo', 'ho' ] - - -boolean_double.js - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .boolean(['x','y','z']) - .argv -; -console.dir([ argv.x, argv.y, argv.z ]); -console.dir(argv._); -```` - -*** - - $ ./boolean_double.js -x -z one two three - [ true, false, true ] - [ 'one', 'two', 'three' ] - -Yargs is here to help you... ---------------------------- - -Ye can describe parameters fer help messages and set aliases. Yargs figures -out how ter format a handy help string automatically. - -line_count.js - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .usage('Usage: $0 <command> [options]') - .command('count', 'Count the lines in a file') - .demand(1) - .example('$0 count -f foo.js', 'count the lines in the given file') - .demand('f') - .alias('f', 'file') - .nargs('f', 1) - .describe('f', 'Load a file') - .help('h') - .alias('h', 'help') - .epilog('copyright 2015') - .argv; - -var fs = require('fs'); -var s = fs.createReadStream(argv.file); - -var lines = 0; -s.on('data', function (buf) { - lines += buf.toString().match(/\n/g).length; -}); - -s.on('end', function () { - console.log(lines); -}); -```` - -*** - $ node line_count.js count - Usage: node test.js <command> [options] - - Commands: - count Count the lines in a file - - Options: - -f, --file Load a file [required] - -h, --help Show help - - Examples: - node test.js count -f foo.js count the lines in the given file - - copyright 2015 - - Missing required arguments: f - - $ node line_count.js count --file line_count.js - 20 - - $ node line_count.js count -f line_count.js - 20 - -methods -======= - -By itself, - -````javascript -require('yargs').argv -````` - -will use `process.argv` array to construct the `argv` object. - -You can pass in the `process.argv` yourself: - -````javascript -require('yargs')([ '-x', '1', '-y', '2' ]).argv -```` - -or use .parse() to do the same thing: - -````javascript -require('yargs').parse([ '-x', '1', '-y', '2' ]) -```` - -The rest of these methods below come in just before the terminating `.argv`. - -.alias(key, alias) ------------------- - -Set key names as equivalent such that updates to a key will propagate to aliases -and vice-versa. - -Optionally `.alias()` can take an object that maps keys to aliases. -Each key of this object should be the canonical version of the option, and each -value should be a string or an array of strings. - -.default(key, value, [description]) --------------------- - -Set `argv[key]` to `value` if no option was specified on `process.argv`. - -Optionally `.default()` can take an object that maps keys to default values. - -But wait, there's more! the default value can be a `function` which returns -a value. The name of the function will be used in the usage string: - -```js -var argv = require('yargs') - .default('random', function randomValue() { - return Math.random() * 256; - }).argv; -``` - -Optionally, `description` can also be provided and will take precedence over -displaying the value in the usage instructions: - -```js -.default('timeout', 60000, '(one-minute)'); -``` - -.demand(key, [msg | boolean]) ------------------------------ -.require(key, [msg | boolean]) ------------------------------- -.required(key, [msg | boolean]) -------------------------------- - -If `key` is a string, show the usage information and exit if `key` wasn't -specified in `process.argv`. - -If `key` is a number, demand at least as many non-option arguments, which show -up in `argv._`. - -If `key` is an Array, demand each element. - -If a `msg` string is given, it will be printed when the argument is missing, -instead of the standard error message. This is especially helpful for the non-option arguments in `argv._`. - -If a `boolean` value is given, it controls whether the option is demanded; -this is useful when using `.options()` to specify command line parameters. - -.requiresArg(key) ------------------ - -Specifies either a single option key (string), or an array of options that -must be followed by option values. If any option value is missing, show the -usage information and exit. - -The default behaviour is to set the value of any key not followed by an -option value to `true`. - -.implies(x, y) --------------- - -Given the key `x` is set, it is required that the key `y` is set. - -implies can also accept an object specifying multiple implications. - -.describe(key, desc) --------------------- - -Describe a `key` for the generated usage information. - -Optionally `.describe()` can take an object that maps keys to descriptions. - -.option(key, opt) ------------------ -.options(key, opt) ------------------- - -Instead of chaining together `.alias().demand().default().describe().string()`, you can specify -keys in `opt` for each of the chainable methods. - -For example: - -````javascript -var argv = require('yargs') - .option('f', { - alias : 'file', - demand: true, - default: '/etc/passwd', - describe: 'x marks the spot', - type: 'string' - }) - .argv -; -```` - -is the same as - -````javascript -var argv = require('yargs') - .alias('f', 'file') - .default('f', '/etc/passwd') - .argv -; -```` - -Optionally `.options()` can take an object that maps keys to `opt` parameters. - -````javascript -var argv = require('yargs') - .options({ - 'f': { - alias: 'file', - demand: true, - default: '/etc/passwd', - describe: 'x marks the spot', - type: 'string' - } - }) - .argv -; -```` - -.usage(message, opts) ---------------------- - -Set a usage message to show which commands to use. Inside `message`, the string -`$0` will get interpolated to the current script name or node command for the -present script similar to how `$0` works in bash or perl. - -`opts` is optional and acts like calling `.options(opts)`. - -.command(cmd, desc, [fn]) -------------------- - -Document the commands exposed by your application. - -use `desc` to provide a description for each command your application accepts (the -values stored in `argv._`). - -Optionally, you can provide a handler `fn` which will be executed when -a given command is provided. The handler will be executed with an instance -of `yargs`, which can be used to compose nested commands. - -Here's an example of top-level and nested commands in action: - -```js -var argv = require('yargs') - .usage('npm <command>') - .command('install', 'tis a mighty fine package to install') - .command('publish', 'shiver me timbers, should you be sharing all that', function (yargs) { - argv = yargs.option('f', { - alias: 'force', - description: 'yar, it usually be a bad idea' - }) - .help('help') - .argv - }) - .help('help') - .argv; -``` - -.example(cmd, desc) -------------------- - -Give some example invocations of your program. Inside `cmd`, the string -`$0` will get interpolated to the current script name or node command for the -present script similar to how `$0` works in bash or perl. -Examples will be printed out as part of the help message. - - -.epilogue(str) --------------- -.epilog(str) ------------- - -A message to print at the end of the usage instructions, e.g., - -```js -var argv = require('yargs') - .epilogue('for more information, find our manual at http://example.com'); -``` - -.check(fn) ----------- - -Check that certain conditions are met in the provided arguments. - -`fn` is called with two arguments, the parsed `argv` hash and an array of options and their aliases. - -If `fn` throws or returns a non-truthy value, show the thrown error, usage information, and -exit. - -.fail(fn) ---------- - -Method to execute when a failure occurs, rather then printing the failure message. - -`fn` is called with the failure message that would have been printed. - -.boolean(key) -------------- - -Interpret `key` as a boolean. If a non-flag option follows `key` in -`process.argv`, that string won't get set as the value of `key`. - -`key` will default to `false`, unless an `default(key, undefined)` is -explicitly set. - -If `key` is an Array, interpret all the elements as booleans. - -.string(key) ------------- - -Tell the parser logic not to interpret `key` as a number or boolean. -This can be useful if you need to preserve leading zeros in an input. - -If `key` is an Array, interpret all the elements as strings. - -`.string('_')` will result in non-hyphenated arguments being interpreted as strings, -regardless of whether they resemble numbers. - -.array(key) ----------- - -Tell the parser to interpret `key` as an array. If `.array('foo')` is set, -`--foo foo bar` will be parsed as `['foo', 'bar']` rather than as `'bar'`. - -.nargs(key, count) ------------ - -The number of arguments that should be consumed after a key. This can be a -useful hint to prevent parsing ambiguity: - -```js -var argv = require('yargs') - .nargs('token', 1) - .parse(['--token', '-my-token']); -``` - -parses as: - -`{ _: [], token: '-my-token', '$0': 'node test' }` - -Optionally `.nargs()` can take an object of `key`/`narg` pairs. - -.config(key) ------------- - -Tells the parser that if the option specified by `key` is passed in, it -should be interpreted as a path to a JSON config file. The file is loaded -and parsed, and its properties are set as arguments. - -.wrap(columns) --------------- - -Format usage output to wrap at `columns` many columns. - -By default wrap will be set to `Math.min(80, windowWidth)`. Use `.wrap(null)` to -specify no column limit. - -`yargs.wrap(yargs.terminalWidth())` can be used to maximize the width -of yargs' usage instructions. - -.strict() ---------- - -Any command-line argument given that is not demanded, or does not have a -corresponding description, will be reported as an error. - -.help([option, [description]]) ------------------------------- - -Add an option (e.g., `--help`) that displays the usage string and exits the -process. If present, the `description` parameter customises the description of -the help option in the usage string. - -If invoked without parameters, `.help` returns the generated usage string. - -Example: - -``` -var yargs = require("yargs") - .usage("$0 -operand1 number -operand2 number -operation [add|subtract]"); -console.log(yargs.help()); -``` - -Later on, ```argv``` can be retrived with ```yargs.argv``` - -.version(version, [option], [description]) ----------------------------------------- - -Add an option (e.g., `--version`) that displays the version number (given by the -`version` parameter) and exits the process. If present, the `description` -parameter customizes the description of the version option in the usage string. - -You can provide a `function` for version, rather than a string. -This is useful if you want to use the version from your package.json: - -```js -var argv = require('yargs') - .version(function() { - return require('../package').version; - }) - .argv; -``` - -.showHelpOnFail(enable, [message]) ----------------------------------- - -By default, yargs outputs a usage string if any error is detected. Use the -`.showHelpOnFail` method to customize this behaviour. if `enable` is `false`, -the usage string is not output. If the `message` parameter is present, this -message is output after the error message. - -line_count.js - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .usage('Count the lines in a file.\nUsage: $0') - .demand('f') - .alias('f', 'file') - .describe('f', 'Load a file') - .showHelpOnFail(false, "Specify --help for available options") - .argv; - -// etc. -```` - -*** - - $ node line_count.js --file - Missing argument value: f - - Specify --help for available options - -.showHelp(consoleLevel='error') ---------------------------- - -Print the usage data using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel` for printing. - -Example: - -``` -var yargs = require("yargs") - .usage("$0 -operand1 number -operand2 number -operation [add|subtract]"); -yargs.showHelp(); -``` - -Or, to print the usage data to `stdout` instead, you can specify the use of `console.log`: - -``` -yargs.showHelp("log"); -``` - -Later on, ```argv``` can be retrived with ```yargs.argv``` - -.completion(cmd, [description], [fn]); -------------- - -Enable bash-completion shortcuts for commands and options. - -`cmd`: when present in `argv._`, will result in the `.bashrc` completion script -being outputted. To enable bash completions, concat the generated script to your -`.bashrc`, or `.bash_profile`. - -`description`: provide a description in your usage instructions for the command -that generates bash completion scripts. - -`fn`, rather than relying on yargs' default completion functionlity, which -shiver me timbers is pretty awesome, you can provide your own completion -method. - -```js -var argv = require('yargs') - .completion('completion', function(current, argv) { - // 'current' is the current command being completed. - // 'argv' is the parsed arguments so far. - // simply return an array of completions. - return [ - 'foo', - 'bar' - ]; - }) - .argv; -``` - -But wait, there's more! you can provide asynchronous completions. - -```js -var argv = require('yargs') - .completion('completion', function(current, argv, done) { - setTimeout(function() { - done([ - 'apple', - 'banana' - ]); - }, 500); - }) - .argv; -``` - -.showCompletionScript() ----------------------- - -Generate a bash completion script. Users of your application can install this -script in their `.bashrc`, and yargs will provide completion shortcuts for -commands and options. - -.exitProcess(enable) ----------------------------------- - -By default, yargs exits the process when the user passes a help flag, uses the `.version` functionality or when validation fails. Calling `.exitProcess(false)` disables this behavior, enabling further actions after yargs have been validated. - -.parse(args) ------------- - -Parse `args` instead of `process.argv`. Returns the `argv` object. - -.reset() --------- - -Reset the argument object built up so far. This is useful for -creating nested command line interfaces. - -```js -var yargs = require('./yargs') - .usage('$0 command') - .command('hello', 'hello command') - .command('world', 'world command') - .demand(1, 'must provide a valid command'), - argv = yargs.argv, - command = argv._[0]; - -if (command === 'hello') { - yargs.reset() - .usage('$0 hello') - .help('h') - .example('$0 hello', 'print the hello message!') - .argv - - console.log('hello!'); -} else if (command === 'world'){ - yargs.reset() - .usage('$0 world') - .help('h') - .example('$0 world', 'print the world message!') - .argv - - console.log('world!'); -} else { - yargs.showHelp(); -} -``` - -.argv ------ - -Get the arguments as a plain old object. - -Arguments without a corresponding flag show up in the `argv._` array. - -The script name or node command is available at `argv.$0` similarly to how `$0` -works in bash or perl. - -parsing tricks -============== - -stop parsing ------------- - -Use `--` to stop parsing flags and stuff the remainder into `argv._`. - - $ node examples/reflect.js -a 1 -b 2 -- -c 3 -d 4 - { _: [ '-c', '3', '-d', '4' ], - '$0': 'node ./examples/reflect.js', - a: 1, - b: 2 } - -negate fields -------------- - -If you want to explicity set a field to false instead of just leaving it -undefined or to override a default you can do `--no-key`. - - $ node examples/reflect.js -a --no-b - { _: [], - '$0': 'node ./examples/reflect.js', - a: true, - b: false } - -numbers -------- - -Every argument that looks like a number (`!isNaN(Number(arg))`) is converted to -one. This way you can just `net.createConnection(argv.port)` and you can add -numbers out of `argv` with `+` without having that mean concatenation, -which is super frustrating. - -duplicates ----------- - -If you specify a flag multiple times it will get turned into an array containing -all the values in order. - - $ node examples/reflect.js -x 5 -x 8 -x 0 - { _: [], - '$0': 'node ./examples/reflect.js', - x: [ 5, 8, 0 ] } - -dot notation ------------- - -When you use dots (`.`s) in argument names, an implicit object path is assumed. -This lets you organize arguments into nested objects. - - $ node examples/reflect.js --foo.bar.baz=33 --foo.quux=5 - { _: [], - '$0': 'node ./examples/reflect.js', - foo: { bar: { baz: 33 }, quux: 5 } } - -short numbers -------------- - -Short numeric `head -n5` style argument work too: - - $ node reflect.js -n123 -m456 - { '3': true, - '6': true, - _: [], - '$0': 'node ./reflect.js', - n: 123, - m: 456 } - -installation -============ - -With [npm](http://github.com/isaacs/npm), just do: - - npm install yargs - -or clone this project on github: - - git clone http://github.com/bcoe/yargs.git - -To run the tests with npm, just do: - - npm test - -inspired by -=========== - -This module is loosely inspired by Perl's -[Getopt::Casual](http://search.cpan.org/~photo/Getopt-Casual-0.13.1/Casual.pm). |