README.md
1 # yargs-parser 2 3  4 [](https://www.npmjs.com/package/yargs-parser) 5 [](https://conventionalcommits.org) 6  7 8 The mighty option parser used by [yargs](https://github.com/yargs/yargs). 9 10 visit the [yargs website](http://yargs.js.org/) for more examples, and thorough usage instructions. 11 12 <img width="250" src="https://raw.githubusercontent.com/yargs/yargs-parser/main/yargs-logo.png"> 13 14 ## Example 15 16 ```sh 17 npm i yargs-parser --save 18 ``` 19 20 ```js 21 const argv = require('yargs-parser')(process.argv.slice(2)) 22 console.log(argv) 23 ``` 24 25 ```console 26 $ node example.js --foo=33 --bar hello 27 { _: [], foo: 33, bar: 'hello' } 28 ``` 29 30 _or parse a string!_ 31 32 ```js 33 const argv = require('yargs-parser')('--foo=99 --bar=33') 34 console.log(argv) 35 ``` 36 37 ```console 38 { _: [], foo: 99, bar: 33 } 39 ``` 40 41 Convert an array of mixed types before passing to `yargs-parser`: 42 43 ```js 44 const parse = require('yargs-parser') 45 parse(['-f', 11, '--zoom', 55].join(' ')) // <-- array to string 46 parse(['-f', 11, '--zoom', 55].map(String)) // <-- array of strings 47 ``` 48 49 ## Deno Example 50 51 As of `v19` `yargs-parser` supports [Deno](https://github.com/denoland/deno): 52 53 ```typescript 54 import parser from "https://deno.land/x/yargs_parser/deno.ts"; 55 56 const argv = parser('--foo=99 --bar=9987930', { 57 string: ['bar'] 58 }) 59 console.log(argv) 60 ``` 61 62 ## ESM Example 63 64 As of `v19` `yargs-parser` supports ESM (_both in Node.js and in the browser_): 65 66 **Node.js:** 67 68 ```js 69 import parser from 'yargs-parser' 70 71 const argv = parser('--foo=99 --bar=9987930', { 72 string: ['bar'] 73 }) 74 console.log(argv) 75 ``` 76 77 **Browsers:** 78 79 ```html 80 <!doctype html> 81 <body> 82 <script type="module"> 83 import parser from "https://unpkg.com/yargs-parser@19.0.0/browser.js"; 84 85 const argv = parser('--foo=99 --bar=9987930', { 86 string: ['bar'] 87 }) 88 console.log(argv) 89 </script> 90 </body> 91 ``` 92 93 ## API 94 95 ### parser(args, opts={}) 96 97 Parses command line arguments returning a simple mapping of keys and values. 98 99 **expects:** 100 101 * `args`: a string or array of strings representing the options to parse. 102 * `opts`: provide a set of hints indicating how `args` should be parsed: 103 * `opts.alias`: an object representing the set of aliases for a key: `{alias: {foo: ['f']}}`. 104 * `opts.array`: indicate that keys should be parsed as an array: `{array: ['foo', 'bar']}`.<br> 105 Indicate that keys should be parsed as an array and coerced to booleans / numbers:<br> 106 `{array: [{ key: 'foo', boolean: true }, {key: 'bar', number: true}]}`. 107 * `opts.boolean`: arguments should be parsed as booleans: `{boolean: ['x', 'y']}`. 108 * `opts.coerce`: provide a custom synchronous function that returns a coerced value from the argument provided 109 (or throws an error). For arrays the function is called only once for the entire array:<br> 110 `{coerce: {foo: function (arg) {return modifiedArg}}}`. 111 * `opts.config`: indicate a key that represents a path to a configuration file (this file will be loaded and parsed). 112 * `opts.configObjects`: configuration objects to parse, their properties will be set as arguments:<br> 113 `{configObjects: [{'x': 5, 'y': 33}, {'z': 44}]}`. 114 * `opts.configuration`: provide configuration options to the yargs-parser (see: [configuration](#configuration)). 115 * `opts.count`: indicate a key that should be used as a counter, e.g., `-vvv` = `{v: 3}`. 116 * `opts.default`: provide default values for keys: `{default: {x: 33, y: 'hello world!'}}`. 117 * `opts.envPrefix`: environment variables (`process.env`) with the prefix provided should be parsed. 118 * `opts.narg`: specify that a key requires `n` arguments: `{narg: {x: 2}}`. 119 * `opts.normalize`: `path.normalize()` will be applied to values set to this key. 120 * `opts.number`: keys should be treated as numbers. 121 * `opts.string`: keys should be treated as strings (even if they resemble a number `-x 33`). 122 123 **returns:** 124 125 * `obj`: an object representing the parsed value of `args` 126 * `key/value`: key value pairs for each argument and their aliases. 127 * `_`: an array representing the positional arguments. 128 * [optional] `--`: an array with arguments after the end-of-options flag `--`. 129 130 ### require('yargs-parser').detailed(args, opts={}) 131 132 Parses a command line string, returning detailed information required by the 133 yargs engine. 134 135 **expects:** 136 137 * `args`: a string or array of strings representing options to parse. 138 * `opts`: provide a set of hints indicating how `args`, inputs are identical to `require('yargs-parser')(args, opts={})`. 139 140 **returns:** 141 142 * `argv`: an object representing the parsed value of `args` 143 * `key/value`: key value pairs for each argument and their aliases. 144 * `_`: an array representing the positional arguments. 145 * [optional] `--`: an array with arguments after the end-of-options flag `--`. 146 * `error`: populated with an error object if an exception occurred during parsing. 147 * `aliases`: the inferred list of aliases built by combining lists in `opts.alias`. 148 * `newAliases`: any new aliases added via camel-case expansion: 149 * `boolean`: `{ fooBar: true }` 150 * `defaulted`: any new argument created by `opts.default`, no aliases included. 151 * `boolean`: `{ foo: true }` 152 * `configuration`: given by default settings and `opts.configuration`. 153 154 <a name="configuration"></a> 155 156 ### Configuration 157 158 The yargs-parser applies several automated transformations on the keys provided 159 in `args`. These features can be turned on and off using the `configuration` field 160 of `opts`. 161 162 ```js 163 var parsed = parser(['--no-dice'], { 164 configuration: { 165 'boolean-negation': false 166 } 167 }) 168 ``` 169 170 ### short option groups 171 172 * default: `true`. 173 * key: `short-option-groups`. 174 175 Should a group of short-options be treated as boolean flags? 176 177 ```console 178 $ node example.js -abc 179 { _: [], a: true, b: true, c: true } 180 ``` 181 182 _if disabled:_ 183 184 ```console 185 $ node example.js -abc 186 { _: [], abc: true } 187 ``` 188 189 ### camel-case expansion 190 191 * default: `true`. 192 * key: `camel-case-expansion`. 193 194 Should hyphenated arguments be expanded into camel-case aliases? 195 196 ```console 197 $ node example.js --foo-bar 198 { _: [], 'foo-bar': true, fooBar: true } 199 ``` 200 201 _if disabled:_ 202 203 ```console 204 $ node example.js --foo-bar 205 { _: [], 'foo-bar': true } 206 ``` 207 208 ### dot-notation 209 210 * default: `true` 211 * key: `dot-notation` 212 213 Should keys that contain `.` be treated as objects? 214 215 ```console 216 $ node example.js --foo.bar 217 { _: [], foo: { bar: true } } 218 ``` 219 220 _if disabled:_ 221 222 ```console 223 $ node example.js --foo.bar 224 { _: [], "foo.bar": true } 225 ``` 226 227 ### parse numbers 228 229 * default: `true` 230 * key: `parse-numbers` 231 232 Should keys that look like numbers be treated as such? 233 234 ```console 235 $ node example.js --foo=99.3 236 { _: [], foo: 99.3 } 237 ``` 238 239 _if disabled:_ 240 241 ```console 242 $ node example.js --foo=99.3 243 { _: [], foo: "99.3" } 244 ``` 245 246 ### parse positional numbers 247 248 * default: `true` 249 * key: `parse-positional-numbers` 250 251 Should positional keys that look like numbers be treated as such. 252 253 ```console 254 $ node example.js 99.3 255 { _: [99.3] } 256 ``` 257 258 _if disabled:_ 259 260 ```console 261 $ node example.js 99.3 262 { _: ['99.3'] } 263 ``` 264 265 ### boolean negation 266 267 * default: `true` 268 * key: `boolean-negation` 269 270 Should variables prefixed with `--no` be treated as negations? 271 272 ```console 273 $ node example.js --no-foo 274 { _: [], foo: false } 275 ``` 276 277 _if disabled:_ 278 279 ```console 280 $ node example.js --no-foo 281 { _: [], "no-foo": true } 282 ``` 283 284 ### combine arrays 285 286 * default: `false` 287 * key: `combine-arrays` 288 289 Should arrays be combined when provided by both command line arguments and 290 a configuration file. 291 292 ### duplicate arguments array 293 294 * default: `true` 295 * key: `duplicate-arguments-array` 296 297 Should arguments be coerced into an array when duplicated: 298 299 ```console 300 $ node example.js -x 1 -x 2 301 { _: [], x: [1, 2] } 302 ``` 303 304 _if disabled:_ 305 306 ```console 307 $ node example.js -x 1 -x 2 308 { _: [], x: 2 } 309 ``` 310 311 ### flatten duplicate arrays 312 313 * default: `true` 314 * key: `flatten-duplicate-arrays` 315 316 Should array arguments be coerced into a single array when duplicated: 317 318 ```console 319 $ node example.js -x 1 2 -x 3 4 320 { _: [], x: [1, 2, 3, 4] } 321 ``` 322 323 _if disabled:_ 324 325 ```console 326 $ node example.js -x 1 2 -x 3 4 327 { _: [], x: [[1, 2], [3, 4]] } 328 ``` 329 330 ### greedy arrays 331 332 * default: `true` 333 * key: `greedy-arrays` 334 335 Should arrays consume more than one positional argument following their flag. 336 337 ```console 338 $ node example --arr 1 2 339 { _: [], arr: [1, 2] } 340 ``` 341 342 _if disabled:_ 343 344 ```console 345 $ node example --arr 1 2 346 { _: [2], arr: [1] } 347 ``` 348 349 **Note: in `v18.0.0` we are considering defaulting greedy arrays to `false`.** 350 351 ### nargs eats options 352 353 * default: `false` 354 * key: `nargs-eats-options` 355 356 Should nargs consume dash options as well as positional arguments. 357 358 ### negation prefix 359 360 * default: `no-` 361 * key: `negation-prefix` 362 363 The prefix to use for negated boolean variables. 364 365 ```console 366 $ node example.js --no-foo 367 { _: [], foo: false } 368 ``` 369 370 _if set to `quux`:_ 371 372 ```console 373 $ node example.js --quuxfoo 374 { _: [], foo: false } 375 ``` 376 377 ### populate -- 378 379 * default: `false`. 380 * key: `populate--` 381 382 Should unparsed flags be stored in `--` or `_`. 383 384 _If disabled:_ 385 386 ```console 387 $ node example.js a -b -- x y 388 { _: [ 'a', 'x', 'y' ], b: true } 389 ``` 390 391 _If enabled:_ 392 393 ```console 394 $ node example.js a -b -- x y 395 { _: [ 'a' ], '--': [ 'x', 'y' ], b: true } 396 ``` 397 398 ### set placeholder key 399 400 * default: `false`. 401 * key: `set-placeholder-key`. 402 403 Should a placeholder be added for keys not set via the corresponding CLI argument? 404 405 _If disabled:_ 406 407 ```console 408 $ node example.js -a 1 -c 2 409 { _: [], a: 1, c: 2 } 410 ``` 411 412 _If enabled:_ 413 414 ```console 415 $ node example.js -a 1 -c 2 416 { _: [], a: 1, b: undefined, c: 2 } 417 ``` 418 419 ### halt at non-option 420 421 * default: `false`. 422 * key: `halt-at-non-option`. 423 424 Should parsing stop at the first positional argument? This is similar to how e.g. `ssh` parses its command line. 425 426 _If disabled:_ 427 428 ```console 429 $ node example.js -a run b -x y 430 { _: [ 'b' ], a: 'run', x: 'y' } 431 ``` 432 433 _If enabled:_ 434 435 ```console 436 $ node example.js -a run b -x y 437 { _: [ 'b', '-x', 'y' ], a: 'run' } 438 ``` 439 440 ### strip aliased 441 442 * default: `false` 443 * key: `strip-aliased` 444 445 Should aliases be removed before returning results? 446 447 _If disabled:_ 448 449 ```console 450 $ node example.js --test-field 1 451 { _: [], 'test-field': 1, testField: 1, 'test-alias': 1, testAlias: 1 } 452 ``` 453 454 _If enabled:_ 455 456 ```console 457 $ node example.js --test-field 1 458 { _: [], 'test-field': 1, testField: 1 } 459 ``` 460 461 ### strip dashed 462 463 * default: `false` 464 * key: `strip-dashed` 465 466 Should dashed keys be removed before returning results? This option has no effect if 467 `camel-case-expansion` is disabled. 468 469 _If disabled:_ 470 471 ```console 472 $ node example.js --test-field 1 473 { _: [], 'test-field': 1, testField: 1 } 474 ``` 475 476 _If enabled:_ 477 478 ```console 479 $ node example.js --test-field 1 480 { _: [], testField: 1 } 481 ``` 482 483 ### unknown options as args 484 485 * default: `false` 486 * key: `unknown-options-as-args` 487 488 Should unknown options be treated like regular arguments? An unknown option is one that is not 489 configured in `opts`. 490 491 _If disabled_ 492 493 ```console 494 $ node example.js --unknown-option --known-option 2 --string-option --unknown-option2 495 { _: [], unknownOption: true, knownOption: 2, stringOption: '', unknownOption2: true } 496 ``` 497 498 _If enabled_ 499 500 ```console 501 $ node example.js --unknown-option --known-option 2 --string-option --unknown-option2 502 { _: ['--unknown-option'], knownOption: 2, stringOption: '--unknown-option2' } 503 ``` 504 505 ## Supported Node.js Versions 506 507 Libraries in this ecosystem make a best effort to track 508 [Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a 509 post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a). 510 511 ## Special Thanks 512 513 The yargs project evolves from optimist and minimist. It owes its 514 existence to a lot of James Halliday's hard work. Thanks [substack](https://github.com/substack) **beep** **boop** \o/ 515 516 ## License 517 518 ISC