Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

yargs

Package Overview
Dependencies
Maintainers
4
Versions
250
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

yargs - npm Package Compare versions

Comparing version 3.16.1 to 3.17.1

locales/fr.json

4

package.json
{
"name": "yargs",
"version": "3.16.1",
"version": "3.17.1",
"description": "Light-weight option parsing with an argv hash. No optstrings attached.",

@@ -25,3 +25,3 @@ "main": "./index.js",

"mocha": "^2.2.1",
"nyc": "^3.0.0",
"nyc": "^3.1.0",
"standard": "^4.4.0"

@@ -28,0 +28,0 @@ },

653

README.md

@@ -379,127 +379,39 @@ yargs

.default(key, value, [description])
--------------------
.argv
-----
Set `argv[key]` to `value` if no option was specified in `process.argv`.
Get the arguments as a plain old object.
Optionally `.default()` can take an object that maps keys to default values.
Arguments without a corresponding flag show up in the `argv._` array.
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:
The script name or node command is available at `argv.$0` similarly to how `$0`
works in bash or perl.
```js
var argv = require('yargs')
.default('random', function randomValue() {
return Math.random() * 256;
}).argv;
```
.array(key)
----------
Optionally, `description` can also be provided and will take precedence over
displaying the value in the usage instructions:
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'`.
```js
.default('timeout', 60000, '(one-minute)')
```
.boolean(key)
-------------
.demand(key, [msg | boolean])
------------------------------
.require(key, [msg | boolean])
------------------------------
.required(key, [msg | boolean])
------------------------------
.demand(count, [max], [msg])
------------------------------
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`.
If `key` is a string, show the usage information and exit if `key` wasn't
specified in `process.argv`.
`key` will default to `false`, unless a `default(key, undefined)` is
explicitly set.
If `key` is a number, demand at least as many non-option arguments, which show
up in `argv._`. A second number can also optionally be provided, which indicates
the maximum number of non-option arguments.
If `key` is an array, interpret all the elements as booleans.
If `key` is an array, demand each element.
.check(fn)
----------
If a `msg` string is given, it will be printed when the argument is missing,
instead of the standard error message. This is especially helpful for the non-option arguments in `argv._`.
Check that certain conditions are met in the provided arguments.
If a `boolean` value is given, it controls whether the option is demanded;
this is useful when using `.options()` to specify command line parameters.
`fn` is called with two arguments, the parsed `argv` hash and an array of options and their aliases.
.requiresArg(key)
-----------------
If `fn` throws or returns a non-truthy value, show the thrown error, usage information, and
exit.
Specifies either a single option key (string), or an array of options that
must be followed by option values. If any option value is missing, show the
usage information and exit.
The default behaviour is to set the value of any key not followed by an
option value to `true`.
.implies(x, y)
--------------
Given the key `x` is set, it is required that the key `y` is set.
Optionally `.implies()` can accept an object specifying multiple implications.
.describe(key, desc)
--------------------
Describe a `key` for the generated usage information.
Optionally `.describe()` can take an object that maps keys to descriptions.
.option(key, opt)
-----------------
.options(key, opt)
------------------
Instead of chaining together `.alias().demand().default().describe().string()`, you can specify
keys in `opt` for each of the chainable methods.
For example:
````javascript
var argv = require('yargs')
.option('f', {
alias: 'file',
demand: true,
default: '/etc/passwd',
describe: 'x marks the spot',
type: 'string'
})
.argv
;
````
is the same as
````javascript
var argv = require('yargs')
.alias('f', 'file')
.demand('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
;
````
.choices(key, choices)

@@ -539,11 +451,2 @@ ----------------------

.usage(message, [opts])
---------------------
Set a usage message to show which commands to use. Inside `message`, the string
`$0` will get interpolated to the current script name or node command for the
present script similar to how `$0` works in bash or perl.
`opts` is optional and acts like calling `.options(opts)`.
.command(cmd, desc, [fn])

@@ -581,110 +484,142 @@ -------------------

.example(cmd, desc)
-------------------
.completion(cmd, [description], [fn]);
-------------
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.
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`.
.epilogue(str)
--------------
.epilog(str)
------------
`description`: Provide a description in your usage instructions for the command
that generates bash completion scripts.
A message to print at the end of the usage instructions, e.g.
`fn`: Rather than relying on yargs' default completion functionality, which
shiver me timbers is pretty awesome, you can provide your own completion
method.
```js
var argv = require('yargs')
.epilogue('for more information, find our manual at http://example.com');
.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;
```
.check(fn)
----------
But wait, there's more! You can provide asynchronous completions.
Check that certain conditions are met in the provided arguments.
```js
var argv = require('yargs')
.completion('completion', function(current, argv, done) {
setTimeout(function() {
done([
'apple',
'banana'
]);
}, 500);
})
.argv;
```
`fn` is called with two arguments, the parsed `argv` hash and an array of options and their aliases.
.config(key, [description])
------------
If `fn` throws or returns a non-truthy value, show the thrown error, usage information, and
exit.
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. If present, the
`description` parameter customizes the description of the config (`key`) option
in the usage string.
.fail(fn)
---------
.default(key, value, [description])
--------------------
Method to execute when a failure occurs, rather than printing the failure message.
Set `argv[key]` to `value` if no option was specified in `process.argv`.
`fn` is called with the failure message that would have been printed.
Optionally `.default()` can take an object that maps keys to default values.
.boolean(key)
-------------
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:
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`.
```js
var argv = require('yargs')
.default('random', function randomValue() {
return Math.random() * 256;
}).argv;
```
`key` will default to `false`, unless a `default(key, undefined)` is
explicitly set.
Optionally, `description` can also be provided and will take precedence over
displaying the value in the usage instructions:
If `key` is an array, interpret all the elements as booleans.
```js
.default('timeout', 60000, '(one-minute)')
```
.string(key)
------------
<a name="demand-key-msg-boolean"></a>.demand(key, [msg | boolean])
------------------------------
.demand(count, [max], [msg])
------------------------------
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 a string, show the usage information and exit if `key` wasn't
specified in `process.argv`.
If `key` is an array, interpret all the elements as strings.
If `key` is a number, demand at least as many non-option arguments, which show
up in `argv._`. A second number can also optionally be provided, which indicates
the maximum number of non-option arguments.
`.string('_')` will result in non-hyphenated arguments being interpreted as strings,
regardless of whether they resemble numbers.
If `key` is an array, demand each element.
.array(key)
----------
If a `msg` string is given, it will be printed when the argument is missing,
instead of the standard error message. This is especially helpful for the non-option arguments in `argv._`.
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'`.
If a `boolean` value is given, it controls whether the option is demanded;
this is useful when using `.options()` to specify command line parameters.
.nargs(key, count)
-----------
.describe(key, desc)
--------------------
The number of arguments that should be consumed after a key. This can be a
useful hint to prevent parsing ambiguity. For example:
Describe a `key` for the generated usage information.
Optionally `.describe()` can take an object that maps keys to descriptions.
.epilog(str)
------------
.epilogue(str)
--------------
A message to print at the end of the usage instructions, e.g.
```js
var argv = require('yargs')
.nargs('token', 1)
.parse(['--token', '-my-token']);
.epilogue('for more information, find our manual at http://example.com');
```
parses as:
.example(cmd, desc)
-------------------
`{ _: [], token: '-my-token', '$0': 'node test' }`
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.
Optionally `.nargs()` can take an object of `key`/`narg` pairs.
.exitProcess(enable)
----------------------------------
.config(key, [description])
------------
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.
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. If present, the
`description` parameter customizes the description of the config (`key`) option
in the usage string.
.fail(fn)
---------
.wrap(columns)
--------------
Method to execute when a failure occurs, rather than printing the failure message.
Format usage output to wrap at `columns` many columns.
`fn` is called with the failure message that would have been printed.
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.
.strict()
---------
Any command-line argument given that is not demanded, or does not have a
corresponding description, will be reported as an error.
.help([option, [description]])

