{"id":13447917,"url":"https://github.com/yargs/yargs-parser","last_synced_at":"2025-05-13T16:06:32.431Z","repository":{"id":38360664,"uuid":"50258379","full_name":"yargs/yargs-parser","owner":"yargs","description":":muscle: the mighty option parser used by yargs","archived":false,"fork":false,"pushed_at":"2025-01-14T18:11:50.000Z","size":861,"stargazers_count":509,"open_issues_count":63,"forks_count":120,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-09T23:05:22.540Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://yargs.js.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yargs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-23T21:03:32.000Z","updated_at":"2025-05-07T01:52:19.000Z","dependencies_parsed_at":"2024-05-01T11:33:20.795Z","dependency_job_id":"ce3d6477-9bcf-4f1f-91f0-454f00221f83","html_url":"https://github.com/yargs/yargs-parser","commit_stats":{"total_commits":347,"total_committers":59,"mean_commits":5.88135593220339,"dds":0.792507204610951,"last_synced_commit":"3aba24ceaa1a06ceb982c63a06002526d781e826"},"previous_names":[],"tags_count":94,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yargs%2Fyargs-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yargs%2Fyargs-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yargs%2Fyargs-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yargs%2Fyargs-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yargs","download_url":"https://codeload.github.com/yargs/yargs-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253497296,"owners_count":21917683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T05:01:30.302Z","updated_at":"2025-05-13T16:06:32.363Z","avatar_url":"https://github.com/yargs.png","language":"JavaScript","readme":"# yargs-parser\n\n![ci](https://github.com/yargs/yargs-parser/workflows/ci/badge.svg)\n[![NPM version](https://img.shields.io/npm/v/yargs-parser.svg)](https://www.npmjs.com/package/yargs-parser)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n![nycrc config on GitHub](https://img.shields.io/nycrc/yargs/yargs-parser)\n\nThe mighty option parser used by [yargs](https://github.com/yargs/yargs).\n\nvisit the [yargs website](http://yargs.js.org/) for more examples, and thorough usage instructions.\n\n\u003cimg width=\"250\" src=\"https://raw.githubusercontent.com/yargs/yargs-parser/main/yargs-logo.png\"\u003e\n\n## Example\n\n```sh\nnpm i yargs-parser --save\n```\n\n```js\nconst argv = require('yargs-parser')(process.argv.slice(2))\nconsole.log(argv)\n```\n\n```console\n$ node example.js --foo=33 --bar hello\n{ _: [], foo: 33, bar: 'hello' }\n```\n\n_or parse a string!_\n\n```js\nconst argv = require('yargs-parser')('--foo=99 --bar=33')\nconsole.log(argv)\n```\n\n```console\n{ _: [], foo: 99, bar: 33 }\n```\n\nConvert an array of mixed types before passing to `yargs-parser`:\n\n```js\nconst parse = require('yargs-parser')\nparse(['-f', 11, '--zoom', 55].join(' '))   // \u003c-- array to string\nparse(['-f', 11, '--zoom', 55].map(String)) // \u003c-- array of strings\n```\n\n## Deno Example\n\nAs of `v19` `yargs-parser` supports [Deno](https://github.com/denoland/deno):\n\n```typescript\nimport parser from \"https://deno.land/x/yargs_parser/deno.ts\";\n\nconst argv = parser('--foo=99 --bar=9987930', {\n  string: ['bar']\n})\nconsole.log(argv)\n```\n\n## ESM Example\n\nAs of `v19` `yargs-parser` supports ESM (_both in Node.js and in the browser_):\n\n**Node.js:**\n\n```js\nimport parser from 'yargs-parser'\n\nconst argv = parser('--foo=99 --bar=9987930', {\n  string: ['bar']\n})\nconsole.log(argv)\n```\n\n**Browsers:**\n\n```html\n\u003c!doctype html\u003e\n\u003cbody\u003e\n  \u003cscript type=\"module\"\u003e\n    import parser from \"https://unpkg.com/yargs-parser@19.0.0/browser.js\";\n\n    const argv = parser('--foo=99 --bar=9987930', {\n      string: ['bar']\n    })\n    console.log(argv)\n  \u003c/script\u003e\n\u003c/body\u003e\n```\n\n## API\n\n### parser(args, opts={})\n\nParses command line arguments returning a simple mapping of keys and values.\n\n**expects:**\n\n* `args`: a string or array of strings representing the options to parse.\n* `opts`: provide a set of hints indicating how `args` should be parsed:\n  * `opts.alias`: an object representing the set of aliases for a key: `{alias: {foo: ['f']}}`.\n  * `opts.array`: indicate that keys should be parsed as an array: `{array: ['foo', 'bar']}`.\u003cbr\u003e\n    Indicate that keys should be parsed as an array and coerced to booleans / numbers:\u003cbr\u003e\n    `{array: [{ key: 'foo', boolean: true }, {key: 'bar', number: true}]}`.\n  * `opts.boolean`: arguments should be parsed as booleans: `{boolean: ['x', 'y']}`.\n  * `opts.coerce`: provide a custom synchronous function that returns a coerced value from the argument provided\n    (or throws an error). For arrays the function is called only once for the entire array:\u003cbr\u003e\n    `{coerce: {foo: function (arg) {return modifiedArg}}}`.\n  * `opts.config`: indicate a key that represents a path to a configuration file (this file will be loaded and parsed).\n  * `opts.configObjects`: configuration objects to parse, their properties will be set as arguments:\u003cbr\u003e\n    `{configObjects: [{'x': 5, 'y': 33}, {'z': 44}]}`.\n  * `opts.configuration`: provide configuration options to the yargs-parser (see: [configuration](#configuration)).\n  * `opts.count`: indicate a key that should be used as a counter, e.g., `-vvv` = `{v: 3}`.\n  * `opts.default`: provide default values for keys: `{default: {x: 33, y: 'hello world!'}}`.\n  * `opts.envPrefix`: environment variables (`process.env`) with the prefix provided should be parsed.\n  * `opts.narg`: specify that a key requires `n` arguments: `{narg: {x: 2}}`.\n  * `opts.normalize`: `path.normalize()` will be applied to values set to this key.\n  * `opts.number`: keys should be treated as numbers.\n  * `opts.string`: keys should be treated as strings (even if they resemble a number `-x 33`).\n\n**returns:**\n\n* `obj`: an object representing the parsed value of `args`\n  * `key/value`: key value pairs for each argument and their aliases.\n  * `_`: an array representing the positional arguments.\n  * [optional] `--`:  an array with arguments after the end-of-options flag `--`.\n\n### require('yargs-parser').detailed(args, opts={})\n\nParses a command line string, returning detailed information required by the\nyargs engine.\n\n**expects:**\n\n* `args`: a string or array of strings representing options to parse.\n* `opts`: provide a set of hints indicating how `args`, inputs are identical to `require('yargs-parser')(args, opts={})`.\n\n**returns:**\n\n* `argv`: an object representing the parsed value of `args`\n  * `key/value`: key value pairs for each argument and their aliases.\n  * `_`: an array representing the positional arguments.\n  * [optional] `--`:  an array with arguments after the end-of-options flag `--`.\n* `error`: populated with an error object if an exception occurred during parsing.\n* `aliases`: the inferred list of aliases built by combining lists in `opts.alias`.\n* `newAliases`: any new aliases added via camel-case expansion:\n  * `boolean`: `{ fooBar: true }`\n* `defaulted`: any new argument created by `opts.default`, no aliases included.\n  * `boolean`: `{ foo: true }`\n* `configuration`: given by default settings and `opts.configuration`.\n\n\u003ca name=\"configuration\"\u003e\u003c/a\u003e\n\n### Configuration\n\nThe yargs-parser applies several automated transformations on the keys provided\nin `args`. These features can be turned on and off using the `configuration` field\nof `opts`.\n\n```js\nvar parsed = parser(['--no-dice'], {\n  configuration: {\n    'boolean-negation': false\n  }\n})\n```\n\n### short option groups\n\n* default: `true`.\n* key: `short-option-groups`.\n\nShould a group of short-options be treated as boolean flags?\n\n```console\n$ node example.js -abc\n{ _: [], a: true, b: true, c: true }\n```\n\n_if disabled:_\n\n```console\n$ node example.js -abc\n{ _: [], abc: true }\n```\n\n### camel-case expansion\n\n* default: `true`.\n* key: `camel-case-expansion`.\n\nShould hyphenated arguments be expanded into camel-case aliases?\n\n```console\n$ node example.js --foo-bar\n{ _: [], 'foo-bar': true, fooBar: true }\n```\n\n_if disabled:_\n\n```console\n$ node example.js --foo-bar\n{ _: [], 'foo-bar': true }\n```\n\n### dot-notation\n\n* default: `true`\n* key: `dot-notation`\n\nShould keys that contain `.` be treated as objects?\n\n```console\n$ node example.js --foo.bar\n{ _: [], foo: { bar: true } }\n```\n\n_if disabled:_\n\n```console\n$ node example.js --foo.bar\n{ _: [], \"foo.bar\": true }\n```\n\n### parse numbers\n\n* default: `true`\n* key: `parse-numbers`\n\nShould keys that look like numbers be treated as such?\n\n```console\n$ node example.js --foo=99.3\n{ _: [], foo: 99.3 }\n```\n\n_if disabled:_\n\n```console\n$ node example.js --foo=99.3\n{ _: [], foo: \"99.3\" }\n```\n\n### parse positional numbers\n\n* default: `true`\n* key: `parse-positional-numbers`\n\nShould positional keys that look like numbers be treated as such.\n\n```console\n$ node example.js 99.3\n{ _: [99.3] }\n```\n\n_if disabled:_\n\n```console\n$ node example.js 99.3\n{ _: ['99.3'] }\n```\n\n### boolean negation\n\n* default: `true`\n* key: `boolean-negation`\n\nShould variables prefixed with `--no` be treated as negations?\n\n```console\n$ node example.js --no-foo\n{ _: [], foo: false }\n```\n\n_if disabled:_\n\n```console\n$ node example.js --no-foo\n{ _: [], \"no-foo\": true }\n```\n\n### combine arrays\n\n* default: `false`\n* key: `combine-arrays`\n\nShould arrays be combined when provided by both command line arguments and\na configuration file.\n\n### duplicate arguments array\n\n* default: `true`\n* key: `duplicate-arguments-array`\n\nShould arguments be coerced into an array when duplicated:\n\n```console\n$ node example.js -x 1 -x 2\n{ _: [], x: [1, 2] }\n```\n\n_if disabled:_\n\n```console\n$ node example.js -x 1 -x 2\n{ _: [], x: 2 }\n```\n\n### flatten duplicate arrays\n\n* default: `true`\n* key: `flatten-duplicate-arrays`\n\nShould array arguments be coerced into a single array when duplicated:\n\n```console\n$ node example.js -x 1 2 -x 3 4\n{ _: [], x: [1, 2, 3, 4] }\n```\n\n_if disabled:_\n\n```console\n$ node example.js -x 1 2 -x 3 4\n{ _: [], x: [[1, 2], [3, 4]] }\n```\n\n### greedy arrays\n\n* default: `true`\n* key: `greedy-arrays`\n\nShould arrays consume more than one positional argument following their flag.\n\n```console\n$ node example --arr 1 2\n{ _: [], arr: [1, 2] }\n```\n\n_if disabled:_\n\n```console\n$ node example --arr 1 2\n{ _: [2], arr: [1] }\n```\n\n**Note: in `v18.0.0` we are considering defaulting greedy arrays to `false`.**\n\n### nargs eats options\n\n* default: `false`\n* key: `nargs-eats-options`\n\nShould nargs consume dash options as well as positional arguments.\n\n### negation prefix\n\n* default: `no-`\n* key: `negation-prefix`\n\nThe prefix to use for negated boolean variables.\n\n```console\n$ node example.js --no-foo\n{ _: [], foo: false }\n```\n\n_if set to `quux`:_\n\n```console\n$ node example.js --quuxfoo\n{ _: [], foo: false }\n```\n\n### populate --\n\n* default: `false`.\n* key: `populate--`\n\nShould unparsed flags be stored in `--` or `_`.\n\n_If disabled:_\n\n```console\n$ node example.js a -b -- x y\n{ _: [ 'a', 'x', 'y' ], b: true }\n```\n\n_If enabled:_\n\n```console\n$ node example.js a -b -- x y\n{ _: [ 'a' ], '--': [ 'x', 'y' ], b: true }\n```\n\n### set placeholder key\n\n* default: `false`.\n* key: `set-placeholder-key`.\n\nShould a placeholder be added for keys not set via the corresponding CLI argument?\n\n_If disabled:_\n\n```console\n$ node example.js -a 1 -c 2\n{ _: [], a: 1, c: 2 }\n```\n\n_If enabled:_\n\n```console\n$ node example.js -a 1 -c 2\n{ _: [], a: 1, b: undefined, c: 2 }\n```\n\n### halt at non-option\n\n* default: `false`.\n* key: `halt-at-non-option`.\n\nShould parsing stop at the first positional argument? This is similar to how e.g. `ssh` parses its command line.\n\n_If disabled:_\n\n```console\n$ node example.js -a run b -x y\n{ _: [ 'b' ], a: 'run', x: 'y' }\n```\n\n_If enabled:_\n\n```console\n$ node example.js -a run b -x y\n{ _: [ 'b', '-x', 'y' ], a: 'run' }\n```\n\n### strip aliased\n\n* default: `false`\n* key: `strip-aliased`\n\nShould aliases be removed before returning results?\n\n_If disabled:_\n\n```console\n$ node example.js --test-field 1\n{ _: [], 'test-field': 1, testField: 1, 'test-alias': 1, testAlias: 1 }\n```\n\n_If enabled:_\n\n```console\n$ node example.js --test-field 1\n{ _: [], 'test-field': 1, testField: 1 }\n```\n\n### strip dashed\n\n* default: `false`\n* key: `strip-dashed`\n\nShould dashed keys be removed before returning results?  This option has no effect if\n`camel-case-expansion` is disabled.\n\n_If disabled:_\n\n```console\n$ node example.js --test-field 1\n{ _: [], 'test-field': 1, testField: 1 }\n```\n\n_If enabled:_\n\n```console\n$ node example.js --test-field 1\n{ _: [], testField: 1 }\n```\n\n### unknown options as args\n\n* default: `false`\n* key: `unknown-options-as-args`\n\nShould unknown options be treated like regular arguments?  An unknown option is one that is not\nconfigured in `opts`.\n\n_If disabled_\n\n```console\n$ node example.js --unknown-option --known-option 2 --string-option --unknown-option2\n{ _: [], unknownOption: true, knownOption: 2, stringOption: '', unknownOption2: true }\n```\n\n_If enabled_\n\n```console\n$ node example.js --unknown-option --known-option 2 --string-option --unknown-option2\n{ _: ['--unknown-option'], knownOption: 2, stringOption: '--unknown-option2' }\n```\n\n## Supported Node.js Versions\n\nLibraries in this ecosystem make a best effort to track\n[Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a\npost on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).\n\n## Special Thanks\n\nThe yargs project evolves from optimist and minimist. It owes its\nexistence to a lot of James Halliday's hard work. Thanks [substack](https://github.com/substack) **beep** **boop** \\o/\n\n## License\n\nISC\n","funding_links":[],"categories":["JavaScript","Repository","命令行","others"],"sub_categories":["Command-line Utilities","redux 扩展","macros"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyargs%2Fyargs-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyargs%2Fyargs-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyargs%2Fyargs-parser/lists"}