136 lines
5.2 KiB
Handlebars
136 lines
5.2 KiB
Handlebars
[](https://www.npmjs.org/package/command-line-args)
|
|
[](https://www.npmjs.org/package/command-line-args)
|
|
[](https://travis-ci.org/75lb/command-line-args)
|
|
[](https://coveralls.io/github/75lb/command-line-args?branch=master)
|
|
[](https://david-dm.org/75lb/command-line-args)
|
|
[](https://github.com/feross/standard)
|
|
[](https://gitter.im/75lb/command-line-args?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
|
|
# command-line-args
|
|
A mature, feature-complete library to parse command-line options.
|
|
|
|
*If your app requires a git-like command interface, consider using [command-line-commands](https://github.com/75lb/command-line-commands).*
|
|
|
|
## Synopsis
|
|
You can set options using the main notation standards (getopt, getopt_long, etc.). These commands are all equivalent, setting the same values:
|
|
```
|
|
$ example --verbose --timeout=1000 --src one.js --src two.js
|
|
$ example --verbose --timeout 1000 --src one.js two.js
|
|
$ example -vt 1000 --src one.js two.js
|
|
$ example -vt 1000 one.js two.js
|
|
```
|
|
|
|
To access the values, first describe the options your app accepts (see [option definitions](#optiondefinition-)).
|
|
```js
|
|
const commandLineArgs = require('command-line-args')
|
|
|
|
const optionDefinitions = [
|
|
{ name: 'verbose', alias: 'v', type: Boolean },
|
|
{ name: 'src', type: String, multiple: true, defaultOption: true },
|
|
{ name: 'timeout', alias: 't', type: Number }
|
|
]
|
|
```
|
|
The [`type`](#optiontype--function) property is a setter function (the value supplied is passed through this), giving you full control over the value received.
|
|
|
|
Next, parse the options using [commandLineArgs()](#commandlineargsdefinitions-argv--object-):
|
|
```js
|
|
const options = commandLineArgs(optionDefinitions)
|
|
```
|
|
|
|
`options` now looks like this:
|
|
```js
|
|
{
|
|
files: [
|
|
'one.js',
|
|
'two.js'
|
|
],
|
|
verbose: true,
|
|
timeout: 1000
|
|
}
|
|
```
|
|
|
|
When dealing with large amounts of options it often makes sense to [group](#optiongroup--string--arraystring) them.
|
|
|
|
A usage guide can be generated using [command-line-usage](https://github.com/75lb/command-line-usage), for example:
|
|
|
|
|
|
|
|
### Notation rules
|
|
|
|
Notation rules for setting command-line options.
|
|
|
|
* Argument order is insignificant. Whether you set `--example` at the beginning or end of the arg list makes no difference.
|
|
* Options with a [type](#optiontype--function) of `Boolean` do not need to supply a value. Setting `--flag` or `-f` will set that option's value to `true`. This is the only [type](#optiontype--function) with special behaviour.
|
|
* Three ways to set an option value
|
|
* `--option value`
|
|
* `--option=value`
|
|
* `-o value`
|
|
* Two ways to a set list of values (on options with [multiple](#optionmultiple--boolean) set)
|
|
* `--list one two three`
|
|
* `--list one --list two --list three`
|
|
* Short options ([alias](#optionalias--string)) can be set in groups. The following are equivalent:
|
|
* `-a -b -c`
|
|
* `-abc`
|
|
|
|
### Ambiguous values
|
|
|
|
Imagine we are using "grep-tool" to search for the string `'-f'`:
|
|
|
|
```
|
|
$ grep-tool --search -f
|
|
```
|
|
|
|
We have an issue here: command-line-args will assume we are setting two options (`--search` and `-f`). In actuality, we are passing one option (`--search`) and one value (`-f`). In cases like this, avoid ambiguity by using `--option=value` notation:
|
|
|
|
```
|
|
$ grep-tool --search=-f
|
|
```
|
|
|
|
### Partial parsing
|
|
|
|
By default, if the user sets an option without a valid [definition](#exp_module_definition--OptionDefinition) an `UNKNOWN_OPTION` exception is thrown. However, in some cases you may only be interested in a subset of the options wishing to pass the remainder to another library. See [here](https://github.com/75lb/command-line-args/blob/master/example/mocha.js) for a example showing where this might be necessary.
|
|
|
|
To enable partial parsing, set `partial: true` in the method options:
|
|
|
|
```js
|
|
const optionDefinitions = [
|
|
{ name: 'value', type: Number }
|
|
]
|
|
const options = commandLineArgs(optionDefinitions, { partial: true })
|
|
```
|
|
|
|
Now, should any unknown args be passed at the command line:
|
|
|
|
```
|
|
$ example --milk --value 2 --bread cheese
|
|
```
|
|
|
|
They will be returned in the `_unknown` property of the `commandLineArgs` output with no exceptions thrown:
|
|
|
|
```js
|
|
{
|
|
value: 2,
|
|
_unknown: [ '--milk', '--bread', 'cheese']
|
|
}
|
|
```
|
|
|
|
|
|
## Install
|
|
|
|
```sh
|
|
$ npm install command-line-args --save
|
|
```
|
|
|
|
# API Reference
|
|
{{#module name="command-line-args"}}
|
|
{{>body~}}
|
|
{{>member-index~}}
|
|
{{>separator~}}
|
|
{{>members~}}
|
|
{{/module}}
|
|
{{#class name="OptionDefinition"}}{{>docs}}{{/class}}
|
|
|
|
* * *
|
|
|
|
© 2014-17 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).
|