@@ -709,133 +644,130 @@ ------------------------------

.version(version, [option], [description])
----------------------------------------
.implies(x, y)
--------------
Add an option (e.g. `--version`) that displays the version number (given by the
`version` parameter) and exits the process. If present, the `description`
parameter customizes the description of the version option in the usage string.
Given the key `x` is set, it is required that the key `y` is set.
You can provide a `function` for version, rather than a string.
This is useful if you want to use the version from your package.json:
Optionally `.implies()` can accept an object specifying multiple implications.
.locale(locale)
---------------
Set a locale other than the default `en` locale:
```js
var argv = require('yargs')
.version(function() {
return require('../package').version;
.usage('./$0 - follow ye instructions true')
.option('option', {
alias: 'o',
describe: "'tis a mighty fine option",
demand: true
})
.argv;
.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
```
.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.
```shell
./test.js - follow ye instructions true
line_count.js:
Choose yer command:
run Arrr, ya best be knowin' what yer doin'
````javascript
#!/usr/bin/env node
var argv = require('yargs')
.usage('Count the lines in a file.\nUsage: $0 -f <file>')
.demand('f')
.alias('f', 'file')
.describe('f', 'Load a file')
.string('f')
.showHelpOnFail(false, 'Specify --help for available options')
.help('help')
.argv;
Options for me hearties!
--option, -o 'tis a mighty fine option [requi-yar-ed]
--help Show help [boolean]
// etc.
````
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
```
$ node line_count.js
Missing argument value: f
Locales currently supported:
Specify --help for available options
* **en:** American English.
* **fr:** French.
* **pirate:** American Pirate.
.showHelp(consoleLevel='error')
---------------------------
To submit a new translation for yargs:
Print the usage data using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel` for printing.
1. use `./locales/en.json` as a starting point.
2. submit a pull request with the new locale file.
Example:
.nargs(key, count)
-----------
```js
var yargs = require("yargs")
.usage("$0 -operand1 number -operand2 number -operation [add|subtract]");
yargs.showHelp(); //prints to stderr using console.error()
```
The number of arguments that should be consumed after a key. This can be a
useful hint to prevent parsing ambiguity. For example:
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()
var argv = require('yargs')
.nargs('token', 1)
.parse(['--token', '-my-token']);
```
Later on, `argv` can be retrieved with `yargs.argv`.
parses as:
.completion(cmd, [description], [fn]);
-------------
`{ _: [], token: '-my-token', '$0': 'node test' }`
Enable bash-completion shortcuts for commands and options.
Optionally `.nargs()` can take an object of `key`/`narg` pairs.
`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`.
.option(key, opt)
-----------------
.options(key, opt)
------------------
`description`: Provide a description in your usage instructions for the command
that generates bash completion scripts.
Instead of chaining together `.alias().demand().default().describe().string()`, you can specify
keys in `opt` for each of the chainable methods.
`fn`: Rather than relying on yargs' default completion functionality, which
shiver me timbers is pretty awesome, you can provide your own completion
method.
For example:
```js
````javascript
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;
```
.option('f', {
alias: 'file',
demand: true,
default: '/etc/passwd',
describe: 'x marks the spot',
type: 'string'
})
.argv
;
````
But wait, there's more! You can provide asynchronous completions.
is the same as
```js
````javascript
var argv = require('yargs')
.completion('completion', function(current, argv, done) {
setTimeout(function() {
done([
'apple',
'banana'
]);
}, 500);
})
.argv;
```
.alias('f', 'file')
.demand('f')
.default('f', '/etc/passwd')
.describe('f', 'x marks the spot')
.string('f')
.argv
;
````
.showCompletionScript()
----------------------
Optionally `.options()` can take an object that maps keys to `opt` parameters.
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.
````javascript
var argv = require('yargs')
.options({
'f': {
alias: 'file',
demand: true,
default: '/etc/passwd',
describe: 'x marks the spot',
type: 'string'
}
})
.argv
;
````
.exitProcess(enable)
----------------------------------
By default, yargs exits the process when the user passes a help flag, uses the
`.version` functionality, or when validation fails. Calling
`.exitProcess(false)` disables this behavior, enabling further actions after
yargs have been validated.
.parse(args)

