1# yargs-parser
2
3![ci](https://github.com/yargs/yargs-parser/workflows/ci/badge.svg)
4[![NPM version](https://img.shields.io/npm/v/yargs-parser.svg)](https://www.npmjs.com/package/yargs-parser)
5[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
6![nycrc config on GitHub](https://img.shields.io/nycrc/yargs/yargs-parser)
7
8The mighty option parser used by [yargs](https://github.com/yargs/yargs).
9
10visit 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
17npm i yargs-parser --save
18```
19
20```js
21const argv = require('yargs-parser')(process.argv.slice(2))
22console.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
33const argv = require('yargs-parser')('--foo=99 --bar=33')
34console.log(argv)
35```
36
37```console
38{ _: [], foo: 99, bar: 33 }
39```
40
41Convert an array of mixed types before passing to `yargs-parser`:
42
43```js
44const parse = require('yargs-parser')
45parse(['-f', 11, '--zoom', 55].join(' '))   // <-- array to string
46parse(['-f', 11, '--zoom', 55].map(String)) // <-- array of strings
47```
48
49## Deno Example
50
51As of `v19` `yargs-parser` supports [Deno](https://github.com/denoland/deno):
52
53```typescript
54import parser from "https://deno.land/x/yargs_parser/deno.ts";
55
56const argv = parser('--foo=99 --bar=9987930', {
57  string: ['bar']
58})
59console.log(argv)
60```
61
62## ESM Example
63
64As of `v19` `yargs-parser` supports ESM (_both in Node.js and in the browser_):
65
66**Node.js:**
67
68```js
69import parser from 'yargs-parser'
70
71const argv = parser('--foo=99 --bar=9987930', {
72  string: ['bar']
73})
74console.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
97Parses 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
132Parses a command line string, returning detailed information required by the
133yargs 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
158The yargs-parser applies several automated transformations on the keys provided
159in `args`. These features can be turned on and off using the `configuration` field
160of `opts`.
161
162```js
163var 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
175Should 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
194Should 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
213Should 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
232Should 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
251Should 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
270Should 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
289Should arrays be combined when provided by both command line arguments and
290a configuration file.
291
292### duplicate arguments array
293
294* default: `true`
295* key: `duplicate-arguments-array`
296
297Should 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
316Should 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
335Should 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
356Should nargs consume dash options as well as positional arguments.
357
358### negation prefix
359
360* default: `no-`
361* key: `negation-prefix`
362
363The 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
382Should 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
403Should 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
424Should 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
445Should 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
466Should 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
488Should unknown options be treated like regular arguments?  An unknown option is one that is not
489configured 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
507Libraries in this ecosystem make a best effort to track
508[Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a
509post 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
513The yargs project evolves from optimist and minimist. It owes its
514existence to a lot of James Halliday's hard work. Thanks [substack](https://github.com/substack) **beep** **boop** \o/
515
516## License
517
518ISC
519