diff options
Diffstat (limited to 'node_modules/yargs')
40 files changed, 1870 insertions, 2276 deletions
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. +<a name="8.0.2"></a> +## [8.0.2](https://github.com/yargs/yargs/compare/v8.0.1...v8.0.2) (2017-06-12) + + + +<a name="8.0.1"></a> +## [8.0.1](https://github.com/yargs/yargs/compare/v8.0.0...v8.0.1) (2017-05-02) + + + +<a name="8.0.0"></a> +# [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. + + + +<a name="7.1.0"></a> +# [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)) + + + +<a name="7.0.2"></a> +## [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)) + + + +<a name="7.0.1"></a> +## [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)) + + + +<a name="7.0.0"></a> +# [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. + + + <a name="6.6.0"></a> # [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!'); -} -```` - -*** +> Yargs be a node.js library fer hearties tryin' ter parse optstrings. - $ ./plunder.js --ships=4 --distance=22 - Plunder more riffiwobbles! +<img width="250" src="/yargs-logo.png"> - $ ./plunder.js --ships 12 --distance 98.7 - Retreat from the xupptumblers! +Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface. It gives you: - +* commands and (grouped) options (`my-program.js serve --port=5000`). +* a dynamically generated help menu based on your arguments. -But don't walk the plank just yet! There be more! You can do short options: -------------------------------------------------- +> <img width="400" src="/screen.png"> -short.js: +* bash-completion shortcuts for commands and options. +* and [tons more](/docs/api.md). -````javascript -#!/usr/bin/env node -var argv = require('yargs').argv; -console.log('(%d,%d)', argv.x, argv.y); -```` +## Installation -*** - - $ ./short.js -x 10 -y 21 - (10,21) - -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 <command> [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 <command> [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`. - -<a name="alias"></a>.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. - -<a name="array"></a>.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'`. - -<a name="boolean"></a>.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. - -<a name="choices"></a>.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 -``` - -<a name="coerce"></a>.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 `<foo>`, and optional arguments -take the form `[bar]`. The parsed positional arguments will be populated in -`argv`: - -```js -yargs.command('get <source> [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 <username|email> [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: - -```js -yargs.command('download <url> [files..]', 'download several files') - .help() - .argv -``` - -### 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. - -```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') - }) - .command({ - command: 'configure <key> [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}`) - } - }) - .demandCommand(1) - .help() - .wrap(72) - .argv -``` - -``` -$ ./svc.js help -Commands: - start [app] Start up an app [aliases: run, up] - configure <key> [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 <source> [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 <source> [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 <command>' -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 <name> <url>' -exports.desc = 'Add remote named <name> for repo at url <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 <name> [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; -``` - -<a name="config"></a>.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' } -``` - -<a name="conflicts"></a>.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. - -<a name="count"></a>.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`. - -<a name="default"></a>.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)') -``` - -<a name="demand"></a>.demand(count, [max], [msg]) [DEPRECATED] --------------------- - -`demand()` has been deprecated, please instead see [`demandOption()`](#demandOption) and -[`demandCommand()`](#demandCommand). - -<a name="demandOption"></a>.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 -``` - -<a name="demandCommand"></a>.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 <key> [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 <key> [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._ - -<a name="describe"></a>.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. - -<a name="exitprocess"></a>.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. - -<a name="fail"></a>.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`<kbd>TAB</kbd>: `--foobar` and `--foobaz` - -<a name="global"></a>.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. - -<a name="group"></a>.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] - -<a name="help"></a>.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). +$ ./plunder.js --ships=4 --distance=22 +Plunder more riffiwobbles! -.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.* - -<a name="nargs"></a>.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']); +$ ./plunder.js --ships 12 --distance 98.7 +Retreat from the xupptumblers! ``` -parses as: - -`{ _: [], token: '-my-token', '$0': 'node test' }` - -Optionally `.nargs()` can take an object of `key`/`narg` pairs. - -<a name="normalize"></a>.normalize(key) ---------------- - -The key provided represents a path and should have `path.normalize()` applied. - -<a name="number"></a>.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. +## Complex Example ```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 <restaurant>', 'start lunch train', function () {}, function (argv) { - console.log(argv.restaurant, argv.time) +#!/usr/bin/env node +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) }) - .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 <restaurant> <time>', 'start lunch train', function () {}, function (argv) { - api.scheduleLunch(argv.restaurant, moment(argv.time)) + .option('verbose', { + alias: 'v', + default: false }) .help() - -parser.parse(bot.userText, function (err, argv, output) { - if (output) bot.respond(output) -}) -``` - -***Note:*** Providing a callback to `parse()` disables the [`exitProcess` setting](#exitprocess) until after the callback is invoked. - -.pkgConf(key, [cwd]) ------------- - -Similar to [`config()`](#config), indicates that yargs should interpret the object from the specified key in package.json -as a configuration object. - -`cwd` can optionally be provided, the package.json will be read -from this location. - -.recommendCommands() ---------------------------- - -Should yargs provide suggestions regarding similar commands if no matching -command is found? - -.require(key, [msg | boolean]) ------------------------------- -.required(key, [msg | boolean]) ------------------------------- - -An alias for [`demand()`](#demand). See docs there. - -<a name="requiresArg"></a>.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 behavior is to set the value of any key not followed by an -option value to `true`. - -<a name="reset"></a>.reset() --------- - -Reset the argument object built up so far. This is useful for -creating nested command line interfaces. Use [global](#global) -to specify keys that should not be reset. - -```js -var yargs = require('yargs') - .usage('$0 command') - .command('hello', 'hello command') - .command('world', 'world command') - .demandCommand(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(); -} -``` - -.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. - -.showHelp(consoleLevel='error') ---------------------------- - -Print the usage data using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel` for printing. - -Example: - -```js -var yargs = require("yargs") - .usage("$0 -operand1 number -operand2 number -operation [add|subtract]"); -yargs.showHelp(); //prints to stderr using console.error() -``` - -Or, to print the usage data to `stdout` instead, you can specify the use of `console.log`: - -```js -yargs.showHelp("log"); //prints to stdout using console.log() -``` - -Later on, `argv` can be retrieved with `yargs.argv`. - -.showHelpOnFail(enable, [message]) ----------------------------------- - -By default, yargs outputs a usage string if any error is detected. Use the -`.showHelpOnFail()` method to customize this behavior. 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 -f <file>') - .demandOption('f') - .alias('f', 'file') - .describe('f', 'Load a file') - .string('f') - .showHelpOnFail(false, 'Specify --help for available options') - .help('help') - .argv; - -// etc. -```` - -*** - -``` -$ node line_count.js -Missing argument value: f - -Specify --help for available options -``` - -<a name="skipValidation"></a>.skipValidation(key) ------------------ - -Specifies either a single option key (string), or an array of options. -If any of the options is present, yargs validation is skipped. - -.strict() ---------- - -Any command-line argument given that is not demanded, or does not have a -corresponding description, will be reported as an error. - -<a name="string"></a>.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. - -.updateLocale(obj) ------------------- -.updateStrings(obj) ------------------- - -Override the default strings used by yargs with the key/value -pairs provided in `obj`: - -```js -var argv = require('yargs') - .command('run', 'the run command') - .help('help') - .updateStrings({ - 'Commands:': 'My Commands -->\n' - }) - .wrap(null) .argv ``` -*** - -```shell -My Commands --> - - run the run command - -Options: - --help Show help [boolean] -``` - -If you explicitly specify a `locale()`, you should do so *before* calling -`updateStrings()`. - -.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)`. - -<a name="version"></a>.version([option], [description], [version]) ----------------------------------------- - -Add an option (e.g. `--version`) that displays the version number (given by the -`version` parameter) and exits the process. - -If no arguments are passed to `version` (`.version()`), yargs will parse the `package.json` -of your module and use its `version` value. The default value of `option` is `--version`. - -You can provide a `function` for version, rather than a string. -This is useful if you want to use a version stored in a location other than package.json: - -```js -var argv = require('yargs') - .version(function() { - return require('../lib/version').version; - }) - .argv; -``` - -<a name="wrap"></a>.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 (no right-align). Use `.wrap(yargs.terminalWidth())` to -maximize the width of yargs' usage instructions. - -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' ], - a: 1, - b: 2, - '$0': 'examples/reflect.js' } - -negate fields -------------- - -If you want to explicitly 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 - { _: [], a: true, b: false, '$0': 'examples/reflect.js' } - -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 - { _: [], x: [ 5, 8, 0 ], '$0': 'examples/reflect.js' } - -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 - { _: [], - foo: { bar: { baz: 33 }, quux: 5 }, - '$0': 'examples/reflect.js' } - -short numbers -------------- - -Short numeric `-n5` style arguments work too: - - $ node examples/reflect.js -n123 -m456 - { _: [], n: 123, m: 456, '$0': 'examples/reflect.js' } - -installation -============ - -With [npm](https://github.com/npm/npm), just do: - - npm install yargs - -or clone this project on github: - - git clone http://github.com/yargs/yargs.git - -To run the tests with npm, just do: - - npm test - -configuration -============= - -Using the `yargs` stanza in your `package.json` you can turn on and off -some of yargs' parsing features: - -```json -{ - "yargs": { - "short-option-groups": true, - "camel-case-expansion": true, - "dot-notation": true, - "parse-numbers": true, - "boolean-negation": true - } -} -``` - -See the [yargs-parser](https://github.com/yargs/yargs-parser#configuration) module -for detailed documentation of this feature. - -inspired by -=========== +## Table of Contents -This module is loosely inspired by Perl's -[Getopt::Casual](http://search.cpan.org/~photo/Getopt-Casual-0.13.1/Casual.pm). +* [Yargs' API](/docs/api.md) +* [Examples](/docs/examples.md) +* [Parsing Tricks](/docs/tricks.md) + * [Stop the Parser](/docs/tricks.md#stop) + * [Negating Boolean Arguments](/docs/tricks.md#negate) + * [Numbers](/docs/tricks.md#numbers) + * [Arrays](/docs/tricks.md#arrays) + * [Objects](/docs/tricks.md#objects) +* [Advanced Topics](/docs/advanced.md) + * [Composing Your App Using Commands](/docs/advanced.md#commands) + * [Building Configurable CLI Apps](/docs/advanced.md#configuration) + * [Customizing Yargs' Parser](/docs/advanced.md#customizing) +* [Contributing](/contributing.md) [travis-url]: https://travis-ci.org/yargs/yargs [travis-image]: https://img.shields.io/travis/yargs/yargs/master.svg @@ -1975,7 +97,7 @@ This module is loosely inspired by Perl's [windows-image]: https://img.shields.io/appveyor/ci/bcoe/yargs-ljwvf/master.svg?label=Windows%20Tests [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg [standard-url]: http://standardjs.com/ -[standard-version-image]: https://img.shields.io/badge/release-standard%20version-brightgreen.svg -[standard-version-url]: https://github.com/conventional-changelog/standard-version +[conventional-commits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg +[conventional-commits-url]: https://conventionalcommits.org/ [gitter-image]: https://img.shields.io/gitter/room/nwjs/nw.js.svg?maxAge=2592000 [gitter-url]: https://gitter.im/yargs/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link diff --git a/node_modules/yargs/lib/apply-extends.js b/node_modules/yargs/lib/apply-extends.js new file mode 100644 index 000000000..5fc69fab1 --- /dev/null +++ b/node_modules/yargs/lib/apply-extends.js @@ -0,0 +1,52 @@ +var fs = require('fs') +var path = require('path') +var assign = require('./assign') +var YError = require('./yerror') + +var previouslyVisitedConfigs = [] + +function checkForCircularExtends (path) { + if (previouslyVisitedConfigs.indexOf(path) > -1) { + throw new YError("Circular extended configurations: '" + path + "'.") + } +} + +function getPathToDefaultConfig (cwd, pathToExtend) { + return path.resolve(cwd, pathToExtend) +} + +function applyExtends (config, cwd) { + var defaultConfig = {} + + if (config.hasOwnProperty('extends')) { + if (typeof config.extends !== 'string') return defaultConfig + var isPath = /\.json$/.test(config.extends) + var pathToDefault = null + if (!isPath) { + try { + pathToDefault = require.resolve(config.extends) + } catch (err) { + // most likely this simply isn't a module. + } + } else { + pathToDefault = getPathToDefaultConfig(cwd, config.extends) + } + // maybe the module uses key for some other reason, + // err on side of caution. + if (!pathToDefault && !isPath) return config + + checkForCircularExtends(pathToDefault) + + previouslyVisitedConfigs.push(pathToDefault) + + defaultConfig = isPath ? JSON.parse(fs.readFileSync(pathToDefault, 'utf8')) : require(config.extends) + delete config.extends + defaultConfig = applyExtends(defaultConfig, path.dirname(pathToDefault)) + } + + previouslyVisitedConfigs = [] + + return assign(defaultConfig, config) +} + +module.exports = applyExtends diff --git a/node_modules/yargs/lib/argsert.js b/node_modules/yargs/lib/argsert.js new file mode 100644 index 000000000..d3e72fce5 --- /dev/null +++ b/node_modules/yargs/lib/argsert.js @@ -0,0 +1,72 @@ +const command = require('./command')() +const YError = require('./yerror') + +const positionName = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth'] + +module.exports = function (expected, callerArguments, length) { + // TODO: should this eventually raise an exception. + try { + // preface the argument description with "cmd", so + // that we can run it through yargs' command parser. + var position = 0 + var parsed = {demanded: [], optional: []} + if (typeof expected === 'object') { + length = callerArguments + callerArguments = expected + } else { + parsed = command.parseCommand('cmd ' + expected) + } + const args = [].slice.call(callerArguments) + + while (args.length && args[args.length - 1] === undefined) args.pop() + length = length || args.length + + if (length < parsed.demanded.length) { + throw new YError('Not enough arguments provided. Expected ' + parsed.demanded.length + + ' but received ' + args.length + '.') + } + + const totalCommands = parsed.demanded.length + parsed.optional.length + if (length > totalCommands) { + throw new YError('Too many arguments provided. Expected max ' + totalCommands + + ' but received ' + length + '.') + } + + parsed.demanded.forEach(function (demanded) { + const arg = args.shift() + const observedType = guessType(arg) + const matchingTypes = demanded.cmd.filter(function (type) { + return type === observedType || type === '*' + }) + if (matchingTypes.length === 0) argumentTypeError(observedType, demanded.cmd, position, false) + position += 1 + }) + + parsed.optional.forEach(function (optional) { + if (args.length === 0) return + const arg = args.shift() + const observedType = guessType(arg) + const matchingTypes = optional.cmd.filter(function (type) { + return type === observedType || type === '*' + }) + if (matchingTypes.length === 0) argumentTypeError(observedType, optional.cmd, position, true) + position += 1 + }) + } catch (err) { + console.warn(err.stack) + } +} + +function guessType (arg) { + if (Array.isArray(arg)) { + return 'array' + } else if (arg === null) { + return 'null' + } + return typeof arg +} + +function argumentTypeError (observedType, allowedTypes, position, optional) { + throw new YError('Invalid ' + (positionName[position] || 'manyith') + ' argument.' + + ' Expected ' + allowedTypes.join(' or ') + ' but received ' + observedType + '.') +} diff --git a/node_modules/yargs/lib/command.js b/node_modules/yargs/lib/command.js index c1afc1c55..3567cf953 100644 --- a/node_modules/yargs/lib/command.js +++ b/node_modules/yargs/lib/command.js @@ -2,6 +2,8 @@ const path = require('path') const inspect = require('util').inspect const camelCase = require('camelcase') +const DEFAULT_MARKER = '*' + // handles parsing positional arguments, // and populating argv with said positional // arguments. @@ -10,8 +12,11 @@ module.exports = function (yargs, usage, validation) { var handlers = {} var aliasMap = {} + var defaultCommand self.addHandler = function (cmd, description, builder, handler) { var aliases = [] + handler = handler || function () {} + if (Array.isArray(cmd)) { aliases = cmd.slice(1) cmd = cmd[0] @@ -28,15 +33,50 @@ module.exports = function (yargs, usage, validation) { return } - var parsedCommand = parseCommand(cmd) + // parse positionals out of cmd string + var parsedCommand = self.parseCommand(cmd) + + // remove positional args from aliases only aliases = aliases.map(function (alias) { - alias = parseCommand(alias).cmd // remove positional args + return self.parseCommand(alias).cmd + }) + + // check for default and filter out '*'' + var isDefault = false + var parsedAliases = [parsedCommand.cmd].concat(aliases).filter(function (c) { + if (c === DEFAULT_MARKER) { + isDefault = true + return false + } + return true + }) + + // short-circuit if default with no aliases + if (isDefault && parsedAliases.length === 0) { + defaultCommand = { + original: cmd.replace(DEFAULT_MARKER, '').trim(), + handler: handler, + builder: builder || {}, + demanded: parsedCommand.demanded, + optional: parsedCommand.optional + } + return + } + + // shift cmd and aliases after filtering out '*' + if (isDefault) { + parsedCommand.cmd = parsedAliases[0] + aliases = parsedAliases.slice(1) + cmd = cmd.replace(DEFAULT_MARKER, parsedCommand.cmd) + } + + // populate aliasMap + aliases.forEach(function (alias) { aliasMap[alias] = parsedCommand.cmd - return alias }) if (description !== false) { - usage.command(cmd, description, aliases) + usage.command(cmd, description, isDefault, aliases) } handlers[parsedCommand.cmd] = { @@ -46,6 +86,8 @@ module.exports = function (yargs, usage, validation) { demanded: parsedCommand.demanded, optional: parsedCommand.optional } + + if (isDefault) defaultCommand = handlers[parsedCommand.cmd] } self.addDirectory = function (dir, context, req, callerFile, opts) { @@ -94,7 +136,7 @@ module.exports = function (yargs, usage, validation) { return false } - function parseCommand (cmd) { + self.parseCommand = function (cmd) { var extraSpacesStrippedCommand = cmd.replace(/\s{2,}/g, ' ') var splitCommand = extraSpacesStrippedCommand.split(/\s+(?![^[]*]|[^<]*>)/) var bregex = /\.*[\][<>]/g @@ -130,48 +172,71 @@ module.exports = function (yargs, usage, validation) { return handlers } - self.runCommand = function (command, yargs, parsed) { - var argv = parsed.argv - var commandHandler = handlers[command] || handlers[aliasMap[command]] - var innerArgv = argv + self.hasDefaultCommand = function () { + return !!defaultCommand + } + + self.runCommand = function (command, yargs, parsed, commandIndex) { + var aliases = parsed.aliases + var commandHandler = handlers[command] || handlers[aliasMap[command]] || defaultCommand var currentContext = yargs.getContext() var numFiles = currentContext.files.length var parentCommands = currentContext.commands.slice() - currentContext.commands.push(command) + + // what does yargs look like after the buidler is run? + var innerArgv = parsed.argv + var innerYargs = null + var positionalMap = {} + + if (command) currentContext.commands.push(command) if (typeof commandHandler.builder === 'function') { // a function can be provided, which builds // up a yargs chain and possibly returns it. - innerArgv = commandHandler.builder(yargs.reset(parsed.aliases)) + innerYargs = commandHandler.builder(yargs.reset(parsed.aliases)) // if the builder function did not yet parse argv with reset yargs // and did not explicitly set a usage() string, then apply the // original command string as usage() for consistent behavior with - // options object below + // options object below. if (yargs.parsed === false) { if (typeof yargs.getUsageInstance().getUsage() === 'undefined') { yargs.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original) } - innerArgv = innerArgv ? innerArgv.argv : yargs.argv + innerArgv = innerYargs ? innerYargs._parseArgs(null, null, true, commandIndex) : yargs._parseArgs(null, null, true, commandIndex) } else { innerArgv = yargs.parsed.argv } + + if (innerYargs && yargs.parsed === false) aliases = innerYargs.parsed.aliases + else aliases = yargs.parsed.aliases } else if (typeof commandHandler.builder === 'object') { // as a short hand, an object can instead be provided, specifying // the options that a command takes. - innerArgv = yargs.reset(parsed.aliases) - innerArgv.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original) + innerYargs = yargs.reset(parsed.aliases) + innerYargs.usage('$0 ' + (parentCommands.length ? parentCommands.join(' ') + ' ' : '') + commandHandler.original) Object.keys(commandHandler.builder).forEach(function (key) { - innerArgv.option(key, commandHandler.builder[key]) + innerYargs.option(key, commandHandler.builder[key]) }) - innerArgv = innerArgv.argv + innerArgv = innerYargs._parseArgs(null, null, true, commandIndex) + aliases = innerYargs.parsed.aliases + } + + if (!yargs._hasOutput()) { + positionalMap = populatePositionals(commandHandler, innerArgv, currentContext, yargs) } - if (!yargs._hasOutput()) populatePositionals(commandHandler, innerArgv, currentContext, yargs) + + // we apply validation post-hoc, so that custom + // checks get passed populated positional arguments. + if (!yargs._hasOutput()) yargs._runValidation(innerArgv, aliases, positionalMap, yargs.parsed.error) if (commandHandler.handler && !yargs._hasOutput()) { + yargs._setHasOutput() commandHandler.handler(innerArgv) } - currentContext.commands.pop() + + if (command) currentContext.commands.pop() numFiles = currentContext.files.length - numFiles if (numFiles > 0) currentContext.files.splice(numFiles * -1, numFiles) + return innerArgv } @@ -181,25 +246,27 @@ module.exports = function (yargs, usage, validation) { argv._ = argv._.slice(context.commands.length) // nuke the current commands var demanded = commandHandler.demanded.slice(0) var optional = commandHandler.optional.slice(0) + var positionalMap = {} validation.positionalCount(demanded.length, argv._.length) while (demanded.length) { var demand = demanded.shift() - populatePositional(demand, argv, yargs) + populatePositional(demand, argv, yargs, positionalMap) } while (optional.length) { var maybe = optional.shift() - populatePositional(maybe, argv, yargs) + populatePositional(maybe, argv, yargs, positionalMap) } argv._ = context.commands.concat(argv._) + return positionalMap } // populate a single positional argument and its // aliases onto argv. - function populatePositional (positional, argv, yargs) { + function populatePositional (positional, argv, yargs, positionalMap) { // "positional" consists of the positional.cmd, an array representing // the positional's name and aliases, and positional.variadic // indicating whether or not it is a variadic array. @@ -214,6 +281,7 @@ module.exports = function (yargs, usage, validation) { if (value) argv[cmd] = value else argv[cmd] = value = argv._.shift() } + positionalMap[cmd] = true postProcessPositional(yargs, argv, cmd) addCamelCaseExpansions(argv, cmd) } @@ -242,6 +310,7 @@ module.exports = function (yargs, usage, validation) { self.reset = function () { handlers = {} aliasMap = {} + defaultCommand = undefined return self } @@ -254,10 +323,12 @@ module.exports = function (yargs, usage, validation) { frozen = {} frozen.handlers = handlers frozen.aliasMap = aliasMap + frozen.defaultCommand = defaultCommand } self.unfreeze = function () { handlers = frozen.handlers aliasMap = frozen.aliasMap + defaultCommand = frozen.defaultCommand frozen = undefined } diff --git a/node_modules/yargs/lib/completion.js b/node_modules/yargs/lib/completion.js index 93a936cf6..5cd9a18a0 100644 --- a/node_modules/yargs/lib/completion.js +++ b/node_modules/yargs/lib/completion.js @@ -44,7 +44,12 @@ module.exports = function (yargs, usage, command) { var handlers = command.getCommandHandlers() for (var i = 0, ii = args.length; i < ii; ++i) { if (handlers[args[i]] && handlers[args[i]].builder) { - return handlers[args[i]].builder(yargs.reset()).argv + const builder = handlers[args[i]].builder + if (typeof builder === 'function') { + const y = yargs.reset() + builder(y) + return y.argv + } } } diff --git a/node_modules/yargs/lib/usage.js b/node_modules/yargs/lib/usage.js index 555ffb52b..43f71225c 100644 --- a/node_modules/yargs/lib/usage.js +++ b/node_modules/yargs/lib/usage.js @@ -3,6 +3,7 @@ const stringWidth = require('string-width') const objFilter = require('./obj-filter') const setBlocking = require('set-blocking') +const YError = require('./yerror') module.exports = function (yargs, y18n) { const __ = y18n.__ @@ -50,7 +51,7 @@ module.exports = function (yargs, y18n) { } } - err = err || new Error(msg) + err = err || new YError(msg) if (yargs.getExitProcess()) { return yargs.exit(1) } else if (yargs._hasParseCallback()) { @@ -76,8 +77,15 @@ module.exports = function (yargs, y18n) { } var commands = [] - self.command = function (cmd, description, aliases) { - commands.push([cmd, description || '', aliases]) + self.command = function (cmd, description, isDefault, aliases) { + // the last default wins, so cancel out any previously set default + if (isDefault) { + commands = commands.map(function (cmdArray) { + cmdArray[2] = false + return cmdArray + }) + } + commands.push([cmd, description || '', isDefault, aliases]) } self.getCommands = function () { return commands @@ -165,8 +173,13 @@ module.exports = function (yargs, y18n) { {text: command[0], padding: [0, 2, 0, 2], width: maxWidth(commands, theWrap) + 4}, {text: command[1]} ) - if (command[2] && command[2].length) { - ui.div({text: '[' + __('aliases:') + ' ' + command[2].join(', ') + ']', padding: [0, 0, 0, 2], align: 'right'}) + var hints = [] + if (command[2]) hints.push('[' + __('default:').slice(0, -1) + ']') // TODO hacking around i18n here + if (command[3] && command[3].length) { + hints.push('[' + __('aliases:') + ' ' + command[3].join(', ') + ']') + } + if (hints.length) { + ui.div({text: hints.join(' '), padding: [0, 0, 0, 2], align: 'right'}) } else { ui.div() } @@ -234,7 +247,7 @@ module.exports = function (yargs, y18n) { var extra = [ type, - demandedOptions[key] ? '[' + __('required') + ']' : null, + (key in demandedOptions) ? '[' + __('required') + ']' : null, options.choices && options.choices[key] ? '[' + __('choices:') + ' ' + self.stringifiedValues(options.choices[key]) + ']' : null, defaultString(options.default[key], options.defaultDescription[key]) @@ -261,10 +274,24 @@ module.exports = function (yargs, y18n) { }) examples.forEach(function (example) { - ui.div( - {text: example[0], padding: [0, 2, 0, 2], width: maxWidth(examples, theWrap) + 4}, - example[1] - ) + if (example[1] === '') { + ui.div( + { + text: example[0], + padding: [0, 2, 0, 2] + } + ) + } else { + ui.div( + { + text: example[0], + padding: [0, 2, 0, 2], + width: maxWidth(examples, theWrap) + 4 + }, { + text: example[1] + } + ) + } }) ui.div() @@ -315,7 +342,7 @@ module.exports = function (yargs, y18n) { // copy descriptions. if (descriptions[alias]) self.describe(key, descriptions[alias]) // copy demanded. - if (demandedOptions[alias]) yargs.demandOption(key, demandedOptions[alias].msg) + if (alias in demandedOptions) yargs.demandOption(key, demandedOptions[alias]) // type messages. if (~options.boolean.indexOf(alias)) yargs.boolean(key) if (~options.count.indexOf(alias)) yargs.count(key) @@ -421,7 +448,7 @@ module.exports = function (yargs, y18n) { else logger.log(version) } - self.reset = function (globalLookup) { + self.reset = function (localLookup) { // do not reset wrap here // do not reset fails here failMessage = null @@ -431,7 +458,7 @@ module.exports = function (yargs, y18n) { examples = [] commands = [] descriptions = objFilter(descriptions, function (k, v) { - return globalLookup[k] + return !localLookup[k] }) return self } diff --git a/node_modules/yargs/lib/validation.js b/node_modules/yargs/lib/validation.js index 328d83aff..2f9ff8e6c 100644 --- a/node_modules/yargs/lib/validation.js +++ b/node_modules/yargs/lib/validation.js @@ -1,4 +1,5 @@ const objFilter = require('./obj-filter') +const specialKeys = ['$0', '--', '_'] // validation-type-stuff, missing params, // bad implications, custom checks. @@ -89,7 +90,7 @@ module.exports = function (yargs, usage, y18n) { var missing = null Object.keys(demandedOptions).forEach(function (key) { - if (!argv.hasOwnProperty(key)) { + if (!argv.hasOwnProperty(key) || typeof argv[key] === 'undefined') { missing = missing || {} missing[key] = demandedOptions[key] } @@ -98,7 +99,7 @@ module.exports = function (yargs, usage, y18n) { if (missing) { const customMsgs = [] Object.keys(missing).forEach(function (key) { - const msg = missing[key].msg + const msg = missing[key] if (msg && customMsgs.indexOf(msg) < 0) { customMsgs.push(msg) } @@ -116,7 +117,7 @@ module.exports = function (yargs, usage, y18n) { } // check for unknown arguments (strict-mode). - self.unknownArguments = function (argv, aliases) { + self.unknownArguments = function (argv, aliases, positionalMap) { const aliasLookup = {} const descriptions = usage.getDescriptions() const demandedOptions = yargs.getDemandedOptions() @@ -131,9 +132,11 @@ module.exports = function (yargs, usage, y18n) { }) Object.keys(argv).forEach(function (key) { - if (key !== '$0' && key !== '_' && + if (specialKeys.indexOf(key) === -1 && !descriptions.hasOwnProperty(key) && !demandedOptions.hasOwnProperty(key) && + !positionalMap.hasOwnProperty(key) && + !yargs._getParseContext().hasOwnProperty(key) && !aliasLookup.hasOwnProperty(key)) { unknown.push(key) } @@ -165,7 +168,7 @@ module.exports = function (yargs, usage, y18n) { if (!Object.keys(options.choices).length) return Object.keys(argv).forEach(function (key) { - if (key !== '$0' && key !== '_' && + if (specialKeys.indexOf(key) === -1 && options.choices.hasOwnProperty(key)) { [].concat(argv[key]).forEach(function (value) { // TODO case-insensitive configurability @@ -194,22 +197,26 @@ module.exports = function (yargs, usage, y18n) { // custom checks, added using the `check` option on yargs. var checks = [] - self.check = function (f) { - checks.push(f) + self.check = function (f, global) { + checks.push({ + func: f, + global: global + }) } self.customChecks = function (argv, aliases) { for (var i = 0, f; (f = checks[i]) !== undefined; i++) { + var func = f.func var result = null try { - result = f(argv, aliases) + result = func(argv, aliases) } catch (err) { usage.fail(err.message ? err.message : err, err) continue } if (!result) { - usage.fail(__('Argument check failed: %s', f.toString())) + usage.fail(__('Argument check failed: %s', func.toString())) } else if (typeof result === 'string' || result instanceof Error) { usage.fail(result.toString(), result) } @@ -224,6 +231,7 @@ module.exports = function (yargs, usage, y18n) { self.implies(k, key[k]) }) } else { + yargs.global(key) implied[key] = value } } @@ -290,6 +298,7 @@ module.exports = function (yargs, usage, y18n) { self.conflicts(k, key[k]) }) } else { + yargs.global(key) conflicting[key] = value } } @@ -324,12 +333,16 @@ module.exports = function (yargs, usage, y18n) { if (recommended) usage.fail(__('Did you mean %s?', recommended)) } - self.reset = function (globalLookup) { + self.reset = function (localLookup) { implied = objFilter(implied, function (k, v) { - return globalLookup[k] + return !localLookup[k] + }) + conflicting = objFilter(conflicting, function (k, v) { + return !localLookup[k] + }) + checks = checks.filter(function (c) { + return c.global }) - checks = [] - conflicting = {} return self } diff --git a/node_modules/yargs/lib/yerror.js b/node_modules/yargs/lib/yerror.js new file mode 100644 index 000000000..ad96a8776 --- /dev/null +++ b/node_modules/yargs/lib/yerror.js @@ -0,0 +1,10 @@ +function YError (msg) { + this.name = 'YError' + this.message = msg || 'yargs error' + Error.captureStackTrace(this, YError) +} + +YError.prototype = Object.create(Error.prototype) +YError.prototype.constructor = YError + +module.exports = YError diff --git a/node_modules/yargs/locales/zh_TW.json b/node_modules/yargs/locales/zh_TW.json new file mode 100644 index 000000000..12498888a --- /dev/null +++ b/node_modules/yargs/locales/zh_TW.json @@ -0,0 +1,40 @@ +{ + "Commands:": "命令：", + "Options:": "選項：", + "Examples:": "例：", + "boolean": "布林", + "count": "次數", + "string": "字串", + "number": "數字", + "array": "陣列", + "required": "必須", + "default:": "預設值:", + "choices:": "可選值:", + "aliases:": "別名:", + "generated-value": "生成的值", + "Not enough non-option arguments: got %s, need at least %s": "non-option 引數不足：只傳入了 %s 個, 至少要 %s 個", + "Too many non-option arguments: got %s, maximum of %s": "non-option 引數過多：傳入了 %s 個, 但最多 %s 個", + "Missing argument value: %s": { + "one": "此引數無指定值：%s", + "other": "這些引數無指定值：%s" + }, + "Missing required argument: %s": { + "one": "缺少必須的引數：%s", + "other": "缺少這些必須的引數：%s" + }, + "Unknown argument: %s": { + "one": "未知的引數：%s", + "other": "未知的這些引數：%s" + }, + "Invalid values:": "無效的選項值：", + "Argument: %s, Given: %s, Choices: %s": "引數名稱: %s, 傳入的值: %s, 可選的值：%s", + "Argument check failed: %s": "引數驗證失敗：%s", + "Implications failed:": "缺少依賴的選項：", + "Not enough arguments following: %s": "沒有提供足夠的值給此引數：%s", + "Invalid JSON config file: %s": "無效的 JSON 設置文件：%s", + "Path to JSON config file": "JSON 設置文件的路徑", + "Show help": "顯示說明", + "Show version number": "顯示版本", + "Did you mean %s?": "是指 %s?", + "Arguments %s and %s are mutually exclusive" : "引數 %s 和 %s 是互斥的" +} diff --git a/node_modules/yargs/node_modules/ansi-regex/index.js b/node_modules/yargs/node_modules/ansi-regex/index.js new file mode 100644 index 000000000..c4aaecf50 --- /dev/null +++ b/node_modules/yargs/node_modules/ansi-regex/index.js @@ -0,0 +1,10 @@ +'use strict'; + +module.exports = () => { + const pattern = [ + '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[a-zA-Z\\d]*)*)?\\u0007)', + '(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PRZcf-ntqry=><~]))' + ].join('|'); + + return new RegExp(pattern, 'g'); +}; diff --git a/node_modules/yargs/node_modules/ansi-regex/license b/node_modules/yargs/node_modules/ansi-regex/license new file mode 100644 index 000000000..e7af2f771 --- /dev/null +++ b/node_modules/yargs/node_modules/ansi-regex/license @@ -0,0 +1,9 @@ +MIT License + +Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/node_modules/yargs/node_modules/ansi-regex/package.json b/node_modules/yargs/node_modules/ansi-regex/package.json new file mode 100644 index 000000000..e94852fd7 --- /dev/null +++ b/node_modules/yargs/node_modules/ansi-regex/package.json @@ -0,0 +1,53 @@ +{ + "name": "ansi-regex", + "version": "3.0.0", + "description": "Regular expression for matching ANSI escape codes", + "license": "MIT", + "repository": "chalk/ansi-regex", + "author": { + "name": "Sindre Sorhus", + "email": "sindresorhus@gmail.com", + "url": "sindresorhus.com" + }, + "engines": { + "node": ">=4" + }, + "scripts": { + "test": "xo && ava", + "view-supported": "node fixtures/view-codes.js" + }, + "files": [ + "index.js" + ], + "keywords": [ + "ansi", + "styles", + "color", + "colour", + "colors", + "terminal", + "console", + "cli", + "string", + "tty", + "escape", + "formatting", + "rgb", + "256", + "shell", + "xterm", + "command-line", + "text", + "regex", + "regexp", + "re", + "match", + "test", + "find", + "pattern" + ], + "devDependencies": { + "ava": "*", + "xo": "*" + } +} diff --git a/node_modules/yargs/node_modules/ansi-regex/readme.md b/node_modules/yargs/node_modules/ansi-regex/readme.md new file mode 100644 index 000000000..22db1c340 --- /dev/null +++ b/node_modules/yargs/node_modules/ansi-regex/readme.md @@ -0,0 +1,46 @@ +# ansi-regex [](https://travis-ci.org/chalk/ansi-regex) + +> Regular expression for matching [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) + + +## Install + +``` +$ npm install ansi-regex +``` + + +## Usage + +```js +const ansiRegex = require('ansi-regex'); + +ansiRegex().test('\u001B[4mcake\u001B[0m'); +//=> true + +ansiRegex().test('cake'); +//=> false + +'\u001B[4mcake\u001B[0m'.match(ansiRegex()); +//=> ['\u001B[4m', '\u001B[0m'] +``` + + +## FAQ + +### Why do you test for codes not in the ECMA 48 standard? + +Some of the codes we run as a test are codes that we acquired finding various lists of non-standard or manufacturer specific codes. We test for both standard and non-standard codes, as most of them follow the same or similar format and can be safely matched in strings without the risk of removing actual string content. There are a few non-standard control codes that do not follow the traditional format (i.e. they end in numbers) thus forcing us to exclude them from the test because we cannot reliably match them. + +On the historical side, those ECMA standards were established in the early 90's whereas the VT100, for example, was designed in the mid/late 70's. At that point in time, control codes were still pretty ungoverned and engineers used them for a multitude of things, namely to activate hardware ports that may have been proprietary. Somewhere else you see a similar 'anarchy' of codes is in the x86 architecture for processors; there are a ton of "interrupts" that can mean different things on certain brands of processors, most of which have been phased out. + + +## Maintainers + +- [Sindre Sorhus](https://github.com/sindresorhus) +- [Josh Junon](https://github.com/qix-) + + +## License + +MIT diff --git a/node_modules/yargs/node_modules/path-type/index.js b/node_modules/yargs/node_modules/path-type/index.js new file mode 100644 index 000000000..4ac9dd967 --- /dev/null +++ b/node_modules/yargs/node_modules/path-type/index.js @@ -0,0 +1,26 @@ +'use strict'; +const fs = require('fs'); +const pify = require('pify'); + +function type(fn, fn2, fp) { + if (typeof fp !== 'string') { + return Promise.reject(new TypeError(`Expected a string, got ${typeof fp}`)); + } + + return pify(fs[fn])(fp).then(stats => stats[fn2]()); +} + +function typeSync(fn, fn2, fp) { + if (typeof fp !== 'string') { + throw new TypeError(`Expected a string, got ${typeof fp}`); + } + + return fs[fn](fp)[fn2](); +} + +exports.file = type.bind(null, 'stat', 'isFile'); +exports.dir = type.bind(null, 'stat', 'isDirectory'); +exports.symlink = type.bind(null, 'lstat', 'isSymbolicLink'); +exports.fileSync = typeSync.bind(null, 'statSync', 'isFile'); +exports.dirSync = typeSync.bind(null, 'statSync', 'isDirectory'); +exports.symlinkSync = typeSync.bind(null, 'lstatSync', 'isSymbolicLink'); diff --git a/node_modules/yargs/node_modules/path-type/license b/node_modules/yargs/node_modules/path-type/license new file mode 100644 index 000000000..654d0bfe9 --- /dev/null +++ b/node_modules/yargs/node_modules/path-type/license @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/node_modules/yargs/node_modules/path-type/package.json b/node_modules/yargs/node_modules/path-type/package.json new file mode 100644 index 000000000..54336f352 --- /dev/null +++ b/node_modules/yargs/node_modules/path-type/package.json @@ -0,0 +1,48 @@ +{ + "name": "path-type", + "version": "2.0.0", + "description": "Check if a path is a file, directory, or symlink", + "license": "MIT", + "repository": "sindresorhus/path-type", + "author": { + "name": "Sindre Sorhus", + "email": "sindresorhus@gmail.com", + "url": "sindresorhus.com" + }, + "engines": { + "node": ">=4" + }, + "scripts": { + "test": "xo && ava" + }, + "files": [ + "index.js" + ], + "keywords": [ + "path", + "fs", + "type", + "is", + "check", + "directory", + "dir", + "file", + "filepath", + "symlink", + "symbolic", + "link", + "stat", + "stats", + "filesystem" + ], + "dependencies": { + "pify": "^2.0.0" + }, + "devDependencies": { + "ava": "*", + "xo": "*" + }, + "xo": { + "esnext": true + } +} diff --git a/node_modules/yargs/node_modules/path-type/readme.md b/node_modules/yargs/node_modules/path-type/readme.md new file mode 100644 index 000000000..b1ea61fe9 --- /dev/null +++ b/node_modules/yargs/node_modules/path-type/readme.md @@ -0,0 +1,42 @@ +# path-type [](https://travis-ci.org/sindresorhus/path-type) + +> Check if a path is a file, directory, or symlink + + +## Install + +``` +$ npm install --save path-type +``` + + +## Usage + +```js +const pathType = require('path-type'); + +pathType.file('package.json').then(isFile => { + console.log(isFile); + //=> true +}) +``` + + +## API + +### .file(path) +### .dir(path) +### .symlink(path) + +Returns a `Promise` for a `boolean` of whether the path is the checked type. + +### .fileSync(path) +### .dirSync(path) +### .symlinkSync(path) + +Returns a `boolean` of whether the path is the checked type. + + +## License + +MIT © [Sindre Sorhus](https://sindresorhus.com) diff --git a/node_modules/yargs/node_modules/read-pkg-up/index.js b/node_modules/yargs/node_modules/read-pkg-up/index.js new file mode 100644 index 000000000..26079760f --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg-up/index.js @@ -0,0 +1,26 @@ +'use strict'; +const findUp = require('find-up'); +const readPkg = require('read-pkg'); + +module.exports = opts => { + return findUp('package.json', opts).then(fp => { + if (!fp) { + return {}; + } + + return readPkg(fp, opts).then(pkg => ({pkg, path: fp})); + }); +}; + +module.exports.sync = opts => { + const fp = findUp.sync('package.json', opts); + + if (!fp) { + return {}; + } + + return { + pkg: readPkg.sync(fp, opts), + path: fp + }; +}; diff --git a/node_modules/yargs/node_modules/read-pkg-up/license b/node_modules/yargs/node_modules/read-pkg-up/license new file mode 100644 index 000000000..654d0bfe9 --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg-up/license @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/node_modules/yargs/node_modules/read-pkg-up/package.json b/node_modules/yargs/node_modules/read-pkg-up/package.json new file mode 100644 index 000000000..f09bf3c35 --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg-up/package.json @@ -0,0 +1,62 @@ +{ + "name": "read-pkg-up", + "version": "2.0.0", + "description": "Read the closest package.json file", + "license": "MIT", + "repository": "sindresorhus/read-pkg-up", + "author": { + "name": "Sindre Sorhus", + "email": "sindresorhus@gmail.com", + "url": "sindresorhus.com" + }, + "engines": { + "node": ">=4" + }, + "scripts": { + "test": "xo && ava" + }, + "files": [ + "index.js" + ], + "keywords": [ + "json", + "read", + "parse", + "file", + "fs", + "graceful", + "load", + "pkg", + "package", + "find", + "up", + "find-up", + "findup", + "look-up", + "look", + "file", + "search", + "match", + "package", + "resolve", + "parent", + "parents", + "folder", + "directory", + "dir", + "walk", + "walking", + "path" + ], + "dependencies": { + "find-up": "^2.0.0", + "read-pkg": "^2.0.0" + }, + "devDependencies": { + "ava": "*", + "xo": "*" + }, + "xo": { + "esnext": true + } +} diff --git a/node_modules/yargs/node_modules/read-pkg-up/readme.md b/node_modules/yargs/node_modules/read-pkg-up/readme.md new file mode 100644 index 000000000..ba18780f9 --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg-up/readme.md @@ -0,0 +1,80 @@ +# read-pkg-up [](https://travis-ci.org/sindresorhus/read-pkg-up) + +> Read the closest package.json file + + +## Why + +- [Finds the closest package.json](https://github.com/sindresorhus/find-up) +- [Gracefully handles filesystem issues](https://github.com/isaacs/node-graceful-fs) +- [Strips UTF-8 BOM](https://github.com/sindresorhus/strip-bom) +- [Throws more helpful JSON errors](https://github.com/sindresorhus/parse-json) +- [Normalizes the data](https://github.com/npm/normalize-package-data#what-normalization-currently-entails) + + +## Install + +``` +$ npm install --save read-pkg-up +``` + + +## Usage + +```js +const readPkgUp = require('read-pkg-up'); + +readPkgUp().then(result => { + console.log(result); + /* + { + pkg: { + name: 'awesome-package', + version: '1.0.0', + ... + }, + path: '/Users/sindresorhus/dev/awesome-package/package.json' + } + */ +}); +``` + + +## API + +### readPkgUp([options]) + +Returns a `Promise` for the result object. + +### readPkgUp.sync([options]) + +Returns the result object. + +#### options + +##### cwd + +Type: `string`<br> +Default: `.` + +Directory to start looking for a package.json file. + +##### normalize + +Type: `boolean`<br> +Default: `true` + +[Normalize](https://github.com/npm/normalize-package-data#what-normalization-currently-entails) the package data. + + +## Related + +- [read-pkg](https://github.com/sindresorhus/read-pkg) - Read a package.json file +- [pkg-up](https://github.com/sindresorhus/pkg-up) - Find the closest package.json file +- [find-up](https://github.com/sindresorhus/find-up) - Find a file by walking up parent directories +- [pkg-conf](https://github.com/sindresorhus/pkg-conf) - Get namespaced config from the closest package.json + + +## License + +MIT © [Sindre Sorhus](https://sindresorhus.com) diff --git a/node_modules/yargs/node_modules/read-pkg/index.js b/node_modules/yargs/node_modules/read-pkg/index.js new file mode 100644 index 000000000..dff948b69 --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg/index.js @@ -0,0 +1,47 @@ +'use strict'; +const path = require('path'); +const loadJsonFile = require('load-json-file'); +const pathType = require('path-type'); + +module.exports = (fp, opts) => { + if (typeof fp !== 'string') { + opts = fp; + fp = '.'; + } + + opts = opts || {}; + + return pathType.dir(fp) + .then(isDir => { + if (isDir) { + fp = path.join(fp, 'package.json'); + } + + return loadJsonFile(fp); + }) + .then(x => { + if (opts.normalize !== false) { + require('normalize-package-data')(x); + } + + return x; + }); +}; + +module.exports.sync = (fp, opts) => { + if (typeof fp !== 'string') { + opts = fp; + fp = '.'; + } + + opts = opts || {}; + fp = pathType.dirSync(fp) ? path.join(fp, 'package.json') : fp; + + const x = loadJsonFile.sync(fp); + + if (opts.normalize !== false) { + require('normalize-package-data')(x); + } + + return x; +}; diff --git a/node_modules/yargs/node_modules/read-pkg/license b/node_modules/yargs/node_modules/read-pkg/license new file mode 100644 index 000000000..654d0bfe9 --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg/license @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/node_modules/yargs/node_modules/read-pkg/package.json b/node_modules/yargs/node_modules/read-pkg/package.json new file mode 100644 index 000000000..b2322191f --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg/package.json @@ -0,0 +1,45 @@ +{ + "name": "read-pkg", + "version": "2.0.0", + "description": "Read a package.json file", + "license": "MIT", + "repository": "sindresorhus/read-pkg", + "author": { + "name": "Sindre Sorhus", + "email": "sindresorhus@gmail.com", + "url": "sindresorhus.com" + }, + "engines": { + "node": ">=4" + }, + "scripts": { + "test": "xo && ava" + }, + "files": [ + "index.js" + ], + "keywords": [ + "json", + "read", + "parse", + "file", + "fs", + "graceful", + "load", + "pkg", + "package", + "normalize" + ], + "dependencies": { + "load-json-file": "^2.0.0", + "normalize-package-data": "^2.3.2", + "path-type": "^2.0.0" + }, + "devDependencies": { + "ava": "*", + "xo": "*" + }, + "xo": { + "esnext": true + } +} diff --git a/node_modules/yargs/node_modules/read-pkg/readme.md b/node_modules/yargs/node_modules/read-pkg/readme.md new file mode 100644 index 000000000..5796008b8 --- /dev/null +++ b/node_modules/yargs/node_modules/read-pkg/readme.md @@ -0,0 +1,79 @@ +# read-pkg [](https://travis-ci.org/sindresorhus/read-pkg) + +> Read a package.json file + + +## Why + +- [Gracefully handles filesystem issues](https://github.com/isaacs/node-graceful-fs) +- [Strips UTF-8 BOM](https://github.com/sindresorhus/strip-bom) +- [Throws more helpful JSON errors](https://github.com/sindresorhus/parse-json) +- [Normalizes the data](https://github.com/npm/normalize-package-data#what-normalization-currently-entails) + + +## Install + +``` +$ npm install --save read-pkg +``` + + +## Usage + +```js +const readPkg = require('read-pkg'); + +readPkg().then(pkg => { + console.log(pkg); + //=> {name: 'read-pkg', ...} +}); + +readPkg(__dirname).then(pkg => { + console.log(pkg); + //=> {name: 'read-pkg', ...} +}); + +readPkg(path.join('unicorn', 'package.json')).then(pkg => { + console.log(pkg); + //=> {name: 'read-pkg', ...} +}); +``` + + +## API + +### readPkg([path], [options]) + +Returns a `Promise` for the parsed JSON. + +### readPkg.sync([path], [options]) + +Returns the parsed JSON. + +#### path + +Type: `string`<br> +Default: `.` + +Path to a `package.json` file or its directory. + +#### options + +##### normalize + +Type: `boolean`<br> +Default: `true` + +[Normalize](https://github.com/npm/normalize-package-data#what-normalization-currently-entails) the package data. + + +## Related + +- [read-pkg-up](https://github.com/sindresorhus/read-pkg-up) - Read the closest package.json file +- [write-pkg](https://github.com/sindresorhus/write-pkg) - Write a `package.json` file +- [load-json-file](https://github.com/sindresorhus/load-json-file) - Read and parse a JSON file + + +## License + +MIT © [Sindre Sorhus](https://sindresorhus.com) diff --git a/node_modules/yargs/node_modules/string-width/index.js b/node_modules/yargs/node_modules/string-width/index.js new file mode 100644 index 000000000..bbc49d29b --- /dev/null +++ b/node_modules/yargs/node_modules/string-width/index.js @@ -0,0 +1,36 @@ +'use strict'; +const stripAnsi = require('strip-ansi'); +const isFullwidthCodePoint = require('is-fullwidth-code-point'); + +module.exports = str => { + if (typeof str !== 'string' || str.length === 0) { + return 0; + } + + str = stripAnsi(str); + + let width = 0; + + for (let i = 0; i < str.length; i++) { + const code = str.codePointAt(i); + + // Ignore control characters + if (code <= 0x1F || (code >= 0x7F && code <= 0x9F)) { + continue; + } + + // Ignore combining characters + if (code >= 0x300 && code <= 0x36F) { + continue; + } + + // Surrogates + if (code > 0xFFFF) { + i++; + } + + width += isFullwidthCodePoint(code) ? 2 : 1; + } + + return width; +}; diff --git a/node_modules/yargs/node_modules/string-width/license b/node_modules/yargs/node_modules/string-width/license new file mode 100644 index 000000000..e7af2f771 --- /dev/null +++ b/node_modules/yargs/node_modules/string-width/license @@ -0,0 +1,9 @@ +MIT License + +Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/node_modules/yargs/node_modules/string-width/package.json b/node_modules/yargs/node_modules/string-width/package.json new file mode 100644 index 000000000..89f0b6a6c --- /dev/null +++ b/node_modules/yargs/node_modules/string-width/package.json @@ -0,0 +1,55 @@ +{ + "name": "string-width", + "version": "2.1.1", + "description": "Get the visual width of a string - the number of columns required to display it", + "license": "MIT", + "repository": "sindresorhus/string-width", + "author": { + "name": "Sindre Sorhus", + "email": "sindresorhus@gmail.com", + "url": "sindresorhus.com" + }, + "engines": { + "node": ">=4" + }, + "scripts": { + "test": "xo && ava" + }, + "files": [ + "index.js" + ], + "keywords": [ + "string", + "str", + "character", + "char", + "unicode", + "width", + "visual", + "column", + "columns", + "fullwidth", + "full-width", + "full", + "ansi", + "escape", + "codes", + "cli", + "command-line", + "terminal", + "console", + "cjk", + "chinese", + "japanese", + "korean", + "fixed-width" + ], + "dependencies": { + "is-fullwidth-code-point": "^2.0.0", + "strip-ansi": "^4.0.0" + }, + "devDependencies": { + "ava": "*", + "xo": "*" + } +} diff --git a/node_modules/yargs/node_modules/string-width/readme.md b/node_modules/yargs/node_modules/string-width/readme.md new file mode 100644 index 000000000..df5b7199f --- /dev/null +++ b/node_modules/yargs/node_modules/string-width/readme.md @@ -0,0 +1,42 @@ +# string-width [](https://travis-ci.org/sindresorhus/string-width) + +> Get the visual width of a string - the number of columns required to display it + +Some Unicode characters are [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) and use double the normal width. [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) are stripped and doesn't affect the width. + +Useful to be able to measure the actual width of command-line output. + + +## Install + +``` +$ npm install string-width +``` + + +## Usage + +```js +const stringWidth = require('string-width'); + +stringWidth('古'); +//=> 2 + +stringWidth('\u001b[1m古\u001b[22m'); +//=> 2 + +stringWidth('a'); +//=> 1 +``` + + +## Related + +- [string-width-cli](https://github.com/sindresorhus/string-width-cli) - CLI for this module +- [string-length](https://github.com/sindresorhus/string-length) - Get the real length of a string +- [widest-line](https://github.com/sindresorhus/widest-line) - Get the visual width of the widest line in a string + + +## License + +MIT © [Sindre Sorhus](https://sindresorhus.com) diff --git a/node_modules/yargs/node_modules/strip-ansi/index.js b/node_modules/yargs/node_modules/strip-ansi/index.js new file mode 100644 index 000000000..96e0292c8 --- /dev/null +++ b/node_modules/yargs/node_modules/strip-ansi/index.js @@ -0,0 +1,4 @@ +'use strict'; +const ansiRegex = require('ansi-regex'); + +module.exports = input => typeof input === 'string' ? input.replace(ansiRegex(), '') : input; diff --git a/node_modules/yargs/node_modules/strip-ansi/license b/node_modules/yargs/node_modules/strip-ansi/license new file mode 100644 index 000000000..e7af2f771 --- /dev/null +++ b/node_modules/yargs/node_modules/strip-ansi/license @@ -0,0 +1,9 @@ +MIT License + +Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/node_modules/yargs/node_modules/strip-ansi/package.json b/node_modules/yargs/node_modules/strip-ansi/package.json new file mode 100644 index 000000000..555f19461 --- /dev/null +++ b/node_modules/yargs/node_modules/strip-ansi/package.json @@ -0,0 +1,52 @@ +{ + "name": "strip-ansi", + "version": "4.0.0", + "description": "Strip ANSI escape codes", + "license": "MIT", + "repository": "chalk/strip-ansi", + "author": { + "name": "Sindre Sorhus", + "email": "sindresorhus@gmail.com", + "url": "sindresorhus.com" + }, + "engines": { + "node": ">=4" + }, + "scripts": { + "test": "xo && ava" + }, + "files": [ + "index.js" + ], + "keywords": [ + "strip", + "trim", + "remove", + "ansi", + "styles", + "color", + "colour", + "colors", + "terminal", + "console", + "string", + "tty", + "escape", + "formatting", + "rgb", + "256", + "shell", + "xterm", + "log", + "logging", + "command-line", + "text" + ], + "dependencies": { + "ansi-regex": "^3.0.0" + }, + "devDependencies": { + "ava": "*", + "xo": "*" + } +} diff --git a/node_modules/yargs/node_modules/strip-ansi/readme.md b/node_modules/yargs/node_modules/strip-ansi/readme.md new file mode 100644 index 000000000..dc76f0cb1 --- /dev/null +++ b/node_modules/yargs/node_modules/strip-ansi/readme.md @@ -0,0 +1,39 @@ +# strip-ansi [](https://travis-ci.org/chalk/strip-ansi) + +> Strip [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) + + +## Install + +``` +$ npm install strip-ansi +``` + + +## Usage + +```js +const stripAnsi = require('strip-ansi'); + +stripAnsi('\u001B[4mUnicorn\u001B[0m'); +//=> 'Unicorn' +``` + + +## Related + +- [strip-ansi-cli](https://github.com/chalk/strip-ansi-cli) - CLI for this module +- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes +- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes +- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right + + +## Maintainers + +- [Sindre Sorhus](https://github.com/sindresorhus) +- [Josh Junon](https://github.com/qix-) + + +## License + +MIT diff --git a/node_modules/yargs/node_modules/yargs-parser/CHANGELOG.md b/node_modules/yargs/node_modules/yargs-parser/CHANGELOG.md index bf172df5f..3ad3df821 100644 --- a/node_modules/yargs/node_modules/yargs-parser/CHANGELOG.md +++ b/node_modules/yargs/node_modules/yargs-parser/CHANGELOG.md @@ -2,6 +2,75 @@ 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. +<a name="7.0.0"></a> +# [7.0.0](https://github.com/yargs/yargs-parser/compare/v6.0.1...v7.0.0) (2017-05-02) + + +### Chores + +* revert populate-- logic ([#91](https://github.com/yargs/yargs-parser/issues/91)) ([6003e6d](https://github.com/yargs/yargs-parser/commit/6003e6d)) + + +### BREAKING CHANGES + +* populate-- now defaults to false. + + + +<a name="6.0.1"></a> +## [6.0.1](https://github.com/yargs/yargs-parser/compare/v6.0.0...v6.0.1) (2017-05-01) + + +### Bug Fixes + +* default '--' to undefined when not provided; this is closer to the array API ([#90](https://github.com/yargs/yargs-parser/issues/90)) ([4e739cc](https://github.com/yargs/yargs-parser/commit/4e739cc)) + + + +<a name="6.0.0"></a> +# [6.0.0](https://github.com/yargs/yargs-parser/compare/v4.2.1...v6.0.0) (2017-05-01) + + +### Bug Fixes + +* environment variables should take precedence over config file ([#81](https://github.com/yargs/yargs-parser/issues/81)) ([76cee1f](https://github.com/yargs/yargs-parser/commit/76cee1f)) +* parsing hints should apply for dot notation keys ([#86](https://github.com/yargs/yargs-parser/issues/86)) ([3e47d62](https://github.com/yargs/yargs-parser/commit/3e47d62)) + + +### Chores + +* upgrade to newest version of camelcase ([#87](https://github.com/yargs/yargs-parser/issues/87)) ([f1903aa](https://github.com/yargs/yargs-parser/commit/f1903aa)) + + +### Features + +* add -- option which allows arguments after the -- flag to be returned separated from positional arguments ([#84](https://github.com/yargs/yargs-parser/issues/84)) ([2572ca8](https://github.com/yargs/yargs-parser/commit/2572ca8)) +* when parsing stops, we now populate "--" by default ([#88](https://github.com/yargs/yargs-parser/issues/88)) ([cd666db](https://github.com/yargs/yargs-parser/commit/cd666db)) + + +### BREAKING CHANGES + +* rather than placing arguments in "_", when parsing is stopped via "--"; we now populate an array called "--" by default. +* camelcase now requires Node 4+. +* environment variables will now override config files (args, env, config-file, config-object) + + + +<a name="5.0.0"></a> +# [5.0.0](https://github.com/yargs/yargs-parser/compare/v4.2.1...v5.0.0) (2017-02-18) + + +### Bug Fixes + +* environment variables should take precedence over config file ([#81](https://github.com/yargs/yargs-parser/issues/81)) ([76cee1f](https://github.com/yargs/yargs-parser/commit/76cee1f)) + + +### BREAKING CHANGES + +* environment variables will now override config files (args, env, config-file, config-object) + + + <a name="4.2.1"></a> ## [4.2.1](https://github.com/yargs/yargs-parser/compare/v4.2.0...v4.2.1) (2017-01-02) diff --git a/node_modules/yargs/node_modules/yargs-parser/README.md b/node_modules/yargs/node_modules/yargs-parser/README.md index cf4517481..d1817fccc 100644 --- a/node_modules/yargs/node_modules/yargs-parser/README.md +++ b/node_modules/yargs/node_modules/yargs-parser/README.md @@ -11,7 +11,7 @@ The mighty option parser used by [yargs](https://github.com/yargs/yargs). visit the [yargs website](http://yargs.js.org/) for more examples, and thorough usage instructions. -<img width="250" src="yargs-logo.png"> +<img width="250" src="https://raw.githubusercontent.com/yargs/yargs-parser/master/yargs-logo.png"> ## Example @@ -72,12 +72,14 @@ Parses command line arguments returning a simple mapping of keys and values. * `opts.string`: keys should be treated as strings (even if they resemble a number `-x 33`). * `opts.configuration`: provide configuration options to the yargs-parser (see: [configuration](#configuration)). * `opts.number`: keys should be treated as numbers. + * `opts['--']`: arguments after the end-of-options flag `--` will be set to the `argv.['--']` array instead of being set to the `argv._` array. **returns:** * `obj`: an object representing the parsed value of `args` * `key/value`: key value pairs for each argument and their aliases. * `_`: an array representing the positional arguments. + * [optional] `--`: an array with arguments after the end-of-options flag `--`. ### require('yargs-parser').detailed(args, opts={}) @@ -100,6 +102,7 @@ yargs engine. * `configuration`: the configuration loaded from the `yargs` stanza in package.json. <a name="configuration"></a> + ### Configuration The yargs-parser applies several automated transformations on the keys provided @@ -247,6 +250,27 @@ node example.js -x 1 2 -x 3 4 { _: [], x: [[1, 2], [3, 4]] } ``` +### populate -- + +* default: `false`. +* key: `populate--` + +Should unparsed flags be stored in `--` or `_`. + +_If disabled:_ + +```sh +node example.js a -b -- x y +{ _: [ 'a', 'x', 'y' ], b: true } +``` + +_If enabled:_ + +```sh +node example.js a -b -- x y +{ _: [ 'a' ], '--': [ 'x', 'y' ], b: true } +``` + ## Special Thanks The yargs project evolves from optimist and minimist. It owes its diff --git a/node_modules/yargs/node_modules/yargs-parser/index.js b/node_modules/yargs/node_modules/yargs-parser/index.js index 1a04d559b..73154066f 100644 --- a/node_modules/yargs/node_modules/yargs-parser/index.js +++ b/node_modules/yargs/node_modules/yargs-parser/index.js @@ -17,11 +17,14 @@ function parse (args, opts) { 'parse-numbers': true, 'boolean-negation': true, 'duplicate-arguments-array': true, - 'flatten-duplicate-arrays': true + 'flatten-duplicate-arrays': true, + 'populate--': false }, opts.configuration) var defaults = opts.default || {} var configObjects = opts.configObjects || [] var envPrefix = opts.envPrefix + var notFlagsOption = configuration['populate--'] + var notFlagsArgv = notFlagsOption ? '--' : '_' var newAliases = {} // allow a i18n handler to be passed in, default to a fake one (util.format). var __ = opts.__ || function (str) { @@ -273,14 +276,14 @@ function parse (args, opts) { // order of precedence: // 1. command line arg - // 2. value from config file - // 3. value from config objects - // 4. value from env var + // 2. value from env var + // 3. value from config file + // 4. value from config objects // 5. configured default value applyEnvVars(argv, true) // special case: check env vars that point to config file + applyEnvVars(argv, false) setConfig(argv) setConfigObjects() - applyEnvVars(argv, false) applyDefaultsAndAliases(argv, flags.aliases, defaults) applyCoercions(argv) @@ -289,8 +292,10 @@ function parse (args, opts) { if (!hasKey(argv, key.split('.'))) setArg(key, 0) }) + // '--' defaults to undefined. + if (notFlagsOption && notFlags.length) argv[notFlagsArgv] = [] notFlags.forEach(function (key) { - argv._.push(key) + argv[notFlagsArgv].push(key) }) // how many arguments should we consume, based @@ -558,7 +563,7 @@ function parse (args, opts) { var key = keys[keys.length - 1] - var isTypeArray = checkAllAliases(key, flags.arrays) + var isTypeArray = checkAllAliases(keys.join('.'), flags.arrays) var isValueArray = Array.isArray(value) var duplicate = configuration['duplicate-arguments-array'] diff --git a/node_modules/yargs/node_modules/yargs-parser/package.json b/node_modules/yargs/node_modules/yargs-parser/package.json index 9b3ddd555..5d84e9f19 100644 --- a/node_modules/yargs/node_modules/yargs-parser/package.json +++ b/node_modules/yargs/node_modules/yargs-parser/package.json @@ -1,6 +1,6 @@ { "name": "yargs-parser", - "version": "4.2.1", + "version": "7.0.0", "description": "the mighty option parser used by yargs", "main": "index.js", "scripts": { @@ -30,11 +30,11 @@ "coveralls": "^2.11.12", "mocha": "^3.0.1", "nyc": "^10.0.0", - "standard": "^8.0.0", + "standard": "^10.0.2", "standard-version": "^4.0.0" }, "dependencies": { - "camelcase": "^3.0.0" + "camelcase": "^4.1.0" }, "files": [ "lib", diff --git a/node_modules/yargs/package.json b/node_modules/yargs/package.json index fc266f74d..c9a799f7a 100644 --- a/node_modules/yargs/package.json +++ b/node_modules/yargs/package.json @@ -1,6 +1,6 @@ { "name": "yargs", - "version": "6.6.0", + "version": "8.0.2", "description": "yargs the modern, pirate-themed, successor to optimist.", "main": "./index.js", "files": [ @@ -12,19 +12,19 @@ "LICENSE" ], "dependencies": { - "camelcase": "^3.0.0", + "camelcase": "^4.1.0", "cliui": "^3.2.0", "decamelize": "^1.1.1", "get-caller-file": "^1.0.1", - "os-locale": "^1.4.0", - "read-pkg-up": "^1.0.1", + "os-locale": "^2.0.0", + "read-pkg-up": "^2.0.0", "require-directory": "^2.1.1", "require-main-filename": "^1.0.1", "set-blocking": "^2.0.0", - "string-width": "^1.0.2", - "which-module": "^1.0.0", + "string-width": "^2.0.0", + "which-module": "^2.0.0", "y18n": "^3.2.1", - "yargs-parser": "^4.2.0" + "yargs-parser": "^7.0.0" }, "devDependencies": { "chai": "^3.4.1", @@ -35,11 +35,12 @@ "es6-promise": "^4.0.2", "hashish": "0.0.4", "mocha": "^3.0.1", - "nyc": "^10.0.0", + "nyc": "^10.3.0", "rimraf": "^2.5.0", "standard": "^8.6.0", - "standard-version": "^3.0.0", - "which": "^1.2.9" + "standard-version": "^4.2.0", + "which": "^1.2.9", + "yargs-test-extends": "^1.0.1" }, "scripts": { "pretest": "standard", @@ -69,12 +70,5 @@ "license": "MIT", "engine": { "node": ">=0.10" - }, - "greenkeeper": { - "ignore": [ - "string-width", - "read-pkg-up", - "camelcase" - ] } } diff --git a/node_modules/yargs/yargs.js b/node_modules/yargs/yargs.js index a63c94a4b..078bf8f14 100644 --- a/node_modules/yargs/yargs.js +++ b/node_modules/yargs/yargs.js @@ -1,3 +1,4 @@ +const argsert = require('./lib/argsert') const assign = require('./lib/assign') const Command = require('./lib/command') const Completion = require('./lib/completion') @@ -8,6 +9,8 @@ const Validation = require('./lib/validation') const Y18n = require('y18n') const objFilter = require('./lib/obj-filter') const setBlocking = require('set-blocking') +const applyExtends = require('./lib/apply-extends') +const YError = require('./lib/yerror') var exports = module.exports = Yargs function Yargs (processArgs, cwd, parentRequire) { @@ -65,23 +68,23 @@ function Yargs (processArgs, cwd, parentRequire) { // logic is used to build a nested command // hierarchy. var tmpOptions = {} - tmpOptions.global = options.global ? options.global : [] + tmpOptions.local = options.local ? options.local : [] tmpOptions.configObjects = options.configObjects ? options.configObjects : [] - // if a key has been set as a global, we - // do not want to reset it or its aliases. - var globalLookup = {} - tmpOptions.global.forEach(function (g) { - globalLookup[g] = true - ;(aliases[g] || []).forEach(function (a) { - globalLookup[a] = true + // if a key has been explicitly set as local, + // we should reset it before passing options to command. + var localLookup = {} + tmpOptions.local.forEach(function (l) { + localLookup[l] = true + ;(aliases[l] || []).forEach(function (a) { + localLookup[a] = true }) }) - // preserve groups containing global keys + // preserve all groups not set to local. preservedGroups = Object.keys(groups).reduce(function (acc, groupName) { var keys = groups[groupName].filter(function (key) { - return key in globalLookup + return !(key in localLookup) }) if (keys.length > 0) { acc[groupName] = keys @@ -103,13 +106,13 @@ function Yargs (processArgs, cwd, parentRequire) { arrayOptions.forEach(function (k) { tmpOptions[k] = (options[k] || []).filter(function (k) { - return globalLookup[k] + return !localLookup[k] }) }) objectOptions.forEach(function (k) { tmpOptions[k] = objFilter(options[k], function (k, v) { - return globalLookup[k] + return !localLookup[k] }) }) @@ -118,12 +121,11 @@ function Yargs (processArgs, cwd, parentRequire) { // if this is the first time being executed, create // instances of all our helpers -- otherwise just reset. - usage = usage ? usage.reset(globalLookup) : Usage(self, y18n) - validation = validation ? validation.reset(globalLookup) : Validation(self, usage, y18n) + usage = usage ? usage.reset(localLookup) : Usage(self, y18n) + validation = validation ? validation.reset(localLookup) : Validation(self, usage, y18n) command = command ? command.reset() : Command(self, usage, validation) if (!completion) completion = Completion(self, usage, command) - strict = false completionCommand = null output = '' exitError = null @@ -171,56 +173,143 @@ function Yargs (processArgs, cwd, parentRequire) { frozen = undefined } - self.boolean = function (bools) { - options.boolean.push.apply(options.boolean, [].concat(bools)) + self.boolean = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('boolean', keys) return self } - self.array = function (arrays) { - options.array.push.apply(options.array, [].concat(arrays)) + self.array = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('array', keys) return self } - self.nargs = function (key, n) { - if (typeof key === 'object') { - Object.keys(key).forEach(function (k) { - self.nargs(k, key[k]) - }) - } else { - options.narg[key] = n - } + self.number = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('number', keys) return self } - self.number = function (numbers) { - options.number.push.apply(options.number, [].concat(numbers)) + self.normalize = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('normalize', keys) return self } - self.choices = function (key, values) { - if (typeof key === 'object') { - Object.keys(key).forEach(function (k) { - self.choices(k, key[k]) - }) - } else { - options.choices[key] = (options.choices[key] || []).concat(values) + self.count = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('count', keys) + return self + } + + self.string = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('string', keys) + return self + } + + self.requiresArg = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('requiresArg', keys) + return self + } + + self.skipValidation = function (keys) { + argsert('<array|string>', [keys], arguments.length) + populateParserHintArray('skipValidation', keys) + return self + } + + function populateParserHintArray (type, keys, value) { + keys = [].concat(keys) + keys.forEach(function (key) { + options[type].push(key) + }) + } + + self.nargs = function (key, value) { + argsert('<string|object|array> [number]', [key, value], arguments.length) + populateParserHintObject(self.nargs, false, 'narg', key, value) + return self + } + + self.choices = function (key, value) { + argsert('<object|string|array> [string|array]', [key, value], arguments.length) + populateParserHintObject(self.choices, true, 'choices', key, value) + return self + } + + self.alias = function (key, value) { + argsert('<object|string|array> [string|array]', [key, value], arguments.length) + populateParserHintObject(self.alias, true, 'alias', key, value) + return self + } + + // TODO: actually deprecate self.defaults. + self.default = self.defaults = function (key, value, defaultDescription) { + argsert('<object|string|array> [*] [string]', [key, value, defaultDescription], arguments.length) + if (defaultDescription) options.defaultDescription[key] = defaultDescription + if (typeof value === 'function') { + if (!options.defaultDescription[key]) options.defaultDescription[key] = usage.functionDescription(value) + value = value.call() } + populateParserHintObject(self.default, false, 'default', key, value) + return self + } + + self.describe = function (key, desc) { + argsert('<object|string|array> [string]', [key, desc], arguments.length) + populateParserHintObject(self.describe, false, 'key', key, true) + usage.describe(key, desc) + return self + } + + self.demandOption = function (keys, msg) { + argsert('<object|string|array> [string]', [keys, msg], arguments.length) + populateParserHintObject(self.demandOption, false, 'demandedOptions', keys, msg) return self } - self.normalize = function (strings) { - options.normalize.push.apply(options.normalize, [].concat(strings)) + self.coerce = function (keys, value) { + argsert('<object|string|array> [function]', [keys, value], arguments.length) + populateParserHintObject(self.coerce, false, 'coerce', keys, value) return self } + function populateParserHintObject (builder, isArray, type, key, value) { + if (Array.isArray(key)) { + // an array of keys with one value ['x', 'y', 'z'], function parse () {} + var temp = {} + key.forEach(function (k) { + temp[k] = value + }) + builder(temp) + } else if (typeof key === 'object') { + // an object of key value pairs: {'x': parse () {}, 'y': parse() {}} + Object.keys(key).forEach(function (k) { + builder(k, key[k]) + }) + } else { + // a single key value pair 'x', parse() {} + if (isArray) { + options[type][key] = (options[type][key] || []).concat(value) + } else { + options[type][key] = value + } + } + } + self.config = function (key, msg, parseFn) { - // allow to pass a configuration object + argsert('[object|string] [string|function] [function]', [key, msg, parseFn], arguments.length) + // allow a config object to be provided directly. if (typeof key === 'object') { + key = applyExtends(key, cwd) options.configObjects = (options.configObjects || []).concat(key) return self } - // allow to provide a parsing function + // allow for a custom parsing function. if (typeof msg === 'function') { parseFn = msg msg = null @@ -231,78 +320,31 @@ function Yargs (processArgs, cwd, parentRequire) { ;(Array.isArray(key) ? key : [key]).forEach(function (k) { options.config[k] = parseFn || true }) + return self } self.example = function (cmd, description) { + argsert('<string> [string]', [cmd, description], arguments.length) usage.example(cmd, description) return self } self.command = function (cmd, description, builder, handler) { + argsert('<string|array|object> [string|boolean] [function|object] [function]', [cmd, description, builder, handler], arguments.length) command.addHandler(cmd, description, builder, handler) return self } self.commandDir = function (dir, opts) { + argsert('<string> [object]', [dir, opts], arguments.length) const req = parentRequire || require command.addDirectory(dir, self.getContext(), req, require('get-caller-file')(), opts) return self } - self.string = function (strings) { - options.string.push.apply(options.string, [].concat(strings)) - return self - } - - // The 'defaults' alias is deprecated. It will be removed in the next major version. - self.default = self.defaults = function (key, value, defaultDescription) { - if (typeof key === 'object') { - Object.keys(key).forEach(function (k) { - self.default(k, key[k]) - }) - } else { - if (defaultDescription) options.defaultDescription[key] = defaultDescription - if (typeof value === 'function') { - if (!options.defaultDescription[key]) options.defaultDescription[key] = usage.functionDescription(value) - value = value.call() - } - options.default[key] = value - } - return self - } - - self.alias = function (x, y) { - if (typeof x === 'object') { - Object.keys(x).forEach(function (key) { - self.alias(key, x[key]) - }) - } else { - options.alias[x] = (options.alias[x] || []).concat(y) - } - return self - } - - self.coerce = function (key, fn) { - if (typeof key === 'object' && !Array.isArray(key)) { - Object.keys(key).forEach(function (k) { - self.coerce(k, key[k]) - }) - } else { - [].concat(key).forEach(function (k) { - options.coerce[k] = fn - }) - } - return self - } - - self.count = function (counts) { - options.count.push.apply(options.count, [].concat(counts)) - return self - } - - // deprecated: the demand API is too overloaded, and is being - // deprecated in favor of .demandCommand() .demandOption(). + // TODO: deprecate self.demand in favor of + // .demandCommand() .demandOption(). self.demand = self.required = self.require = function (keys, max, msg) { // you can optionally provide a 'max' key, // which will raise an exception if too many '_' @@ -318,7 +360,7 @@ function Yargs (processArgs, cwd, parentRequire) { } if (typeof keys === 'number') { - self.demandCommand(keys, max, msg) + self.demandCommand(keys, max, msg, msg) } else if (Array.isArray(keys)) { keys.forEach(function (key) { self.demandOption(key, msg) @@ -334,29 +376,18 @@ function Yargs (processArgs, cwd, parentRequire) { return self } - self.demandOption = function (key, msg) { - if (Array.isArray(key)) { - key.forEach(function (key) { - self.demandOption(key, msg) - }) - } else { - if (typeof msg === 'string') { - options.demandedOptions[key] = { msg: msg } - // allow edge-case of options: {a: {demand: true}, b: {demand: false}} - } else if (msg === true || typeof msg === 'undefined') { - options.demandedOptions[key] = { msg: undefined } - } - } + self.demandCommand = function (min, max, minMsg, maxMsg) { + argsert('[number] [number|string] [string|null] [string|null]', [min, max, minMsg, maxMsg], arguments.length) - return self - } + if (typeof min === 'undefined') min = 1 - self.demandCommand = function (min, max, minMsg, maxMsg) { if (typeof max !== 'number') { minMsg = max max = Infinity } + self.global('_', false) + options.demandedCommands._ = { min: min, max: max, @@ -368,34 +399,30 @@ function Yargs (processArgs, cwd, parentRequire) { } self.getDemandedOptions = function () { + argsert([], 0) return options.demandedOptions } self.getDemandedCommands = function () { + argsert([], 0) return options.demandedCommands } - self.requiresArg = function (requiresArgs) { - options.requiresArg.push.apply(options.requiresArg, [].concat(requiresArgs)) - return self - } - - self.skipValidation = function (skipValidations) { - options.skipValidation.push.apply(options.skipValidation, [].concat(skipValidations)) - return self - } - self.implies = function (key, value) { + argsert('<string|object> [string]', [key, value], arguments.length) validation.implies(key, value) return self } self.conflicts = function (key1, key2) { + argsert('<string|object> [string]', [key1, key2], arguments.length) validation.conflicts(key1, key2) return self } self.usage = function (msg, opts) { + argsert('<string|null|object> [object]', [msg, opts], arguments.length) + if (!opts && typeof msg === 'object') { opts = msg msg = null @@ -409,45 +436,49 @@ function Yargs (processArgs, cwd, parentRequire) { } self.epilogue = self.epilog = function (msg) { + argsert('<string>', [msg], arguments.length) usage.epilog(msg) return self } self.fail = function (f) { + argsert('<function>', [f], arguments.length) usage.failFn(f) return self } - self.check = function (f) { - validation.check(f) + self.check = function (f, _global) { + argsert('<function> [boolean]', [f, _global], arguments.length) + validation.check(f, _global !== false) return self } - self.describe = function (key, desc) { - if (typeof key === 'object') { - Object.keys(key).forEach(function (k) { - options.key[k] = true + self.global = function (globals, global) { + argsert('<string|array> [boolean]', [globals, global], arguments.length) + globals = [].concat(globals) + if (global !== false) { + options.local = options.local.filter(function (l) { + return globals.indexOf(l) === -1 }) } else { - options.key[key] = true + globals.forEach(function (g) { + if (options.local.indexOf(g) === -1) options.local.push(g) + }) } - usage.describe(key, desc) - return self - } - - self.global = function (globals) { - options.global.push.apply(options.global, [].concat(globals)) return self } self.pkgConf = function (key, path) { + argsert('<string> [string]', [key, path], arguments.length) var conf = null - - var obj = pkgUp(path) + // prefer cwd to require-main-filename in this method + // since we're looking for e.g. "nyc" config in nyc consumer + // rather than "yargs" config in nyc (where nyc is the main filename) + var obj = pkgUp(path || cwd) // If an object exists in the key, add it to options.configObjects if (obj[key] && typeof obj[key] === 'object') { - conf = obj[key] + conf = applyExtends(obj[key], path || cwd) options.configObjects = (options.configObjects || []).concat(conf) } @@ -475,6 +506,8 @@ function Yargs (processArgs, cwd, parentRequire) { var parseFn = null var parseContext = null self.parse = function (args, shortCircuit, _parseFn) { + argsert('<string|array> [function|boolean|object] [function]', [args, shortCircuit, _parseFn], arguments.length) + // a context object can optionally be provided, this allows // additional information to be passed to a command handler. if (typeof shortCircuit === 'object') { @@ -496,18 +529,23 @@ function Yargs (processArgs, cwd, parentRequire) { freeze() if (parseFn) exitProcess = false - var parsed = parseArgs(args, shortCircuit) + var parsed = self._parseArgs(args, shortCircuit) if (parseFn) parseFn(exitError, parsed, output) unfreeze() return parsed } + self._getParseContext = function () { + return parseContext || {} + } + self._hasParseCallback = function () { return !!parseFn } self.option = self.options = function (key, opt) { + argsert('<string|object> [object]', [key, opt], arguments.length) if (typeof key === 'object') { Object.keys(key).forEach(function (k) { self.options(k, key[k]) @@ -523,22 +561,31 @@ function Yargs (processArgs, cwd, parentRequire) { var demand = opt.demand || opt.required || opt.require + // deprecated, use 'demandOption' instead if (demand) { self.demand(key, demand) } - if ('demandOption' in opt) { - self.demandOption(key, opt.demandOption) + if (opt.demandOption) { + self.demandOption(key, typeof opt.demandOption === 'string' ? opt.demandOption : undefined) } if ('config' in opt) { self.config(key, opt.configParser) } + if ('conflicts' in opt) { + self.conflicts(key, opt.conflicts) + } + if ('default' in opt) { self.default(key, opt.default) } + if ('implies' in opt) { + self.implies(key, opt.implies) + } + if ('nargs' in opt) { self.nargs(key, opt.nargs) } @@ -559,10 +606,6 @@ function Yargs (processArgs, cwd, parentRequire) { self.group(key, opt.group) } - if (opt.global) { - self.global(key) - } - if (opt.boolean || opt.type === 'boolean') { self.boolean(key) if (opt.alias) self.boolean(opt.alias) @@ -587,6 +630,10 @@ function Yargs (processArgs, cwd, parentRequire) { self.count(key) } + if (typeof opt.global === 'boolean') { + self.global(key, opt.global) + } + if (opt.defaultDescription) { options.defaultDescription[key] = opt.defaultDescription } @@ -612,10 +659,10 @@ function Yargs (processArgs, cwd, parentRequire) { } self.group = function (opts, groupName) { + argsert('<string|array> <string>', [opts, groupName], arguments.length) var existing = preservedGroups[groupName] || groups[groupName] if (preservedGroups[groupName]) { - // the preserved group will be moved to the set of explicitly declared - // groups + // we now only need to track this group name in groups. delete preservedGroups[groupName] } @@ -634,19 +681,22 @@ function Yargs (processArgs, cwd, parentRequire) { // as long as options.envPrefix is not undefined, // parser will apply env vars matching prefix to argv self.env = function (prefix) { + argsert('[string|boolean]', [prefix], arguments.length) if (prefix === false) options.envPrefix = undefined else options.envPrefix = prefix || '' return self } self.wrap = function (cols) { + argsert('<number|null>', [cols], arguments.length) usage.wrap(cols) return self } var strict = false - self.strict = function () { - strict = true + self.strict = function (enabled) { + argsert('[boolean]', [enabled], arguments.length) + strict = enabled !== false return self } self.getStrict = function () { @@ -654,13 +704,15 @@ function Yargs (processArgs, cwd, parentRequire) { } self.showHelp = function (level) { - if (!self.parsed) parseArgs(processArgs) // run parser, if it has not already been executed. + argsert('[string|function]', [level], arguments.length) + if (!self.parsed) self._parseArgs(processArgs) // run parser, if it has not already been executed. usage.showHelp(level) return self } var versionOpt = null self.version = function (opt, msg, ver) { + argsert('[string|function] [string|function] [string]', [opt, msg, ver], arguments.length) if (arguments.length === 0) { ver = guessVersion() opt = 'version' @@ -669,6 +721,7 @@ function Yargs (processArgs, cwd, parentRequire) { opt = 'version' } else if (arguments.length === 2) { ver = msg + msg = null } versionOpt = opt @@ -676,7 +729,6 @@ function Yargs (processArgs, cwd, parentRequire) { usage.version(ver || undefined) self.boolean(versionOpt) - self.global(versionOpt) self.describe(versionOpt, msg) return self } @@ -690,6 +742,8 @@ function Yargs (processArgs, cwd, parentRequire) { var helpOpt = null var useHelpOptAsCommand = false // a call to .help() will enable this self.addHelpOpt = self.help = function (opt, msg, addImplicitCmd) { + argsert('[string|boolean] [string|boolean] [boolean]', [opt, msg, addImplicitCmd], arguments.length) + // argument shuffle if (arguments.length === 0) { useHelpOptAsCommand = true @@ -713,18 +767,19 @@ function Yargs (processArgs, cwd, parentRequire) { // use arguments, fallback to defaults for opt and msg helpOpt = opt || 'help' self.boolean(helpOpt) - self.global(helpOpt) self.describe(helpOpt, msg || usage.deferY18nLookup('Show help')) return self } self.showHelpOnFail = function (enabled, message) { + argsert('[boolean|string] [string]', [enabled, message], arguments.length) usage.showHelpOnFail(enabled, message) return self } var exitProcess = true self.exitProcess = function (enabled) { + argsert('[boolean]', [enabled], arguments.length) if (typeof enabled !== 'boolean') { enabled = true } @@ -737,6 +792,8 @@ function Yargs (processArgs, cwd, parentRequire) { var completionCommand = null self.completion = function (cmd, desc, fn) { + argsert('[string] [string|boolean|function] [function]', [cmd, desc, fn], arguments.length) + // a function to execute when generating // completions can be provided as the second // or third argument to completion. @@ -759,16 +816,19 @@ function Yargs (processArgs, cwd, parentRequire) { } self.showCompletionScript = function ($0) { + argsert('[string]', [$0], arguments.length) $0 = $0 || self.$0 _logger.log(completion.generateCompletionScript($0)) return self } self.getCompletion = function (args, done) { + argsert('<array> <function>', [args, done], arguments.length) completion.getCompletion(args, done) } self.locale = function (locale) { + argsert('[string]', [locale], arguments.length) if (arguments.length === 0) { guessLocale() return y18n.getLocale() @@ -779,6 +839,7 @@ function Yargs (processArgs, cwd, parentRequire) { } self.updateStrings = self.updateLocale = function (obj) { + argsert('<object>', [obj], arguments.length) detectLocale = false y18n.updateLocale(obj) return self @@ -786,6 +847,7 @@ function Yargs (processArgs, cwd, parentRequire) { var detectLocale = true self.detectLocale = function (detect) { + argsert('<boolean>', [detect], arguments.length) detectLocale = detect return self } @@ -807,14 +869,16 @@ function Yargs (processArgs, cwd, parentRequire) { // so that we can print to non-CLIs, e.g., chat-bots. var _logger = { log: function () { - var args = Array.prototype.slice.call(arguments) + const args = [] + for (var i = 0; i < arguments.length; i++) args.push(arguments[i]) if (!self._hasParseCallback()) console.log.apply(console, args) hasOutput = true if (output.length) output += '\n' output += args.join(' ') }, error: function () { - var args = Array.prototype.slice.call(arguments) + const args = [] + for (var i = 0; i < arguments.length; i++) args.push(arguments[i]) if (!self._hasParseCallback()) console.error.apply(console, args) hasOutput = true if (output.length) output += '\n' @@ -830,9 +894,14 @@ function Yargs (processArgs, cwd, parentRequire) { return hasOutput } + self._setHasOutput = function () { + hasOutput = true + } + var recommendCommands - self.recommendCommands = function () { - recommendCommands = true + self.recommendCommands = function (recommend) { + argsert('[boolean]', [recommend], arguments.length) + recommendCommands = typeof recommend === 'boolean' ? recommend : true return self } @@ -849,161 +918,182 @@ function Yargs (processArgs, cwd, parentRequire) { } self.terminalWidth = function () { - return process.stdout.columns + argsert([], 0) + return typeof process.stdout.columns !== 'undefined' ? process.stdout.columns : null } Object.defineProperty(self, 'argv', { get: function () { - var args = null - - try { - args = parseArgs(processArgs) - } catch (err) { - usage.fail(err.message, err) - } - - return args + return self._parseArgs(processArgs) }, enumerable: true }) - function parseArgs (args, shortCircuit) { + self._parseArgs = function (args, shortCircuit, _skipValidation, commandIndex) { + var skipValidation = !!_skipValidation + args = args || processArgs + options.__ = y18n.__ options.configuration = pkgUp()['yargs'] || {} const parsed = Parser.detailed(args, options) var argv = parsed.argv - if (parseContext) argv = assign(parseContext, argv) + if (parseContext) argv = assign(argv, parseContext) var aliases = parsed.aliases argv.$0 = self.$0 self.parsed = parsed - guessLocale() // guess locale lazily, so that it can be turned off in chain. + try { + guessLocale() // guess locale lazily, so that it can be turned off in chain. - // while building up the argv object, there - // are two passes through the parser. If completion - // is being performed short-circuit on the first pass. - if (shortCircuit) { - return argv - } + // while building up the argv object, there + // are two passes through the parser. If completion + // is being performed short-circuit on the first pass. + if (shortCircuit) { + return argv + } - if (argv._.length) { - // check for helpOpt in argv._ before running commands - // assumes helpOpt must be valid if useHelpOptAsCommand is true - if (useHelpOptAsCommand) { - // consider any multi-char helpOpt alias as a valid help command - // unless all helpOpt aliases are single-char - // note that parsed.aliases is a normalized bidirectional map :) - var helpCmds = [helpOpt].concat(aliases[helpOpt]) - var multiCharHelpCmds = helpCmds.filter(function (k) { - return k.length > 1 - }) - if (multiCharHelpCmds.length) helpCmds = multiCharHelpCmds - // look for and strip any helpCmds from argv._ - argv._ = argv._.filter(function (cmd) { - if (~helpCmds.indexOf(cmd)) { - argv[helpOpt] = true - return false + if (argv._.length) { + // check for helpOpt in argv._ before running commands + // assumes helpOpt must be valid if useHelpOptAsCommand is true + if (useHelpOptAsCommand) { + // consider any multi-char helpOpt alias as a valid help command + // unless all helpOpt aliases are single-char + // note that parsed.aliases is a normalized bidirectional map :) + var helpCmds = [helpOpt].concat(aliases[helpOpt] || []) + var multiCharHelpCmds = helpCmds.filter(function (k) { + return k.length > 1 + }) + if (multiCharHelpCmds.length) helpCmds = multiCharHelpCmds + // look for and strip any helpCmds from argv._ + argv._ = argv._.filter(function (cmd) { + if (~helpCmds.indexOf(cmd)) { + argv[helpOpt] = true + return false + } + return true + }) + } + + // if there's a handler associated with a + // command defer processing to it. + var handlerKeys = command.getCommands() + if (handlerKeys.length) { + var firstUnknownCommand + for (var i = (commandIndex || 0), cmd; argv._[i] !== undefined; i++) { + cmd = String(argv._[i]) + if (~handlerKeys.indexOf(cmd) && cmd !== completionCommand) { + setPlaceholderKeys(argv) + // commands are executed using a recursive algorithm that executes + // the deepest command first; we keep track of the position in the + // argv._ array that is currently being executed. + return command.runCommand(cmd, self, parsed, i + 1) + } else if (!firstUnknownCommand && cmd !== completionCommand) { + firstUnknownCommand = cmd + break + } } - return true - }) - } - // if there's a handler associated with a - // command defer processing to it. - var handlerKeys = command.getCommands() - if (handlerKeys.length) { - var firstUnknownCommand - for (var i = 0, cmd; (cmd = argv._[i]) !== undefined; i++) { - if (~handlerKeys.indexOf(cmd) && cmd !== completionCommand) { + // run the default command, if defined + if (command.hasDefaultCommand() && !argv[helpOpt]) { setPlaceholderKeys(argv) - return command.runCommand(cmd, self, parsed) - } else if (!firstUnknownCommand && cmd !== completionCommand) { - firstUnknownCommand = cmd + return command.runCommand(null, self, parsed) + } + + // recommend a command if recommendCommands() has + // been enabled, and no commands were found to execute + if (recommendCommands && firstUnknownCommand && !argv[helpOpt]) { + validation.recommendCommands(firstUnknownCommand, handlerKeys) } } - // recommend a command if recommendCommands() has - // been enabled, and no commands were found to execute - if (recommendCommands && firstUnknownCommand) { - validation.recommendCommands(firstUnknownCommand, handlerKeys) + // generate a completion script for adding to ~/.bashrc. + if (completionCommand && ~argv._.indexOf(completionCommand) && !argv[completion.completionKey]) { + if (exitProcess) setBlocking(true) + self.showCompletionScript() + self.exit(0) } + } else if (command.hasDefaultCommand() && !argv[helpOpt]) { + setPlaceholderKeys(argv) + return command.runCommand(null, self, parsed) } - // generate a completion script for adding to ~/.bashrc. - if (completionCommand && ~argv._.indexOf(completionCommand) && !argv[completion.completionKey]) { + // we must run completions first, a user might + // want to complete the --help or --version option. + if (completion.completionKey in argv) { if (exitProcess) setBlocking(true) - self.showCompletionScript() - self.exit(0) - } - } - // we must run completions first, a user might - // want to complete the --help or --version option. - if (completion.completionKey in argv) { - if (exitProcess) setBlocking(true) - - // we allow for asynchronous completions, - // e.g., loading in a list of commands from an API. - var completionArgs = args.slice(args.indexOf('--' + completion.completionKey) + 1) - completion.getCompletion(completionArgs, function (completions) { - ;(completions || []).forEach(function (completion) { - _logger.log(completion) - }) - - self.exit(0) - }) - return setPlaceholderKeys(argv) - } - - var skipValidation = false + // we allow for asynchronous completions, + // e.g., loading in a list of commands from an API. + var completionArgs = args.slice(args.indexOf('--' + completion.completionKey) + 1) + completion.getCompletion(completionArgs, function (completions) { + ;(completions || []).forEach(function (completion) { + _logger.log(completion) + }) - // Handle 'help' and 'version' options - Object.keys(argv).forEach(function (key) { - if (key === helpOpt && argv[key]) { - if (exitProcess) setBlocking(true) + self.exit(0) + }) + return setPlaceholderKeys(argv) + } - skipValidation = true - self.showHelp('log') - self.exit(0) - } else if (key === versionOpt && argv[key]) { - if (exitProcess) setBlocking(true) + // Handle 'help' and 'version' options + // if we haven't already output help! + if (!hasOutput) { + Object.keys(argv).forEach(function (key) { + if (key === helpOpt && argv[key]) { + if (exitProcess) setBlocking(true) + + skipValidation = true + self.showHelp('log') + self.exit(0) + } else if (key === versionOpt && argv[key]) { + if (exitProcess) setBlocking(true) + + skipValidation = true + usage.showVersion() + self.exit(0) + } + }) + } - skipValidation = true - usage.showVersion() - self.exit(0) + // Check if any of the options to skip validation were provided + if (!skipValidation && options.skipValidation.length > 0) { + skipValidation = Object.keys(argv).some(function (key) { + return options.skipValidation.indexOf(key) >= 0 && argv[key] === true + }) } - }) - // Check if any of the options to skip validation were provided - if (!skipValidation && options.skipValidation.length > 0) { - skipValidation = Object.keys(argv).some(function (key) { - return options.skipValidation.indexOf(key) >= 0 && argv[key] === true - }) - } + // If the help or version options where used and exitProcess is false, + // or if explicitly skipped, we won't run validations. + if (!skipValidation) { + if (parsed.error) throw new YError(parsed.error.message) - // If the help or version options where used and exitProcess is false, - // or if explicitly skipped, we won't run validations - if (!skipValidation) { - if (parsed.error) throw parsed.error - - // if we're executed via bash completion, don't - // bother with validation. - if (!argv[completion.completionKey]) { - validation.nonOptionCount(argv) - validation.missingArgumentValue(argv) - validation.requiredArguments(argv) - if (strict) validation.unknownArguments(argv, aliases) - validation.customChecks(argv, aliases) - validation.limitedChoices(argv) - validation.implications(argv) - validation.conflicting(argv) + // if we're executed via bash completion, don't + // bother with validation. + if (!argv[completion.completionKey]) { + self._runValidation(argv, aliases, {}, parsed.error) + } } + } catch (err) { + if (err instanceof YError) usage.fail(err.message, err) + else throw err } return setPlaceholderKeys(argv) } + self._runValidation = function (argv, aliases, positionalMap, parseErrors) { + if (parseErrors) throw new YError(parseErrors.message) + validation.nonOptionCount(argv) + validation.missingArgumentValue(argv) + validation.requiredArguments(argv) + if (strict) validation.unknownArguments(argv, aliases, positionalMap) + validation.customChecks(argv, aliases) + validation.limitedChoices(argv) + validation.implications(argv) + validation.conflicting(argv) + } + function guessLocale () { if (!detectLocale) return |