.config/coc/extensions/node_modules/coc-prettier/node_modules/yargs-parser/README.md

   1 # yargs-parser
   2
   3 [![Build Status](https://travis-ci.org/yargs/yargs-parser.png)](https://travis-ci.org/yargs/yargs-parser)
   4 [![Coverage Status](https://coveralls.io/repos/yargs/yargs-parser/badge.svg?branch=)](https://coveralls.io/r/yargs/yargs-parser?branch=master)
   5 [![NPM version](https://img.shields.io/npm/v/yargs-parser.svg)](https://www.npmjs.com/package/yargs-parser)
   6 [![Windows Tests](https://img.shields.io/appveyor/ci/bcoe/yargs-parser/master.svg?label=Windows%20Tests)](https://ci.appveyor.com/project/bcoe/yargs-parser)
   7 [![Standard Version](https://img.shields.io/badge/release-standard%20version-brightgreen.svg)](https://github.com/conventional-changelog/standard-version)
   8
   9
  10 The mighty option parser used by [yargs](https://github.com/yargs/yargs).
  11
  12 visit the [yargs website](http://yargs.js.org/) for more examples, and thorough usage instructions.
  13
  14 <img width="250" src="https://raw.githubusercontent.com/yargs/yargs-parser/master/yargs-logo.png">
  15
  16 ## Example
  17
  18 ```sh
  19 npm i yargs-parser --save
  20 ```
  21
  22 ```js
  23 var argv = require('yargs-parser')(process.argv.slice(2))
  24 console.log(argv)
  25 ```
  26
  27 ```sh
  28 node example.js --foo=33 --bar hello
  29 { _: [], foo: 33, bar: 'hello' }
  30 ```
  31
  32 _or parse a string!_
  33
  34 ```js
  35 var argv = require('./')('--foo=99 --bar=33')
  36 console.log(argv)
  37 ```
  38
  39 ```sh
  40 { _: [], foo: 99, bar: 33 }
  41 ```
  42
  43 Convert an array of mixed types before passing to `yargs-parser`:
  44
  45 ```js
  46 var parse = require('yargs-parser')
  47 parse(['-f', 11, '--zoom', 55].join(' '))   // <-- array to string
  48 parse(['-f', 11, '--zoom', 55].map(String)) // <-- array of strings
  49 ```
  50
  51 ## API
  52
  53 ### require('yargs-parser')(args, opts={})
  54
  55 Parses command line arguments returning a simple mapping of keys and values.
  56
  57 **expects:**
  58
  59 * `args`: a string or array of strings representing the options to parse.
  60 * `opts`: provide a set of hints indicating how `args` should be parsed:
  61   * `opts.alias`: an object representing the set of aliases for a key: `{alias: {foo: ['f']}}`.
  62   * `opts.array`: indicate that keys should be parsed as an array: `{array: ['foo', 'bar']}`.
  63   * `opts.boolean`: arguments should be parsed as booleans: `{boolean: ['x', 'y']}`.
  64   * `opts.config`: indicate a key that represents a path to a configuration file (this file will be loaded and parsed).
  65   * `opts.coerce`: provide a custom synchronous function that returns a coerced value from the argument provided
  66     (or throws an error), e.g. `{coerce: {foo: function (arg) {return modifiedArg}}}`.
  67   * `opts.count`: indicate a key that should be used as a counter, e.g., `-vvv` = `{v: 3}`.
  68   * `opts.default`: provide default values for keys: `{default: {x: 33, y: 'hello world!'}}`.
  69   * `opts.envPrefix`: environment variables (`process.env`) with the prefix provided should be parsed.
  70   * `opts.narg`: specify that a key requires `n` arguments: `{narg: {x: 2}}`.
  71   * `opts.normalize`: `path.normalize()` will be applied to values set to this key.
  72   * `opts.string`: keys should be treated as strings (even if they resemble a number `-x 33`).
  73   * `opts.configuration`: provide configuration options to the yargs-parser (see: [configuration](#configuration)).
  74   * `opts.number`: keys should be treated as numbers.
  75   * `opts['--']`: arguments after the end-of-options flag `--` will be set to the `argv.['--']` array instead of being set to the `argv._` array.
  76
  77 **returns:**
  78
  79 * `obj`: an object representing the parsed value of `args`
  80   * `key/value`: key value pairs for each argument and their aliases.
  81   * `_`: an array representing the positional arguments.
  82   * [optional] `--`:  an array with arguments after the end-of-options flag `--`.
  83
  84 ### require('yargs-parser').detailed(args, opts={})
  85
  86 Parses a command line string, returning detailed information required by the
  87 yargs engine.
  88
  89 **expects:**
  90
  91 * `args`: a string or array of strings representing options to parse.
  92 * `opts`: provide a set of hints indicating how `args`, inputs are identical to `require('yargs-parser')(args, opts={})`.
  93
  94 **returns:**
  95
  96 * `argv`: an object representing the parsed value of `args`
  97   * `key/value`: key value pairs for each argument and their aliases.
  98   * `_`: an array representing the positional arguments.
  99 * `error`: populated with an error object if an exception occurred during parsing.
 100 * `aliases`: the inferred list of aliases built by combining lists in `opts.alias`.
 101 * `newAliases`: any new aliases added via camel-case expansion.
 102 * `configuration`: the configuration loaded from the `yargs` stanza in package.json.
 103
 104 <a name="configuration"></a>
 105
 106 ### Configuration
 107
 108 The yargs-parser applies several automated transformations on the keys provided
 109 in `args`. These features can be turned on and off using the `configuration` field
 110 of `opts`.
 111
 112 ```js
 113 var parsed = parser(['--no-dice'], {
 114   configuration: {
 115     'boolean-negation': false
 116   }
 117 })
 118 ```
 119
 120 ### short option groups
 121
 122 * default: `true`.
 123 * key: `short-option-groups`.
 124
 125 Should a group of short-options be treated as boolean flags?
 126
 127 ```sh
 128 node example.js -abc
 129 { _: [], a: true, b: true, c: true }
 130 ```
 131
 132 _if disabled:_
 133
 134 ```sh
 135 node example.js -abc
 136 { _: [], abc: true }
 137 ```
 138
 139 ### camel-case expansion
 140
 141 * default: `true`.
 142 * key: `camel-case-expansion`.
 143
 144 Should hyphenated arguments be expanded into camel-case aliases?
 145
 146 ```sh
 147 node example.js --foo-bar
 148 { _: [], 'foo-bar': true, fooBar: true }
 149 ```
 150
 151 _if disabled:_
 152
 153 ```sh
 154 node example.js --foo-bar
 155 { _: [], 'foo-bar': true }
 156 ```
 157
 158 ### dot-notation
 159
 160 * default: `true`
 161 * key: `dot-notation`
 162
 163 Should keys that contain `.` be treated as objects?
 164
 165 ```sh
 166 node example.js --foo.bar
 167 { _: [], foo: { bar: true } }
 168 ```
 169
 170 _if disabled:_
 171
 172 ```sh
 173 node example.js --foo.bar
 174 { _: [], "foo.bar": true }
 175 ```
 176
 177 ### parse numbers
 178
 179 * default: `true`
 180 * key: `parse-numbers`
 181
 182 Should keys that look like numbers be treated as such?
 183
 184 ```sh
 185 node example.js --foo=99.3
 186 { _: [], foo: 99.3 }
 187 ```
 188
 189 _if disabled:_
 190
 191 ```sh
 192 node example.js --foo=99.3
 193 { _: [], foo: "99.3" }
 194 ```
 195
 196 ### boolean negation
 197
 198 * default: `true`
 199 * key: `boolean-negation`
 200
 201 Should variables prefixed with `--no` be treated as negations?
 202
 203 ```sh
 204 node example.js --no-foo
 205 { _: [], foo: false }
 206 ```
 207
 208 _if disabled:_
 209
 210 ```sh
 211 node example.js --no-foo
 212 { _: [], "no-foo": true }
 213 ```
 214
 215 ### combine arrays
 216
 217 * default: `false`
 218 * key: `combine-arrays`
 219
 220 Should arrays be combined when provided by both command line arguments and
 221 a configuration file.
 222
 223 ### duplicate arguments array
 224
 225 * default: `true`
 226 * key: `duplicate-arguments-array`
 227
 228 Should arguments be coerced into an array when duplicated:
 229
 230 ```sh
 231 node example.js -x 1 -x 2
 232 { _: [], x: [1, 2] }
 233 ```
 234
 235 _if disabled:_
 236
 237 ```sh
 238 node example.js -x 1 -x 2
 239 { _: [], x: 2 }
 240 ```
 241
 242 ### flatten duplicate arrays
 243
 244 * default: `true`
 245 * key: `flatten-duplicate-arrays`
 246
 247 Should array arguments be coerced into a single array when duplicated:
 248
 249 ```sh
 250 node example.js -x 1 2 -x 3 4
 251 { _: [], x: [1, 2, 3, 4] }
 252 ```
 253
 254 _if disabled:_
 255
 256 ```sh
 257 node example.js -x 1 2 -x 3 4
 258 { _: [], x: [[1, 2], [3, 4]] }
 259 ```
 260
 261 ### negation prefix
 262
 263 * default: `no-`
 264 * key: `negation-prefix`
 265
 266 The prefix to use for negated boolean variables.
 267
 268 ```sh
 269 node example.js --no-foo
 270 { _: [], foo: false }
 271 ```
 272
 273 _if set to `quux`:_
 274
 275 ```sh
 276 node example.js --quuxfoo
 277 { _: [], foo: false }
 278 ```
 279
 280 ### populate --
 281
 282 * default: `false`.
 283 * key: `populate--`
 284
 285 Should unparsed flags be stored in `--` or `_`.
 286
 287 _If disabled:_
 288
 289 ```sh
 290 node example.js a -b -- x y
 291 { _: [ 'a', 'x', 'y' ], b: true }
 292 ```
 293
 294 _If enabled:_
 295
 296 ```sh
 297 node example.js a -b -- x y
 298 { _: [ 'a' ], '--': [ 'x', 'y' ], b: true }
 299 ```
 300
 301 ## Special Thanks
 302
 303 The yargs project evolves from optimist and minimist. It owes its
 304 existence to a lot of James Halliday's hard work. Thanks [substack](https://github.com/substack) **beep** **boop** \o/
 305
 306 ## License
 307
 308 ISC