From 363723fc84f7b8477592e0105aeb331ec9a017af Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Mon, 14 Aug 2017 05:01:11 +0200 Subject: node_modules --- node_modules/yargs/CHANGELOG.md | 118 ++ node_modules/yargs/README.md | 1986 +------------------- node_modules/yargs/lib/apply-extends.js | 52 + node_modules/yargs/lib/argsert.js | 72 + node_modules/yargs/lib/command.js | 115 +- node_modules/yargs/lib/completion.js | 7 +- node_modules/yargs/lib/usage.js | 53 +- node_modules/yargs/lib/validation.js | 39 +- node_modules/yargs/lib/yerror.js | 10 + node_modules/yargs/locales/zh_TW.json | 40 + .../yargs/node_modules/ansi-regex/index.js | 10 + node_modules/yargs/node_modules/ansi-regex/license | 9 + .../yargs/node_modules/ansi-regex/package.json | 53 + .../yargs/node_modules/ansi-regex/readme.md | 46 + node_modules/yargs/node_modules/path-type/index.js | 26 + node_modules/yargs/node_modules/path-type/license | 21 + .../yargs/node_modules/path-type/package.json | 48 + .../yargs/node_modules/path-type/readme.md | 42 + .../yargs/node_modules/read-pkg-up/index.js | 26 + .../yargs/node_modules/read-pkg-up/license | 21 + .../yargs/node_modules/read-pkg-up/package.json | 62 + .../yargs/node_modules/read-pkg-up/readme.md | 80 + node_modules/yargs/node_modules/read-pkg/index.js | 47 + node_modules/yargs/node_modules/read-pkg/license | 21 + .../yargs/node_modules/read-pkg/package.json | 45 + node_modules/yargs/node_modules/read-pkg/readme.md | 79 + .../yargs/node_modules/string-width/index.js | 36 + .../yargs/node_modules/string-width/license | 9 + .../yargs/node_modules/string-width/package.json | 55 + .../yargs/node_modules/string-width/readme.md | 42 + .../yargs/node_modules/strip-ansi/index.js | 4 + node_modules/yargs/node_modules/strip-ansi/license | 9 + .../yargs/node_modules/strip-ansi/package.json | 52 + .../yargs/node_modules/strip-ansi/readme.md | 39 + .../yargs/node_modules/yargs-parser/CHANGELOG.md | 69 + .../yargs/node_modules/yargs-parser/README.md | 26 +- .../yargs/node_modules/yargs-parser/index.js | 19 +- .../yargs/node_modules/yargs-parser/package.json | 6 +- node_modules/yargs/package.json | 28 +- node_modules/yargs/yargs.js | 624 +++--- 40 files changed, 1870 insertions(+), 2276 deletions(-) create mode 100644 node_modules/yargs/lib/apply-extends.js create mode 100644 node_modules/yargs/lib/argsert.js create mode 100644 node_modules/yargs/lib/yerror.js create mode 100644 node_modules/yargs/locales/zh_TW.json create mode 100644 node_modules/yargs/node_modules/ansi-regex/index.js create mode 100644 node_modules/yargs/node_modules/ansi-regex/license create mode 100644 node_modules/yargs/node_modules/ansi-regex/package.json create mode 100644 node_modules/yargs/node_modules/ansi-regex/readme.md create mode 100644 node_modules/yargs/node_modules/path-type/index.js create mode 100644 node_modules/yargs/node_modules/path-type/license create mode 100644 node_modules/yargs/node_modules/path-type/package.json create mode 100644 node_modules/yargs/node_modules/path-type/readme.md create mode 100644 node_modules/yargs/node_modules/read-pkg-up/index.js create mode 100644 node_modules/yargs/node_modules/read-pkg-up/license create mode 100644 node_modules/yargs/node_modules/read-pkg-up/package.json create mode 100644 node_modules/yargs/node_modules/read-pkg-up/readme.md create mode 100644 node_modules/yargs/node_modules/read-pkg/index.js create mode 100644 node_modules/yargs/node_modules/read-pkg/license create mode 100644 node_modules/yargs/node_modules/read-pkg/package.json create mode 100644 node_modules/yargs/node_modules/read-pkg/readme.md create mode 100644 node_modules/yargs/node_modules/string-width/index.js create mode 100644 node_modules/yargs/node_modules/string-width/license create mode 100644 node_modules/yargs/node_modules/string-width/package.json create mode 100644 node_modules/yargs/node_modules/string-width/readme.md create mode 100644 node_modules/yargs/node_modules/strip-ansi/index.js create mode 100644 node_modules/yargs/node_modules/strip-ansi/license create mode 100644 node_modules/yargs/node_modules/strip-ansi/package.json create mode 100644 node_modules/yargs/node_modules/strip-ansi/readme.md (limited to 'node_modules/yargs') diff --git a/node_modules/yargs/CHANGELOG.md b/node_modules/yargs/CHANGELOG.md index 5c80536ae..95f414125 100644 --- a/node_modules/yargs/CHANGELOG.md +++ b/node_modules/yargs/CHANGELOG.md @@ -2,6 +2,124 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. + +## [8.0.2](https://github.com/yargs/yargs/compare/v8.0.1...v8.0.2) (2017-06-12) + + + + +## [8.0.1](https://github.com/yargs/yargs/compare/v8.0.0...v8.0.1) (2017-05-02) + + + + +# [8.0.0](https://github.com/yargs/yargs/compare/v7.1.0...v8.0.0) (2017-05-01) + + +### Bug Fixes + +* commands are now applied in order, from left to right ([#857](https://github.com/yargs/yargs/issues/857)) ([baba863](https://github.com/yargs/yargs/commit/baba863)) +* help now takes precedence over command recommendation ([#866](https://github.com/yargs/yargs/issues/866)) ([17e3567](https://github.com/yargs/yargs/commit/17e3567)) +* positional arguments now work if no handler is provided to inner command ([#864](https://github.com/yargs/yargs/issues/864)) ([e28ded3](https://github.com/yargs/yargs/commit/e28ded3)) + + +### Chores + +* upgrade yargs-parser ([#867](https://github.com/yargs/yargs/issues/867)) ([8f9c6c6](https://github.com/yargs/yargs/commit/8f9c6c6)) + + +### Features + +* allow extends to inherit from a module ([#865](https://github.com/yargs/yargs/issues/865)) ([89456d9](https://github.com/yargs/yargs/commit/89456d9)) +* allow strict mode to be disabled ([#840](https://github.com/yargs/yargs/issues/840)) ([6f78c05](https://github.com/yargs/yargs/commit/6f78c05)) + + +### BREAKING CHANGES + +* extends functionality now always loads the JSON provided, rather than reading from a specific key +* Node 4+ is now required; this will allow us to start updating our dependencies. +* the first argument to strict() is now used to enable/disable its functionality, rather than controlling whether or not it is global. + + + + +# [7.1.0](https://github.com/yargs/yargs/compare/v7.0.2...v7.1.0) (2017-04-13) + + +### Bug Fixes + +* fix demandOption no longer treats 'false' as truthy ([#829](https://github.com/yargs/yargs/issues/829)) ([c748dd2](https://github.com/yargs/yargs/commit/c748dd2)) +* get terminalWidth in non interactive mode no longer causes a validation exception ([#837](https://github.com/yargs/yargs/issues/837)) ([360e301](https://github.com/yargs/yargs/commit/360e301)) +* we shouldn't output help if we've printed a prior help-like message ([#847](https://github.com/yargs/yargs/issues/847)) ([17e89bd](https://github.com/yargs/yargs/commit/17e89bd)) + + +### Features + +* add support for numeric commands ([#825](https://github.com/yargs/yargs/issues/825)) ([fde0564](https://github.com/yargs/yargs/commit/fde0564)) + + + + +## [7.0.2](https://github.com/yargs/yargs/compare/v7.0.1...v7.0.2) (2017-03-10) + + +### Bug Fixes + +* populating placeholder arguments broke validation ([b3eb2fe](https://github.com/yargs/yargs/commit/b3eb2fe)) + + + + +## [7.0.1](https://github.com/yargs/yargs/compare/v7.0.0...v7.0.1) (2017-03-03) + + +### Bug Fixes + +* --help with default command should print top-level help ([#810](https://github.com/yargs/yargs/issues/810)) ([9c03fa4](https://github.com/yargs/yargs/commit/9c03fa4)) + + + + +# [7.0.0](https://github.com/yargs/yargs/compare/v6.6.0...v7.0.0) (2017-02-26) + + +### Bug Fixes + +* address min/max validation message regression ([#750](https://github.com/yargs/yargs/issues/750)) ([2e5ce0f](https://github.com/yargs/yargs/commit/2e5ce0f)) +* address positional argument strict() bug introduced in [#766](https://github.com/yargs/yargs/issues/766) ([#784](https://github.com/yargs/yargs/issues/784)) ([a8528e6](https://github.com/yargs/yargs/commit/a8528e6)) +* console.warn() rather than throwing errors when api signatures are incorrect ([#804](https://github.com/yargs/yargs/issues/804)) ([a607061](https://github.com/yargs/yargs/commit/a607061)) +* context should override parsed argv ([#786](https://github.com/yargs/yargs/issues/786)) ([0997288](https://github.com/yargs/yargs/commit/0997288)) +* context variables are now recognized in strict() mode ([#796](https://github.com/yargs/yargs/issues/796)) ([48575cd](https://github.com/yargs/yargs/commit/48575cd)) +* errors were not bubbling appropriately from sub-commands to top-level ([#802](https://github.com/yargs/yargs/issues/802)) ([8a992f5](https://github.com/yargs/yargs/commit/8a992f5)) +* positional arguments of sub-commands threw strict() exception ([#805](https://github.com/yargs/yargs/issues/805)) ([f3f074b](https://github.com/yargs/yargs/commit/f3f074b)) +* pull in yargs-parser with modified env precedence ([#787](https://github.com/yargs/yargs/issues/787)) ([e0fbbe5](https://github.com/yargs/yargs/commit/e0fbbe5)) +* running parse() multiple times on the same yargs instance caused exception if help() enabled ([#790](https://github.com/yargs/yargs/issues/790)) ([07e39b7](https://github.com/yargs/yargs/commit/07e39b7)) +* use path.resolve() to support node 0.10 ([#797](https://github.com/yargs/yargs/issues/797)) ([49a93fc](https://github.com/yargs/yargs/commit/49a93fc)) + + +### Features + +* add conflicts and implies shorthands. ([#753](https://github.com/yargs/yargs/issues/753)) ([bd1472b](https://github.com/yargs/yargs/commit/bd1472b)) +* add traditional Chinese translation ([#780](https://github.com/yargs/yargs/issues/780)) ([6ab6a95](https://github.com/yargs/yargs/commit/6ab6a95)) +* allow provided config object to extend other configs ([#779](https://github.com/yargs/yargs/issues/779)) ([3280dd0](https://github.com/yargs/yargs/commit/3280dd0)) +* function argument validation ([#773](https://github.com/yargs/yargs/issues/773)) ([22ed9bb](https://github.com/yargs/yargs/commit/22ed9bb)) +* if only one column is provided for examples, allow it to take up the entire line ([#749](https://github.com/yargs/yargs/issues/749)) ([7931652](https://github.com/yargs/yargs/commit/7931652)) +* introduce custom yargs error object ([#765](https://github.com/yargs/yargs/issues/765)) ([8308efa](https://github.com/yargs/yargs/commit/8308efa)) +* introduces support for default commands, using the '*' identifier ([#785](https://github.com/yargs/yargs/issues/785)) ([d78a0f5](https://github.com/yargs/yargs/commit/d78a0f5)) +* rethink how options are inherited by commands ([#766](https://github.com/yargs/yargs/issues/766)) ([ab1fa4b](https://github.com/yargs/yargs/commit/ab1fa4b)) + + +### BREAKING CHANGES + +* `extends` key in config file is now used for extending other config files +* environment variables now take precedence over config files. +* context now takes precedence over argv and defaults +* the arguments passed to functions are now validated, there's a good chance this will throw exceptions for a few folks who are using the API in an unexpected way. +* by default options, and many of yargs' parsing helpers will now default to being applied globally; such that they are no-longer reset before being passed into commands. +* yargs will no longer aggressively suppress errors, allowing errors that are not generated internally to bubble. + + + # [6.6.0](https://github.com/yargs/yargs/compare/v6.5.0...v6.6.0) (2016-12-29) diff --git a/node_modules/yargs/README.md b/node_modules/yargs/README.md index 154ed80cc..867118bfe 100644 --- a/node_modules/yargs/README.md +++ b/node_modules/yargs/README.md @@ -1,1969 +1,91 @@ - 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. +# Yargs [![Build Status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url] [![NPM version][npm-image]][npm-url] [![Windows Tests][windows-image]][windows-url] [![js-standard-style][standard-image]][standard-url] -[![standard-version][standard-version-image]][standard-version-url] +[![Conventional Commits][conventional-commits-image]][conventional-commits-url] [![Gitter][gitter-image]][gitter-url] -> 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/yargs/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! +> Yargs be a node.js library fer hearties tryin' ter parse optstrings. -![Joe was one optimistic pirate.](https://i.imgur.com/4WFGVJ9.png) + -But don't walk the plank just yet! There be more! You can do short options: -------------------------------------------------- +Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface. It gives you: -short.js: +* commands and (grouped) options (`my-program.js serve --port=5000`). +* a dynamically generated help menu based on your arguments. -````javascript -#!/usr/bin/env node -var argv = require('yargs').argv; -console.log('(%d,%d)', argv.x, argv.y); -```` +> -*** +* bash-completion shortcuts for commands and options. +* and [tons more](/docs/api.md). - $ ./short.js -x 10 -y 21 - (10,21) +## Installation -And booleans, both long, short, and even grouped: ----------------------------------- +```bash +npm i yargs --save +``` -bool.js: +## Simple Example ````javascript #!/usr/bin/env node -var argv = require('yargs').argv; +const argv = require('yargs').argv -if (argv.s) { - process.stdout.write(argv.fr ? 'Le perroquet dit: ' : 'The parrot says: '); +if (argv.ships > 3 && argv.distance < 53.5) { + console.log('Plunder more riffiwobbles!') +} else { + console.log('Retreat from the xupptumblers!') } -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-important 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] -h [num]') - .demandOption(['w','h']) - .argv; - -console.log("The area is:", argv.w * argv.h); -```` - -*** - - $ ./area.js -w 55 -h 11 - The area is: 605 - - $ node ./area.js -w 4.91 -w 2.51 - Usage: 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-hyphenated arguments! ------------------------------------------ - -demand_count.js: - -````javascript -#!/usr/bin/env node -var argv = require('yargs') - .demandCommand(2) - .argv; -console.dir(argv); -```` - -*** - - $ ./demand_count.js a - - Not enough non-option arguments: got 1, need at least 2 - - $ ./demand_count.js a b - { _: [ 'a', 'b' ], '$0': 'demand_count.js' } - - $ ./demand_count.js a b c - { _: [ 'a', 'b', 'c' ], '$0': '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 [options]') - .command('count', 'Count the lines in a file') - .example('$0 count -f foo.js', 'count the lines in the given file') - .alias('f', 'file') - .nargs('f', 1) - .describe('f', 'Load a file') - .demandOption(['f']) - .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: line_count.js [options] - - Commands: - count Count the lines in a file - - Options: - -f, --file Load a file [required] - -h, --help Show help [boolean] - - Examples: - line_count.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 - 26 - - $ node line_count.js count -f line_count.js - 26 - -methods -======= - -By itself, - -````javascript -require('yargs').argv -```` - -will use the `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. - -.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. - -If `yargs` is executed in an environment that embeds node and there's no script name (e.g. -[Electron](http://electron.atom.io/) or [nw.js](http://nwjs.io/)), it will ignore the first parameter since it -expects it to be the script name. In order to override this behavior, use `.parse(process.argv.slice(1))` -instead of `.argv` and the first parameter won't be ignored. - -.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 `'foo'`. - -.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 a `default(key, undefined)` is -explicitly set. - -If `key` is an array, interpret all the elements as booleans. - -.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. - -.choices(key, choices) ----------------------- - -Limit valid values for `key` to a predefined set of `choices`, given as an array -or as an individual value. - -```js -var argv = require('yargs') - .alias('i', 'ingredient') - .describe('i', 'choose your sandwich ingredients') - .choices('i', ['peanut-butter', 'jelly', 'banana', 'pickles']) - .help('help') - .argv -``` - -If this method is called multiple times, all enumerated values will be merged -together. Choices are generally strings or numbers, and value matching is -case-sensitive. - -Optionally `.choices()` can take an object that maps multiple keys to their -choices. - -Choices can also be specified as `choices` in the object given to `option()`. - -```js -var argv = require('yargs') - .option('size', { - alias: 's', - describe: 'choose a size', - choices: ['xs', 's', 'm', 'l', 'xl'] - }) - .argv -``` - -.coerce(key, fn) ----------------- - -Provide a synchronous function to coerce or transform the value(s) given on the -command line for `key`. - -The coercion function should accept one argument, representing the parsed value -from the command line, and should return a new value or throw an error. The -returned value will be used as the value for `key` (or one of its aliases) in -`argv`. - -If the function throws, the error will be treated as a validation -failure, delegating to either a custom [`.fail()`](#fail) handler or printing -the error message in the console. - -Coercion will be applied to a value after -all other modifications, such as [`.normalize()`](#normalize). - -_Examples:_ - -```js -var argv = require('yargs') - .coerce('file', function (arg) { - return require('fs').readFileSync(arg, 'utf8') - }) - .argv -``` - -Optionally `.coerce()` can take an object that maps several keys to their -respective coercion function. - -```js -var argv = require('yargs') - .coerce({ - date: Date.parse, - json: JSON.parse - }) - .argv -``` - -You can also map the same function to several keys at one time. Just pass an -array of keys as the first argument to `.coerce()`: - -```js -var path = require('path') -var argv = require('yargs') - .coerce(['src', 'dest'], path.resolve) - .argv -``` - -If you are using dot-notion or arrays, .e.g., `user.email` and `user.password`, -coercion will be applied to the final object that has been parsed: - -```js -// --user.name Batman --user.password 123 -// gives us: {name: 'batman', password: '[SECRET]'} -var argv = require('yargs') - .option('user') - .coerce('user', opt => { - opt.name = opt.name.toLowerCase() - opt.password = '[SECRET]' - return opt - }) - .argv -``` - -.command(cmd, desc, [builder], [handler]) ------------------------------------------ -.command(cmd, desc, [module]) ------------------------------ -.command(module) ----------------- - -Define the commands exposed by your application. - -`cmd` should be a string representing the command or an array of strings -representing the command and its aliases. Read more about command aliases in the -subsection below. - -Use `desc` to provide a description for each command your application accepts (the -values stored in `argv._`). Set `desc` to `false` to create a hidden command. -Hidden commands don't show up in the help output and aren't available for -completion. - -Optionally, you can provide a `builder` object to give hints about the -options that your command accepts: - -```js -yargs - .command('get', 'make a get HTTP request', { - url: { - alias: 'u', - default: 'http://yargs.js.org/' - } - }) - .help() - .argv -``` - -Note that commands will not automatically inherit configuration _or_ options -of their parent context. This means you'll have to re-apply configuration -if necessary, and make options global manually using the [global](#global) method. - -Additionally, the [`help`](#help) and [`version`](#version) -options (if used) **always** apply globally, just like the -[`.wrap()`](#wrap) configuration. - -`builder` can also be a function. This function is executed -with a `yargs` instance, and can be used to provide _advanced_ command specific help: - -```js -yargs - .command('get', 'make a get HTTP request', function (yargs) { - return yargs.option('url', { - alias: 'u', - default: 'http://yargs.js.org/' - }) - }) - .help() - .argv -``` - -You can also provide a handler function, which will be executed with the -parsed `argv` object: - -```js -yargs - .command( - 'get', - 'make a get HTTP request', - function (yargs) { - return yargs.option('u', { - alias: 'url', - describe: 'the URL to make an HTTP request to' - }) - }, - function (argv) { - console.log(argv.url) - } - ) - .help() - .argv -``` - -### Positional Arguments - -Commands can accept _optional_ and _required_ positional arguments. Required -positional arguments take the form ``, and optional arguments -take the form `[bar]`. The parsed positional arguments will be populated in -`argv`: - -```js -yargs.command('get [proxy]', 'make a get HTTP request') - .help() - .argv -``` - -#### Positional Argument Aliases - -Aliases can be provided for positional arguments using the `|` character. -As an example, suppose our application allows either a username _or_ -an email as the first argument: - -```js -yargs.command('get [password]', 'fetch a user by username or email.') - .help() - .argv -``` - -In this way, both `argv.username` and `argv.email` would be populated with the -same value when the command is executed. - -#### Variadic Positional Arguments - -The last positional argument can optionally accept an array of -values, by using the `..` operator: +```bash +$ ./plunder.js --ships=4 --distance=22 +Plunder more riffiwobbles! -```js -yargs.command('download [files..]', 'download several files') - .help() - .argv +$ ./plunder.js --ships 12 --distance 98.7 +Retreat from the xupptumblers! ``` -### Command Execution - -When a command is given on the command line, yargs will execute the following: - -1. push the command into the current context -2. reset non-global configuration -3. apply command configuration via the `builder`, if given -4. parse and validate args from the command line, including positional args -5. if validation succeeds, run the `handler` function, if given -6. pop the command from the current context - -### Command Aliases - -You can define aliases for a command by putting the command and all of its -aliases into an array. - -Alternatively, a command module may specify an `aliases` property, which may be -a string or an array of strings. All aliases defined via the `command` property -and the `aliases` property will be concatenated together. - -The first element in the array is considered the canonical command, which may -define positional arguments, and the remaining elements in the array are -considered aliases. Aliases inherit positional args from the canonical command, -and thus any positional args defined in the aliases themselves are ignored. - -If either the canonical command or any of its aliases are given on the command -line, the command will be executed. +## Complex Example ```js #!/usr/bin/env node -require('yargs') - .command(['start [app]', 'run', 'up'], 'Start up an app', {}, (argv) => { - console.log('starting up the', argv.app || 'default', 'app') +const yargs = require('yargs') // eslint-disable-line + .command('serve', 'start the server', (yargs) => { + yargs.option('port', { + describe: 'port to bind on', + default: 5000 + }) + }, (argv) => { + if (argv.verbose) console.info(`start server on :${argv.port}`) + serve(argv.port) }) - .command({ - command: 'configure [value]', - aliases: ['config', 'cfg'], - desc: 'Set a config variable', - builder: (yargs) => yargs.default('value', 'true'), - handler: (argv) => { - console.log(`setting ${argv.key} to ${argv.value}`) - } + .option('verbose', { + alias: 'v', + default: false }) - .demandCommand(1) .help() - .wrap(72) .argv ``` -``` -$ ./svc.js help -Commands: - start [app] Start up an app [aliases: run, up] - configure [value] Set a config variable [aliases: config, cfg] - -Options: - --help Show help [boolean] - -$ ./svc.js cfg concurrency 4 -setting concurrency to 4 - -$ ./svc.js run web -starting up the web app -``` - -### Providing a Command Module - -For complicated commands you can pull the logic into a module. A module -simply needs to export: - -* `exports.command`: string (or array of strings) that executes this command when given on the command line, first string may contain positional args -* `exports.aliases`: array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored -* `exports.describe`: string used as the description for the command in help text, use `false` for a hidden command -* `exports.builder`: object declaring the options the command accepts, or a function accepting and returning a yargs instance -* `exports.handler`: a function which will be passed the parsed argv. - -```js -// my-module.js -exports.command = 'get [proxy]' - -exports.describe = 'make a get HTTP request' - -exports.builder = { - banana: { - default: 'cool' - }, - batman: { - default: 'sad' - } -} - -exports.handler = function (argv) { - // do something with argv. -} -``` - -You then register the module like so: - -```js -yargs.command(require('my-module')) - .help() - .argv -``` - -Or if the module does not export `command` and `describe` (or if you just want to override them): - -```js -yargs.command('get [proxy]', 'make a get HTTP request', require('my-module')) - .help() - .argv -``` - -.commandDir(directory, [opts]) ------------------------------- - -Apply command modules from a directory relative to the module calling this method. - -This allows you to organize multiple commands into their own modules under a -single directory and apply all of them at once instead of calling -`.command(require('./dir/module'))` multiple times. - -By default, it ignores subdirectories. This is so you can use a directory -structure to represent your command hierarchy, where each command applies its -subcommands using this method in its builder function. See the example below. - -Note that yargs assumes all modules in the given directory are command modules -and will error if non-command modules are encountered. In this scenario, you -can either move your module to a different directory or use the `exclude` or -`visit` option to manually filter it out. More on that below. - -`directory` is a relative directory path as a string (required). - -`opts` is an options object (optional). The following options are valid: - -- `recurse`: boolean, default `false` - - Look for command modules in all subdirectories and apply them as a flattened - (non-hierarchical) list. - -- `extensions`: array of strings, default `['js']` - - The types of files to look for when requiring command modules. - -- `visit`: function - - A synchronous function called for each command module encountered. Accepts - `commandObject`, `pathToFile`, and `filename` as arguments. Returns - `commandObject` to include the command; any falsy value to exclude/skip it. - -- `include`: RegExp or function - - Whitelist certain modules. See [`require-directory` whitelisting](https://www.npmjs.com/package/require-directory#whitelisting) for details. - -- `exclude`: RegExp or function - - Blacklist certain modules. See [`require-directory` blacklisting](https://www.npmjs.com/package/require-directory#blacklisting) for details. - -### Example command hierarchy using `.commandDir()` - -Desired CLI: - -```sh -$ myapp --help -$ myapp init -$ myapp remote --help -$ myapp remote add base http://yargs.js.org -$ myapp remote prune base -$ myapp remote prune base fork whatever -``` - -Directory structure: - -``` -myapp/ -├─ cli.js -└─ cmds/ - ├─ init.js - ├─ remote.js - └─ remote_cmds/ - ├─ add.js - └─ prune.js -``` - -cli.js: - -```js -#!/usr/bin/env node -require('yargs') - .commandDir('cmds') - .demandCommand(1) - .help() - .argv -``` - -cmds/init.js: - -```js -exports.command = 'init [dir]' -exports.desc = 'Create an empty repo' -exports.builder = { - dir: { - default: '.' - } -} -exports.handler = function (argv) { - console.log('init called for dir', argv.dir) -} -``` - -cmds/remote.js: - -```js -exports.command = 'remote ' -exports.desc = 'Manage set of tracked repos' -exports.builder = function (yargs) { - return yargs.commandDir('remote_cmds') -} -exports.handler = function (argv) {} -``` - -cmds/remote_cmds/add.js: - -```js -exports.command = 'add ' -exports.desc = 'Add remote named for repo at url ' -exports.builder = {} -exports.handler = function (argv) { - console.log('adding remote %s at url %s', argv.name, argv.url) -} -``` - -cmds/remote_cmds/prune.js: - -```js -exports.command = 'prune [names..]' -exports.desc = 'Delete tracked branches gone stale for remotes' -exports.builder = {} -exports.handler = function (argv) { - console.log('pruning remotes %s', [].concat(argv.name).concat(argv.names).join(', ')) -} -``` - -.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 functionality, which -shiver me timbers is pretty awesome, you can provide your own completion -method. - -If invoked without parameters, `.completion()` will make `completion` the command to output -the completion script. - -```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; -``` - -You can also provide asynchronous completions. - -```js -var argv = require('yargs') - .completion('completion', function(current, argv, done) { - setTimeout(function() { - done([ - 'apple', - 'banana' - ]); - }, 500); - }) - .argv; -``` - -But wait, there's more! You can return an asynchronous promise. - -```js -var argv = require('yargs') - .completion('completion', function(current, argv, done) { - return new Promise(function (resolve, reject) { - setTimeout(function () { - resolve(['apple', 'banana']) - }, 10) - }) - }) - .argv; -``` - -.config([key], [description], [parseFn]) -------------------------------------------------------------- -.config(object) ---------------- - -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. Because the file is -loaded using Node's require(), the filename MUST end in `.json` to be -interpreted correctly. - -If invoked without parameters, `.config()` will make `--config` the option to pass the JSON config file. - -An optional `description` can be provided to customize the config (`key`) option -in the usage string. - -An optional `parseFn` can be used to provide a custom parser. The parsing -function must be synchronous, and should return an object containing -key value pairs or an error. - -```js -var argv = require('yargs') - .config('settings', function (configPath) { - return JSON.parse(fs.readFileSync(configPath, 'utf-8')) - }) - .argv -``` - -You can also pass an explicit configuration `object`, it will be parsed -and its properties will be set as arguments. - -```js -var argv = require('yargs') - .config({foo: 1, bar: 2}) - .argv -console.log(argv) -``` - -``` -$ node test.js -{ _: [], - foo: 1, - bar: 2, - '$0': 'test.js' } -``` - -.conflicts(x, y) ----------------------------------------------- - -Given the key `x` is set, the key `y` must not be set. - -Optionally `.conflicts()` can accept an object specifying multiple conflicting keys. - -.count(key) ------------- - -Interpret `key` as a boolean flag, but set its parsed value to the number of -flag occurrences rather than `true` or `false`. Default value is thus `0`. - -.default(key, value, [description]) ---------------------------------------------------------- -.defaults(key, value, [description]) ------------------------------------- - -**Note:** The `.defaults()` alias is deprecated. It will be -removed in the next major version. - -Set `argv[key]` to `value` if no option was specified in `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(count, [max], [msg]) [DEPRECATED] --------------------- - -`demand()` has been deprecated, please instead see [`demandOption()`](#demandOption) and -[`demandCommand()`](#demandCommand). - -.demandOption(key, [msg | boolean]) ------------------------------- -.demandOption(key, msg) ------------------------------- - -If `key` is a string, show the usage information and exit if `key` wasn't -specified in `process.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. - -```javascript -// demand an array of keys to be provided -require('yargs') - .option('run', { - alias: 'r', - describe: 'run your program' - }) - .option('path', { - alias: 'p', - describe: 'provide a path to file' - }) - .option('spec', { - alias: 's', - describe: 'program specifications' - }) - .demandOption(['run', 'path'], 'Please provide both run and path arguments to work with this tool') - .help() - .argv -``` -which will provide the following output: -```bash -Options: - --run, -r run your program [required] - --path, -p provide a path to file [required] - --spec, -s program specifications - --help Show help [boolean] - - Missing required arguments: run, path - Please provide both run and path arguments to work with this tool -``` - -If a `boolean` value is given, it controls whether the option is demanded; -this is useful when using `.options()` to specify command line parameters. - -```javascript -// demand individual options within the option constructor -require('yargs') - .options({ - 'run': { - alias: 'r', - describe: 'run your program', - demand: true - }, - 'path': { - alias: 'p', - describe: 'provide a path to file', - demand: true - }, - 'spec': { - alias: 's', - describe: 'program specifications' - } - }) - .help() - .argv -``` -which will provide the following output: -```bash -Options: - --run, -r run your program [required] - --path, -p provide a path to file [required] - --spec, -s program specifications - --help Show help [boolean] - -Missing required arguments: run, path -``` - -.demandCommand(min, [minMsg]) ------------------------------- -.demandCommand(min, [max], [minMsg], [maxMsg]) ------------------------------- - -Demand in context of commands. You can demand a minimum and a maximum number a user can have within your program, as well as provide corresponding error messages if either of the demands is not met. -```javascript -require('yargs') - .command({ - command: 'configure [value]', - aliases: ['config', 'cfg'], - desc: 'Set a config variable', - builder: (yargs) => yargs.default('value', 'true'), - handler: (argv) => { - console.log(`setting ${argv.key} to ${argv.value}`) - } - }) - // provide a minimum demand and a minimum demand message - .demandCommand(1, 'You need at least one command before moving on') - .help() - .argv -``` -which will provide the following output: -```bash -Commands: - configure [value] Set a config variable [aliases: config, cfg] - -Options: - --help Show help [boolean] - -You need at least one command before moving on -``` - -_Note: in `minMsg` and `maxMsg`, every occurrence of `$0` will be replaced -with the observed value, and every instance of `$1` will be replaced with the -expected value._ - -.describe(key, desc) --------------------- - -Describe a `key` for the generated usage information. - -Optionally `.describe()` can take an object that maps keys to descriptions. - -.detectLocale(boolean) ------------ - -Should yargs attempt to detect the os' locale? Defaults to `true`. - -.env([prefix]) --------------- - -Tell yargs to parse environment variables matching the given prefix and apply -them to argv as though they were command line arguments. - -Use the "__" separator in the environment variable to indicate nested options. -(e.g. prefix_nested__foo => nested.foo) - -If this method is called with no argument or with an empty string or with `true`, -then all env vars will be applied to argv. - -Program arguments are defined in this order of precedence: - -1. Command line args -2. Config file -3. Env var -4. Configured defaults - -```js -var argv = require('yargs') - .env('MY_PROGRAM') - .option('f', { - alias: 'fruit-thing', - default: 'apple' - }) - .argv -console.log(argv) -``` - -``` -$ node fruity.js -{ _: [], - f: 'apple', - 'fruit-thing': 'apple', - fruitThing: 'apple', - '$0': 'fruity.js' } -``` - -``` -$ MY_PROGRAM_FRUIT_THING=banana node fruity.js -{ _: [], - fruitThing: 'banana', - f: 'banana', - 'fruit-thing': 'banana', - '$0': 'fruity.js' } -``` - -``` -$ MY_PROGRAM_FRUIT_THING=banana node fruity.js -f cat -{ _: [], - f: 'cat', - 'fruit-thing': 'cat', - fruitThing: 'cat', - '$0': 'fruity.js' } -``` - -Env var parsing is disabled by default, but you can also explicitly disable it -by calling `.env(false)`, e.g. if you need to undo previous configuration. - -.epilog(str) ------------- -.epilogue(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'); -``` - -.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. - -.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. - -.fail(fn) ---------- - -Method to execute when a failure occurs, rather than printing the failure message. - -`fn` is called with the failure message that would have been printed, the -`Error` instance originally thrown and yargs state when the failure -occured. - -```js -var argv = require('yargs') - .fail(function (msg, err, yargs) { - if (err) throw err // preserve stack - console.error('You broke it!') - console.error(msg) - console.error('You should be doing', yargs.help()) - process.exit(1) - }) - .argv -``` - -.getCompletion(args, done); ---------------------------- - -Allows to programmatically get completion choices for any line. - -`args`: An array of the words in the command line to complete. - -`done`: The callback to be called with the resulting completions. - -For example: - -```js -require('yargs') - .option('foobar') - .option('foobaz') - .completion() - .getCompletion(['./test.js', '--foo'], function (completions) { - console.log(completions) - }) -``` - -Outputs the same completion choices as `./test.js --foo`TAB: `--foobar` and `--foobaz` - -.global(globals) ------------- - -Indicate that an option (or group of options) should not be reset when a command -is executed, as an example: - -```js -var argv = require('yargs') - .option('a', { - alias: 'all', - default: true - }) - .option('n', { - alias: 'none', - default: true - }) - .command('foo', 'foo command', function (yargs) { - return yargs.option('b', { - alias: 'bar' - }) - }) - .help('help') - .global('a') - .argv -``` - -If the `foo` command is executed the `all` option will remain, but the `none` -option will have been eliminated. - -`help`, `version`, and `completion` options default to being global. - -.group(key(s), groupName) --------------------- - -Given a key, or an array of keys, places options under an alternative heading -when displaying usage instructions, e.g., - -```js -var yargs = require('yargs')(['--help']) - .help() - .group('batman', 'Heroes:') - .describe('batman', "world's greatest detective") - .wrap(null) - .argv -``` -*** - Heroes: - --batman world's greatest detective - - Options: - --help Show help [boolean] - -.help() ------------------------------------------ -.help([option | boolean]) ------------------------------------------ -.help([option, [description | boolean]]) ------------------------------------------ -.help([option, [description, [boolean]]]) ------------------------------------------ - -Add an option (e.g. `--help`) and implicit command that displays the usage -string and exits the process. - -If present, the `description` parameter customizes the description of -the help option in the usage string. - -If a boolean argument is provided, it will enable or disable the use of an -implicit command. The implicit command is enabled by default, but it can be -disabled by passing `false`. - -Note that any multi-char aliases (e.g. `help`) used for the help option will -also be used for the implicit command. If there are no multi-char aliases (e.g. -`h`), then all single-char aliases will be used for the command. - -If invoked without parameters, `.help()` will use `--help` as the option and -`help` as the implicit command to trigger help output. - -Example: - -```js -var yargs = require("yargs")(['--help']) - .usage("$0 -operand1 number -operand2 number -operation [add|subtract]") - .help() - .argv -``` - -Later on, `argv` can be retrieved with `yargs.argv`. - -.implies(x, y) --------------- - -Given the key `x` is set, it is required that the key `y` is set. - -Optionally `.implies()` can accept an object specifying multiple implications. - -.locale() ---------- - -Return the locale that yargs is currently using. - -By default, yargs will auto-detect the operating system's locale so that -yargs-generated help content will display in the user's language. - -To override this behavior with a static locale, pass the desired locale as a -string to this method (see below). - -.locale(locale) ---------------- - -Override the auto-detected locale from the user's operating system with a static -locale. Note that the OS locale can be modified by setting/exporting the `LC_ALL` -environment variable. - -```js -var argv = require('yargs') - .usage('./$0 - follow ye instructions true') - .option('option', { - alias: 'o', - describe: "'tis a mighty fine option", - demand: true - }) - .command('run', "Arrr, ya best be knowin' what yer doin'") - .example('$0 run foo', "shiver me timbers, here's an example for ye") - .help('help') - .wrap(70) - .locale('pirate') - .argv -``` - -*** - -```shell -./test.js - follow ye instructions true - -Choose yer command: - run Arrr, ya best be knowin' what yer doin' - -Options for me hearties! - --option, -o 'tis a mighty fine option [requi-yar-ed] - --help Parlay this here code of conduct [boolean] - -Ex. marks the spot: - test.js run foo shiver me timbers, here's an example for ye - -Ye be havin' to set the followin' argument land lubber: option -``` - -Locales currently supported: - -* **de:** German. -* **en:** American English. -* **es:** Spanish. -* **fr:** French. -* **hi:** Hindi. -* **hu:** Hungarian. -* **id:** Indonesian. -* **it:** Italian. -* **ja:** Japanese. -* **ko:** Korean. -* **nb:** Norwegian Bokmål. -* **pirate:** American Pirate. -* **pl:** Polish. -* **pt:** Portuguese. -* **pt_BR:** Brazilian Portuguese. -* **ru:** Russian. -* **th:** Thai. -* **tr:** Turkish. -* **zh_CN:** Chinese. - -To submit a new translation for yargs: - -1. use `./locales/en.json` as a starting point. -2. submit a pull request with the new locale file. - -*The [Microsoft Terminology Search](http://www.microsoft.com/Language/en-US/Search.aspx) can be useful for finding the correct terminology in your locale.* - -.nargs(key, count) ------------ - -The number of arguments that should be consumed after a key. This can be a -useful hint to prevent parsing ambiguity. For example: - -```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. - -.normalize(key) ---------------- - -The key provided represents a path and should have `path.normalize()` applied. - -.number(key) ------------- - -Tell the parser to always interpret `key` as a number. - -If `key` is an array, all elements will be parsed as numbers. - -If the option is given on the command line without a value, `argv` will be -populated with `undefined`. - -If the value given on the command line cannot be parsed as a number, `argv` will -be populated with `NaN`. - -Note that decimals, hexadecimals, and scientific notation are all accepted. - -```js -var argv = require('yargs') - .number('n') - .number(['width', 'height']) - .argv -``` - -.option(key, [opt]) ------------------ -.options(key, [opt]) ------------------- - -This method can be used to make yargs aware of options that _could_ -exist. You can also pass an `opt` object which can hold further -customization, like `.alias()`, `.demandOption()` etc. for that option. - -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') - .demandOption('f') - .default('f', '/etc/passwd') - .describe('f', 'x marks the spot') - .string('f') - .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 -; -```` - -Valid `opt` keys include: - -- `alias`: string or array of strings, alias(es) for the canonical option key, see [`alias()`](#alias) -- `array`: boolean, interpret option as an array, see [`array()`](#array) -- `boolean`: boolean, interpret option as a boolean flag, see [`boolean()`](#boolean) -- `choices`: value or array of values, limit valid option arguments to a predefined set, see [`choices()`](#choices) -- `coerce`: function, coerce or transform parsed command line values into another value, see [`coerce()`](#coerce) -- `config`: boolean, interpret option as a path to a JSON config file, see [`config()`](#config) -- `configParser`: function, provide a custom config parsing function, see [`config()`](#config) -- `count`: boolean, interpret option as a count of boolean flags, see [`count()`](#count) -- `default`: value, set a default value for the option, see [`default()`](#default) -- `defaultDescription`: string, use this description for the default value in help content, see [`default()`](#default) -- `demandOption`: boolean or string, demand the option be given, with optional error message, see [`demandOption()`](#demandOption) -- `desc`/`describe`/`description`: string, the option description for help content, see [`describe()`](#describe) -- `global`: boolean, indicate that this key should not be [reset](#reset) when a command is invoked, see [`global()`](#global) -- `group`: string, when displaying usage instructions place the option under an alternative group heading, see [`group()`](#group) -- `nargs`: number, specify how many arguments should be consumed for the option, see [`nargs()`](#nargs) -- `normalize`: boolean, apply `path.normalize()` to the option, see [`normalize()`](#normalize) -- `number`: boolean, interpret option as a number, [`number()`](#number) -- `requiresArg`: boolean, require the option be specified with a value, see [`requiresArg()`](#requiresArg) -- `skipValidation`: boolean, skips validation if the option is present, see [`skipValidation()`](#skipValidation) -- `string`: boolean, interpret option as a string, see [`string()`](#string) -- `type`: one of the following strings - - `'array'`: synonymous for `array: true`, see [`array()`](#array) - - `'boolean'`: synonymous for `boolean: true`, see [`boolean()`](#boolean) - - `'count'`: synonymous for `count: true`, see [`count()`](#count) - - `'number'`: synonymous for `number: true`, see [`number()`](#number) - - `'string'`: synonymous for `string: true`, see [`string()`](#string) - -.parse(args, [context], [parseCallback]) ------------- - -Parse `args` instead of `process.argv`. Returns the `argv` object. -`args` may either be a pre-processed argv array, or a raw argument string. - -A `context` object can optionally be given as the second argument to `parse()`, providing a -useful mechanism for passing state information to commands: - -```js -const parser = yargs - .command('lunch-train ', 'start lunch train', function () {}, function (argv) { - console.log(argv.restaurant, argv.time) - }) - .parse("lunch-train rudy's", {time: '12:15'}) -``` - -A `parseCallback` can also be provided to `.parse()`. If a callback is given, it will be invoked with three arguments: - -1. `err`: populated if any validation errors raised while parsing. -2. `argv`: the parsed argv object. -3. `output`: any text that would have been output to the terminal, had a - callback not been provided. - -```js -// providing the `fn` argument to `parse()` runs yargs in headless mode, this -// makes it easy to use yargs in contexts other than the CLI, e.g., writing -// a chat-bot. -const parser = yargs - .command('lunch-train