@@ -846,2 +778,19 @@ ------------

.require(key, [msg | boolean])
------------------------------
.required(key, [msg | boolean])
------------------------------
An alias for [`demand()`](#demand-key-msg-boolean). See docs there.
.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`.
.reset()

@@ -883,50 +832,81 @@ --------

.locale(locale)
---------------
.showCompletionScript()
----------------------
Set a locale other than the default `en` locale:
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 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')
.locale('pirate')
.argv
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`:
```shell
./test.js - follow ye instructions true
```js
yargs.showHelp("log"); //prints to stdout using console.log()
```
Choose yer command:
run Arrr, ya best be knowin' what yer doin'
Later on, `argv` can be retrieved with `yargs.argv`.
Options for me hearties!
--option, -o 'tis a mighty fine option [requi-yar-ed]
--help Show help [boolean]
.showHelpOnFail(enable, [message])
----------------------------------
Ex. marks the spot:
test.js run foo shiver me timbers, here's an example for ye
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.
Ye be havin' to set the followin' argument land lubber: option
line_count.js:
````javascript
#!/usr/bin/env node
var argv = require('yargs')
.usage('Count the lines in a file.\nUsage: $0 -f <file>')
.demand('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
Locales currently supported:
Specify --help for available options
```
* **en:** American English.
* **pirate:** American Pirate.
.strict()
---------
To submit a new translation for yargs:
Any command-line argument given that is not demanded, or does not have a
corresponding description, will be reported as an error.
1. use `./locales/en.json` as a starting point.
2. submit a pull request with the new locale file.
.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)

@@ -947,2 +927,3 @@ ------------------

})
.wrap(null)
.argv

@@ -959,15 +940,41 @@ ```

Options:
--help Show help [boolean]
--help Show help [boolean]
```
.argv
-----
.usage(message, [opts])
---------------------
Get the arguments as a plain old object.
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.
Arguments without a corresponding flag show up in the `argv._` array.
`opts` is optional and acts like calling `.options(opts)`.
The script name or node command is available at `argv.$0` similarly to how `$0`
works in bash or perl.
.version(version, [option], [description])
----------------------------------------
Add an option (e.g. `--version`) that displays the version number (given by the
`version` parameter) and exits the process. If present, the `description`
parameter customizes the description of the version option in the usage string.
You can provide a `function` for version, rather than a string.
This is useful if you want to use the version from your package.json:
```js
var argv = require('yargs')
.version(function() {
return require('../package').version;
})
.argv;
```
.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

@@ -974,0 +981,0 @@ ==============

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc