{"id":16882755,"url":"https://github.com/alhadis/getoptions","last_synced_at":"2025-04-11T11:51:36.212Z","repository":{"id":57250334,"uuid":"47337486","full_name":"Alhadis/GetOptions","owner":"Alhadis","description":"JavaScript's answer to getopts. Simple, obvious, and direct.","archived":false,"fork":false,"pushed_at":"2019-06-24T05:52:44.000Z","size":85,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T18:03:37.354Z","etag":null,"topics":["args","argv","cli-args","cli-parser","getopts","option-extraction","options"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/get-options","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/Alhadis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-03T14:32:31.000Z","updated_at":"2021-12-08T16:41:30.000Z","dependencies_parsed_at":"2022-08-24T16:51:58.521Z","dependency_job_id":null,"html_url":"https://github.com/Alhadis/GetOptions","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alhadis%2FGetOptions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alhadis%2FGetOptions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alhadis%2FGetOptions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alhadis%2FGetOptions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alhadis","download_url":"https://codeload.github.com/Alhadis/GetOptions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248390414,"owners_count":21095791,"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":["args","argv","cli-args","cli-parser","getopts","option-extraction","options"],"created_at":"2024-10-13T16:08:36.686Z","updated_at":"2025-04-11T11:51:36.185Z","avatar_url":"https://github.com/Alhadis.png","language":"JavaScript","readme":"GetOptions\n==========\n\n[![Build status: TravisCI](https://travis-ci.org/Alhadis/GetOptions.svg?branch=master)](https://travis-ci.org/Alhadis/GetOptions)\n[![Build status: AppVeyor](https://ci.appveyor.com/api/projects/status/kcobm8bf144ja7oa?svg=true)](https://ci.appveyor.com/project/Alhadis/getoptions)\n\n\nThe JavaScript equivalent of `getopts`. No frills, no bullshit; nothing but cold, hard option extraction.\n\n**Use this module if you**\n* Are happy validating and type-checking input yourself\n* Don't mind writing your own documentation\n* Prefer a hands-on approach without pointless array-fiddling\n\n\nThis lets you extract options so this...\n\n\u003cpre\u003e\u003ccode\u003e$ program \u003cb\u003e--log-path \u003cins\u003e/var/log/stuff.txt\u003c/ins\u003e\u003c/b\u003e generate all-files \u003cb\u003e\u003cins\u003e--verbose\u003c/ins\u003e\u003c/b\u003e\u003c/code\u003e\u003c/pre\u003e\n\n\n... gets filtered down to this:\n\n\u003cpre\u003e\u003ccode\u003e$ program generate all-files\u003c/code\u003e\u003c/pre\u003e\n\n\n... with everything neatly sorted into one little object:\n```js\nlet result = {\n    options: {\n        logPath: \"/var/log/stuff.txt\",\n        verbose: true\n    },\n    argv: [\n        \"generate\",\n        \"all-files\"\n    ]\n};\n```\n\nThat's seriously all.\n\n\nExample\n-------\n\n```js\ngetOpts(process.argv, {\n    \"-v, --verbose\":    \"\",\n    \"-l, --log-level\":  \"[level]\",\n    \"-p, --log-path\":   \"\u003cpath\u003e\",\n    \"-s, --set-config\": \"\u003cname\u003e \u003cvalue\u003e\",\n    \"-f, --files\":      \"\u003csearch-path\u003e \u003cvariadic-file-list...\u003e\"\n});\n```\n\n**Left column:**  \nShort and long forms of each defined option, separated by commas.\n\n**Right column:**  \nArguments each option takes, if any.\n\nNote: There's no requirement to enclose each parameter's name with `\u003c \u003e [ ] ( )`. These characters are just permitted for readability, and are ignored by the function when it runs. They're allowed because some authors might find them easier on the eyes than simple space-separation.\n\n**When omitted:**  \nIf you don't define any options, the function takes a \"best guess\" approach by absorbing anything with a dash in front of it. Specifically, the following assumptions are made:\n\n* Anything beginning with at least one dash is an option name\n* Options without arguments mean a boolean `true`\n* Option-reading stops at `--`\n* Anything caught between two options becomes the first option's value\n\nDon't rely on this approach to give you foolproof results. Read about the caveats [here](docs/anonymous-options.md).\n\n\nResult\n------\n\nThe value that's assigned to each corresponding `.options` property is either:  \n* **Boolean `true`** if the option doesn't take any parameters (e.g., `\"--verbose\": \"\"`)\n* **A string** holding the value of the option's only argument (e.g., `\"--log-path\": \"path\"`)\n* **An array** if more than one parameter was specified. (e.g., `\"-s, --set-config\": \"name value\"`)\n\nGiven the earlier example, the following line...\n\n\u003cpre\u003e\u003ccode\u003eprogram \u003cb\u003e--files \u003cins\u003e/search/path\u003c/ins\u003e \u003cins\u003e1.jpg\u003c/ins\u003e \u003cins\u003e2.txt\u003c/ins\u003e \u003cins\u003e3.gif\u003c/ins\u003e\u003c/b\u003e \u003cb\u003e--log-path \u003cins\u003e/path/to/\u003c/ins\u003e\u003c/b\u003e subcommand param \u003cb\u003e--verbose\u003c/b\u003e\u003c/code\u003e\u003c/pre\u003e\n\n... would yield:\n```js\nlet result = {\n    argv:    [\"subcommand\", \"param\"],\n    options: {\n        files:   [\"/search/path\", \"1.jpg\", \"2.txt\", \"3.gif\"],\n        logPath: \"/path/to\",\n        verbose: true\n    }\n};\n```\n\nI'm sure you get it by now.\n\n\t\n\nThat's it?\n----------\n\nYeah, that's it. You want fancy subcommands? Just leverage the `.argv` property of the returned object:\n```js\nlet subcommands = {\n    generate: function(whichFiles){\n        console.log(\"Let's generate... \" + whichFiles);\n    }\n};\n\nsubcommands[ result.argv[0] ].apply(null, result.argv.slice(1));\n/** -\u003e Outputs \"Let's generate... all-files\" */\n```\n\nThis would work too, if you're an `eval` kinda guy:\n```js\nfunction generate(whichFiles){ /* ... */ }\n\neval(result.argv[0]).apply(null, result.argv.slice(1));\n```\nObviously you'd be checking if the function existed and all that jazz. But that's up to you.\n\n\nFurther reading\n---------------\n\nI've broken the more convoluted documentation into different files, in an effort to keep this readme file terse:\n\n* **[Advanced settings](docs/advanced-settings.md):** Covers additional features not detailed here\n* **[Anonymous options](docs/anonymous-options.md):** What happens if you don't define any options\n* **[Bundling](docs/bundling.md):** Describes how `getOpts` parses bundled short-options like `-cyfaws`\n\n\n\nReminders\n---------\n* No typecasting is performed on user input. Values will *always* be stored as strings.\u003cbr/\u003e\u003cbr/\u003e\n* This is pure JavaScript, so it's not reliant on Node to work. Feel free to use it in a browser environment or whatever.\u003cbr/\u003e\u003cbr/\u003e\n* The array that's passed to the function isn't modified. If you want to overwrite the values stored in `process.argv`, do so by assignment:\n  \u003cpre\u003e\u003ccode\u003eprocess.argv = result.argv;\u003c/code\u003e\u003c/pre\u003e\n  This is by design. It's not reasonable to assume developers will expect the contents of the array to be automatically shifted as options are being plucked from it.\u003cbr/\u003e\u003cbr/\u003e\n* As you'd expect, the first two values in `process.argv` contain the paths of the Node executable and the currently-running script.\n  These have been omitted from the examples documented here (perhaps misleadingly, but done so for brevity's sake).\n  In production, you'd probably want to pass `process.argv.slice(2)` to `getOpts` or something.\n\n\n\n\nWhy?\n----\n\nYeah, there's billions of CLI-handling modules on NPM. Among the most well-known and popular are [Commander.JS](https://github.com/tj/commander.js) and [yargs](https://www.npmjs.com/package/yargs). Since I'm a control freak, though, I prefer doing things my way. So I developed a solution that'd permit more idiosyncratic approaches than those offered by \"mainstream\" option modules.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falhadis%2Fgetoptions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falhadis%2Fgetoptions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falhadis%2Fgetoptions/lists"}