{"id":28844135,"url":"https://github.com/yord/shargs","last_synced_at":"2025-10-11T02:38:47.907Z","repository":{"id":57358094,"uuid":"233786847","full_name":"Yord/shargs","owner":"Yord","description":"šŸ¦ˆ shargs is a combinator library for building command-line argument parsers.","archived":false,"fork":false,"pushed_at":"2021-01-31T21:22:22.000Z","size":3875,"stargazers_count":86,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-19T17:08:01.733Z","etag":null,"topics":["command-line","parser","shargs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yord.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-14T07:53:31.000Z","updated_at":"2022-10-26T04:40:01.000Z","dependencies_parsed_at":"2022-09-26T16:40:48.435Z","dependency_job_id":null,"html_url":"https://github.com/Yord/shargs","commit_stats":null,"previous_names":["yord/pxi-args"],"tags_count":187,"template":false,"template_full_name":null,"purl":"pkg:github/Yord/shargs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yord%2Fshargs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yord%2Fshargs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yord%2Fshargs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yord%2Fshargs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yord","download_url":"https://codeload.github.com/Yord/shargs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yord%2Fshargs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260793384,"owners_count":23064033,"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":["command-line","parser","shargs"],"created_at":"2025-06-19T17:07:54.287Z","updated_at":"2025-10-11T02:38:47.877Z","avatar_url":"https://github.com/Yord.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg width=\"800\" src=\"shargs.png\" /\u003e\n\u003c/p\u003e\n\nšŸ¦ˆ shargs (**sh**ell **args**) is a library for building command-line argument parsers.\n\n[![node version][shield-node]][node]\n[![npm version][shield-npm]][npm-package]\n[![license][shield-license]][license]\n[![PRs Welcome][shield-prs]][contribute]\n[![linux unit tests status][shield-unit-tests-linux]][actions]\n[![macos unit tests status][shield-unit-tests-macos]][actions]\n[![windows unit tests status][shield-unit-tests-windows]][actions]\n\n## Features\n\n+ Compose functions to build [highly customizable](#command-line-parsers) command-line argument [parsers](#the-parsersync-function).\n+ 35+ opt-in features, e.g. ([multiple](#multiple-subcommands)) [subcommands](#subcommand),\n [spelling mistake detection](#suggestOpts), [default values](#setDefaultValues),\n and ([best guess](#bestGuessCast)) [casting](#cast).\n+ [Synchronous](#the-parsersync-function) and Promise-based [asynchronous](#async-parsers) modes\n with async/await support.\n+ [Automatic usage documentation generation](#automatic-usage-documentation-generation) with fine-grained control over \n [layouts](#automatic-usage-documentation-generation) and [styles](#style).\n+ Easily extensible with your own [custom parser stages](#custom-checks-and-stages)\n and [custom usage layouts](#custom-usage-functions).\n+ [Extensively documented](#documentation) and very well tested (800+ unit and integration tests).\n+ [Modular library layout](#installation) with zero runtime dependencies.\n\n## Installation\n\nInstall as a bundle (recommended):\n\n\u003cpre\u003e\nnpm install --save \u003ca href=\"https://github.com/Yord/shargs\"\u003eshargs\u003c/a\u003e\n\u003c/pre\u003e\n\nInstall as modules:\n\n\u003cpre\u003e\nnpm install --save \u003ca href=\"https://github.com/Yord/shargs-core\"\u003eshargs-core\u003c/a\u003e # core functions like \u003ca href=\"#the-parsersync-function\"\u003eparserSync\u003c/a\u003e (in bundle: shargs/core or shargs)\nnpm install --save \u003ca href=\"https://github.com/Yord/shargs-opts\"\u003eshargs-opts\u003c/a\u003e # a DSL for \u003ca href=\"#command-line-options\"\u003ecommand-line options\u003c/a\u003e (in bundle: shargs/opts)\nnpm install --save \u003ca href=\"https://github.com/Yord/shargs-parser\"\u003eshargs-parser\u003c/a\u003e # collection of \u003ca href=\"#command-line-parsers\"\u003eparser functions\u003c/a\u003e (in bundle: shargs/parser)\nnpm install --save \u003ca href=\"https://github.com/Yord/shargs-usage\"\u003eshargs-usage\u003c/a\u003e # collection of \u003ca href=\"#automatic-usage-documentation-generation\"\u003eusage functions\u003c/a\u003e (in bundle: shargs/usage)\nnpm install --save \u003ca href=\"https://github.com/Yord/shargs-repl\"\u003eshargs-repl\u003c/a\u003e # \u003ca href=\"#building-repls-with-shargs\"\u003ebuild REPLs\u003c/a\u003e powered by shargs (not in bundle)\n\u003c/pre\u003e\n\nThe documentation assumes the bundle is installed,\nbut the only difference between the bundle and modules installation is how functions are imported:\nThe bundle uses `require('shargs/opts')`, while `require('shargs-opts')` is used by modules\n(note the use of `/` vs. `-`).\nRead [installing as bundle or modules](#installing-as-bundle-or-modules) for more details.\n\n## Getting Started\n\n\u003cdetails\u003e\n\u003csummary\u003e\nDescribe your command and its options:\n\n\u003cp\u003e\n\n```js\nconst opts = [\n stringPos('question', {desc: 'Ask a question.', required: true}),\n number('answer', ['-a', '--answer'], {desc: 'The answer.', defaultValues: [42]}),\n flag('help', ['-h', '--help'], {desc: 'Print this help message and exit.'})\n]\n\nconst deepThought = command('deepThought', opts, {desc: 'Ask the Ultimate Question.'})\n```\n\n\u003c/p\u003e\n\u003c/summary\u003e\n\nThe `deepThought` command has three command-line options:\n\n1. A `required` string positional argument named `question`.\n2. An `answer` number option specified with `-a` or `--answer` that should default to `42` if not given.\n3. A `help` command-line flag given by `-h` or `--help`.\n\nYou may use the `shargs-opts` module to get a nice DSL for describing our options.\nHowever, you could have also written them out as objects yourself or could have used a different DSL.\n\nRead up on the details in the [command-line options](#command-line-options) section.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nDeclare your own command-line parser:\n\n\u003cp\u003e\n\n```js\nconst parser = parserSync({\n argv: [splitShortOpts],\n opts: [setDefaultValues, requireOpts, cast],\n args: [flagsAsBools]\n})\n```\n\n\u003c/p\u003e\n\u003c/summary\u003e\n\nShargs gives you fine-grained control over how the options are parsed.\nBy using the `shargs-core` and `shargs-parser` modules, we have build the following `parser`:\n\n1. `splitShortOpts`: Short option groups like `-cvzf` are transformed to `-c -v -z -f`.\n2. `setDefaultValues`: Options with default values that were not provided are set.\n3. `requireOpts`: It is verified that all required options have been given.\n4. `cast`: Strings are cast to other types, like numbers or booleans.\n5. `flagsAsBools`: Command-line flags are transformed to booleans.\n\nNote that you did not tell `parser` how exactly to do those things.\nEverything is nice and declarative, and the details are hidden away in the parser stages.\n\nThe [parserSync function](#the-parserSync-function)\nand [command-line parsers](#command-line-parsers) sections have all the details.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nLayout a usage documentation:\n\n\u003cp\u003e\n\n```js\nconst docs = usage([synopsis, space, optsList, space, desc])\n\nconst style = {\n line: [{width: 80}],\n cols: [{width: 25}, {width: 55}]\n}\n```\n\n\u003c/p\u003e\n\u003c/summary\u003e\n\nYou may use `shargs-usage` to automatically generate a usage documentation based on a command definition\n(e.g. `deepThought` from before).\nThe module provides all components generally found in usage documentations, like:\n\n1. A `synopsis`, summarizing available options: e.g. `deepThought (\u003cquestion\u003e) [-a|--answer] [-h|--help]`.\n2. An options list (`optsList`), describing option details in a tabular format.\n\nNote that `shargs-usage` is declarative:\nYou only specify what components our usage documentation should have.\nThe details on how exactly those components transform command-line options into text is hidden away.\n\nSee the [automatic usage documentation generation](#automatic-usage-documentation-generation)\nand [style](#style) sections.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nUse the parser and the usage documentation in your program:\n\n\u003cp\u003e\n\n```js\nconst argv = process.argv.slice(2)\nconst {errs, args} = parser(deepThought)(argv)\n\nerrs.forEach(err =\u003e console.log(err.msg))\n\nconst help = docs(deepThought)(style)\nif (args.help) console.log(help)\n```\n\n\u003c/p\u003e\n\u003c/summary\u003e\n\nThe command-line option DSL, the parser DSL, and the usage documentation DSL combined\ngive you a very flexible way to write command-line programs.\n\nFind out more in the [building command-line parsers with shargs](#building-command-line-parsers-with-shargs) section.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nRun your command with \u003ccode\u003enode ./deepThought --help\u003c/code\u003e:\n\n\u003cp\u003e\n\n```bash\ndeepThought (\u003cquestion\u003e) [-a|--answer] [-h|--help] \n \n\u003cquestion\u003e Ask a question. [required] \n-a, --answer=\u003cnumber\u003e The answer. [default: 42] \n-h, --help Print this help message and exit. \n \nAsk the Ultimate Question. \n```\n\n\u003c/p\u003e\n\u003c/summary\u003e\n\nThe [automatic usage documentation generation](#automatic-usage-documentation-generation)\nand [building command-line parsers with shargs](#building-command-line-parsers-with-shargs) sections have more.\n\n\u003c/details\u003e\n\n### Tutorials\n\n+ [Beginners: Implementing a `git`-like interface.][shargs-tutorial-git]\n\n### Examples\n\n+ [An asynchronous version of deepThought.][shargs-example-async-deepthought]\n+ [A synchronous version of deepThought.][shargs-example-sync-deepthought]\n+ [deepThought with three layers of configuration: A config file, environment variables, and command-line arguments.][shargs-example-sync-deepthought-config-env-argv]\n+ [A command-line arguments SQL parser.][shargs-example-sync-sql]\n+ [A REPL (Real Eval Print Loop) build with `shargs-repl`.][shargs-example-repl]\n\n## Documentation\n\nThis documentation encompasses the following shargs modules:\n\n1. [`shargs-opts`][shargs-opts] is documented in [command-line options](#command-line-options).\n2. [`shargs-core`][shargs-core] is documented in [the `parserSync` function](#the-parserSync-function).\n3. [`shargs-parser`][shargs-parser] is documented in [command-line parsers](#command-line-parsers).\n4. [`shargs-usage`][shargs-usage] is documented in [automatic usage documentation generation](#automatic-usage-documentation-generation).\n5. [`shargs-repl`][shargs-repl] is documented in [building REPLs with shargs](#building-repls-with-shargs).\n\n### Command-line Options\n\nCommand-line options are the most important concept in shargs.\nThey are the basis for its two main features:\n[Command-line parsers](#command-line-parsers)\nand [automatic usage documentation generation](#automatic-usage-documentation-generation).\n\nShargs defines many different types of command-line options represented by objects with the following interfaces:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Type\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Interface\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"flag-option\"\u003e\n\u003ctd\u003e\u003ca href=\"#flag-option\"\u003eFlag Option\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#args\"\u003eargs\u003c/a\u003e, \u003ca href=\"#types\"\u003etypes\u003c/a\u003e: []}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eA present or absent value.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"primitive-option\"\u003e\n\u003ctd\u003e\u003ca href=\"#primitive-option\"\u003ePrimitive Option\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#args\"\u003eargs\u003c/a\u003e, \u003ca href=\"#types\"\u003etypes\u003c/a\u003e: [_]}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eA unary value given by argument.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"array-option\"\u003e\n\u003ctd\u003e\u003ca href=\"#array-option\"\u003eArray Option\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#args\"\u003eargs\u003c/a\u003e, \u003ca href=\"#types\"\u003etypes\u003c/a\u003e: [_, _, ...]}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eAn array of length n given by argument.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"variadic-option\"\u003e\n\u003ctd\u003e\u003ca href=\"#variadic-option\"\u003eVariadic Option\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#args\"\u003eargs\u003c/a\u003e}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eA variable length array given by argument.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"subcommand-option\"\u003e\n\u003ctd\u003e\u003ca href=\"#subcommand-option\"\u003eSubcommand Option\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#args\"\u003eargs\u003c/a\u003e, \u003ca href=\"#opts\"\u003eopts\u003c/a\u003e}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eAn option group given by argument.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"primitive-pos-arg\"\u003e\n\u003ctd\u003e\u003ca href=\"#primitive-pos-arg\"\u003ePrimitive Positional Argument\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#types\"\u003etypes\u003c/a\u003e: [_]}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eA unary value given by position.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"array-pos-arg\"\u003e\n\u003ctd\u003e\u003ca href=\"#array-pos-arg\"\u003eArray Positional Argument\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#types\"\u003etypes\u003c/a\u003e: [_, _, ...]}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eAn array of length n given by position.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"variadic-pos-arg\"\u003e\n\u003ctd\u003e\u003ca href=\"#variadic-pos-arg\"\u003eVariadic Positional Argument\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eA variable length array given by position.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"command-pos-arg\"\u003e\n\u003ctd\u003e\u003ca href=\"#command-pos-arg\"\u003eCommand Positional Argument\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#key\"\u003ekey\u003c/a\u003e, \u003ca href=\"#opts\"\u003eopts\u003c/a\u003e}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eAn option group given by position.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"rest\"\u003e\n\u003ctd\u003e\u003ca href=\"#rest\"\u003eRest\u003c/a\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e{\u003ca href=\"#values\"\u003evalues\u003c/a\u003e}\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eAn argument value of unknown type.\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nSince writing objects following these interfaces by hand can be tedious,\n[`shargs-opts`][shargs-opts] gives you a simple type-based DSL for defining valid command-line options:\n\n```js\nconst {command, flag, number, subcommand} = require('shargs/opts')\n\nconst opts = [\n subcommand(askOpts)('ask', ['ask'], {required: true, desc: 'Ask a question.'}),\n number('answer', ['-a', '--answer'], {defaultValues: [42], desc: 'The answer.'}),\n flag('help', ['-h', '--help'], {desc: 'Print this help message and exit.'})\n]\n\nconst deepThought = command('deepThought', opts, {\n desc: 'Deep Thought was created to come up with the Answer to ' +\n 'The Ultimate Question of Life, the Universe, and Everything.'\n})\n```\n\nIn the example, using the type functions [`subcommand`](#subcommand), [`number`](#number), [`flag`](#flag),\nand [`command`](#command) guarantees the generation of valid objects.\n\n#### Type Functions\n\nThe following type functions are available:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Type\u0026nbsp;Function\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"array\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"arrayPos\"\u003e\u003ca href=\"#array\"\u003earray\u003c/a\u003e(types)(key, args, fields)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#arrayPos\"\u003earrayPos\u003c/a\u003e(types)(key, fields)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003earray\u003c/code\u003e generates an \u003ca href=\"#array-option\"\u003earray option\u003c/a\u003e,\nwhile \u003ccode\u003earrayPos\u003c/code\u003e generates an \u003ca href=\"#array-pos-arg\"\u003earray positional argument\u003c/a\u003e,\nrepresenting arrays whose length is known in advance.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThe closely related \u003ccode\u003e\u003ca href=\"#variadic\"\u003evariadic\u003c/a\u003e\u003c/code\u003e\nand \u003ccode\u003e\u003ca href=\"#variadicPos\"\u003evariadicPos\u003c/a\u003e\u003c/code\u003e represent arrays with unknown lengths.\n\n\u003cbr /\u003e\n\n`array` returns the following object:\n\n```js\nconst array = types =\u003e (key, args, fields) =\u003e ({\n key, args, types, ...fields\n})\n```\n\n`arrayPos` returns the following object:\n\n```js\nconst arrayPos = types =\u003e (key, fields) =\u003e ({\n key, types, ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"bool\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"boolPos\"\u003e\u003ca href=\"#bool\"\u003ebool\u003c/a\u003e(key, args, fields)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#boolPos\"\u003eboolPos\u003c/a\u003e(key, fields)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ebool\u003c/code\u003e generates a \u003ca href=\"#primitive-option\"\u003eprimitive option\u003c/a\u003e,\nwhile \u003ccode\u003eboolPos\u003c/code\u003e generates a \u003ca href=\"#primitive-pos-arg\"\u003eprimitive positional argument\u003c/a\u003e,\nrepresenting the boolean values \u003ccode\u003e'true'\u003c/code\u003e and \u003ccode\u003e'false'\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nNote that the values are represented as strings and you may want to \u003ccode\u003e\u003ca href=\"#cast\"\u003ecast\u003c/a\u003e\u003c/code\u003e them.\nIf you need more values representing \u003ccode\u003e'true'\u003c/code\u003e (e.g. \u003ccode\u003e't'\u003c/code\u003e, \u003ccode\u003e'yes'\u003c/code\u003e)\nor \u003ccode\u003e'false'\u003c/code\u003e (e.g. \u003ccode\u003e'F'\u003c/code\u003e, \u003ccode\u003e'no'\u003c/code\u003e),\nhave a look at \u003ccode\u003e\u003ca href=\"#broadenBools\"\u003ebroadenBools\u003c/a\u003e\u003c/code\u003e.\nIf you want to treat a value as its \u003ccode\u003e\u003ca href=\"#reverse\"\u003ereverse\u003c/a\u003e\u003c/code\u003e,\nsee \u003ccode\u003e\u003ca href=\"#reverseBools\"\u003ereverseBools\u003c/a\u003e\u003c/code\u003e.\nIf you need \u003ccode\u003e\u003ca href=\"#flag\"\u003eflag\u003c/a\u003e\u003c/code\u003es instead of \u003ccode\u003ebool\u003c/code\u003es, have a look at the\n\u003ccode\u003e\u003ca href=\"#boolAsFlag\"\u003eboolAsFlag\u003c/a\u003e\u003c/code\u003e and \u003ccode\u003e\u003ca href=\"#boolsAsFlags\"\u003eboolsAsFlags\u003c/a\u003e\u003c/code\u003e \nparser stages.\n\n\u003cbr /\u003e\n\n`bool` returns the following object:\n\n```js\nconst bool = (key, args, fields) =\u003e ({\n key, args, types: ['bool'], ...fields\n})\n```\n\n`boolPos` returns the following object:\n\n```js\nconst boolPos = (key, fields) =\u003e ({\n key, types: ['bool'], ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"subcommand\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"command\"\u003e\u003ca href=\"#subcommand\"\u003esubcommand\u003c/a\u003e(opts)(key, args, fields)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#command\"\u003ecommand\u003c/a\u003e(key, opts, fields)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003esubcommand\u003c/code\u003e generates a \u003ca href=\"#subcommand-option\"\u003esubcommand option\u003c/a\u003e,\nwhile \u003ccode\u003ecommand\u003c/code\u003e generates a \u003ca href=\"#command-pos-arg\"\u003ecommand positional argument\u003c/a\u003e.\nCombined, they enable commands to do multiple things like \u003ccode\u003egit init\u003c/code\u003e, \u003ccode\u003egit commit\u003c/code\u003e, and \u003ccode\u003egit push\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n\u003ccode\u003esubcommand\u003c/code\u003e's and \u003ccode\u003ecommand\u003c/code\u003e's \u003ccode\u003e\u003ca href=\"#opts\"\u003eopts\u003c/a\u003e\u003c/code\u003e fields\nare arrays of command-line options used to parse their \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e.\nSubcommands may have their own \u003ca href=\"#substages\"\u003ecommand-specific parsers\u003c/a\u003e\nor are parsed by \u003ccode\u003ecommand\u003c/code\u003e's parser.\n\u003ccode\u003ecommand\u003c/code\u003e or \u003ccode\u003esubcommand\u003c/code\u003e values are either terminated by the end of the input\nor by \u003ccode\u003e--\u003c/code\u003e.\n\n\u003cbr /\u003e\n\n`subcommand` returns the following object:\n\n```js\nconst subcommand = opts =\u003e (key, args, fields) =\u003e ({\n key, args, opts, ...fields\n})\n```\n\n`command` returns the following object:\n\n```js\nconst command = (key, opts, fields) =\u003e ({\n key, opts, ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"flag\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#flag\"\u003eflag\u003c/a\u003e(key, args, fields)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eflag\u003c/code\u003e generates a \u003ca href=\"#flag-option\"\u003eflag option\u003c/a\u003e,\nrepresenting command-line options that take no value.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nShargs counts the number of times a \u003ccode\u003eflag\u003c/code\u003e occurs, so a \u003ccode\u003eflag\u003c/code\u003e may be amplified by repeating it.\nIf you don't need counts and prefer numbers or boolean values, have a look at the\n\u003ccode\u003e\u003ca href=\"#flagAsBool\"\u003eflagAsBool\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#flagAsNumber\"\u003eflagAsNumber\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#flagsAsBools\"\u003eflagsAsBools\u003c/a\u003e\u003c/code\u003e and \u003ccode\u003e\u003ca href=\"#flagsAsNumbers\"\u003eflagsAsNumbers\u003c/a\u003e\u003c/code\u003e \nparser stages.\nIf you need the presence of a \u003ccode\u003eflag\u003c/code\u003e to imply negativity (e.g. \u003ccode\u003e--no-fun\u003c/code\u003e),\nsee \u003ccode\u003e\u003ca href=\"#complement\"\u003ecomplement\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#reverse\"\u003ereverse\u003c/a\u003e\u003c/code\u003e and \u003ccode\u003e\u003ca href=\"#reverseFlags\"\u003ereverseFlags\u003c/a\u003e\u003c/code\u003e.\n\n\u003cbr /\u003e\n\n`flag` returns the following object:\n\n```js\nconst flag = (key, args, fields) =\u003e ({\n key, args, types: [], ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"number\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"numberPos\"\u003e\u003ca href=\"#number\"\u003enumber\u003c/a\u003e(key, args, fields)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#numberPos\"\u003enumberPos\u003c/a\u003e(key, fields)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003enumber\u003c/code\u003e generates a \u003ca href=\"#primitive-option\"\u003eprimitive option\u003c/a\u003e,\nwhile \u003ccode\u003enumberPos\u003c/code\u003e generates a \u003ca href=\"#primitive-pos-arg\"\u003eprimitive positional argument\u003c/a\u003e,\nrepresenting JavaScript numbers.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nNumbers are represented as strings and you may want to \u003ccode\u003e\u003ca href=\"#cast\"\u003ecast\u003c/a\u003e\u003c/code\u003e them.\nIf you need \u003ccode\u003e\u003ca href=\"#flag\"\u003eflag\u003c/a\u003e\u003c/code\u003es instead of \u003ccode\u003enumber\u003c/code\u003es, have a look at the\n\u003ccode\u003e\u003ca href=\"#numberAsFlag\"\u003enumberAsFlag\u003c/a\u003e\u003c/code\u003e and \u003ccode\u003e\u003ca href=\"#numbersAsFlags\"\u003enumbersAsFlags\u003c/a\u003e\u003c/code\u003e \nparser stages.\n\n\u003cbr /\u003e\n\n`number` returns the following object:\n\n```js\nconst number = (key, args, fields) =\u003e ({\n key, args, types: ['number'], ...fields\n})\n```\n\n`numberPos` returns the following object:\n\n```js\nconst numberPos = (key, fields) =\u003e ({\n key, types: ['number'], ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"string\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"stringPos\"\u003e\u003ca href=\"#string\"\u003estring\u003c/a\u003e(key, args, fields)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#stringPos\"\u003estringPos\u003c/a\u003e(key, fields)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003estring\u003c/code\u003e generates a \u003ca href=\"#primitive-option\"\u003eprimitive option\u003c/a\u003e,\nwhile \u003ccode\u003estringPos\u003c/code\u003e generates a \u003ca href=\"#primitive-pos-arg\"\u003eprimitive positional argument\u003c/a\u003e,\nrepresenting strings.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n`string` returns the following object:\n\n```js\nconst string = (key, args, fields) =\u003e ({\n key, args, types: ['string'], ...fields\n})\n```\n\n`stringPos` returns the following object:\n\n```js\nconst stringPos = (key, fields) =\u003e ({\n key, types: ['string'], ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"variadic\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"variadicPos\"\u003e\u003ca href=\"#variadic\"\u003evariadic\u003c/a\u003e(key, args, fields)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#variadicPos\"\u003evariadicPos\u003c/a\u003e(key, fields)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003evariadic\u003c/code\u003e generates a \u003ca href=\"#variadic-option\"\u003evariadic option\u003c/a\u003e,\nwhile \u003ccode\u003evariadicPos\u003c/code\u003e generates a \u003ca href=\"#variadic-pos-arg\"\u003evariadic positional argument\u003c/a\u003e.\nThese types represent arrays whose length is not known in advance.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nAn \u003ccode\u003eopts\u003c/code\u003e array can have at most one \u003ca href=\"#variadic-pos-arg\"\u003evariadic positional argument\u003c/a\u003e\nand no other positional arguments (\u003ccode\u003e*Pos\u003c/code\u003e) may be defined after it.\nThe closely related \u003ccode\u003e\u003ca href=\"#array\"\u003earray\u003c/a\u003e\u003c/code\u003e\nand \u003ccode\u003e\u003ca href=\"#arrayPos\"\u003earrayPos\u003c/a\u003e\u003c/code\u003e represent arrays with known lengths, while\n\u003ccode\u003e\u003ca href=\"#command\"\u003ecommand\u003c/a\u003e\u003c/code\u003e and \u003ccode\u003e\u003ca href=\"#subcommand\"\u003esubcommand\u003c/a\u003e\u003c/code\u003e are\n\u003ccode\u003evariadicPos\u003c/code\u003e and \u003ccode\u003evariadic\u003c/code\u003e with \u003ccode\u003e\u003ca href=\"#opts\"\u003eopts\u003c/a\u003e\u003c/code\u003e fields.\nA \u003ccode\u003evariadic\u003c/code\u003e's or \u003ccode\u003evariadicPos\u003c/code\u003e' values are either terminated by the end of the input\nor by \u003ccode\u003e--\u003c/code\u003e.\n\n\u003cbr /\u003e\n\n`variadic` returns the following object:\n\n```js\nconst variadic = (key, args, fields) =\u003e ({\n key, args, ...fields\n})\n```\n\n`variadicPos` returns the following object:\n\n```js\nconst variadicPos = (key, fields) =\u003e ({\n key, ...fields\n})\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nYou may write out command-line options by hand, or write your own DSLs for creating them, they are just JavaScript objects:\n\n```js\nconst askOpts = [\n {key: 'format', args: ['--format'], types: ['string'], only: ['json', 'xml'], defaultValues: ['json'],\n desc: 'Respond either with json or xml.'},\n {key: 'html', args: ['--no-html'], types: [], reverse: true, desc: 'Remove HTML tags.'},\n {key: 'help', args: ['-h', '--help'], types: [], desc: 'Print this help message and exit.'},\n {key: 'question', types: ['string'], required: true, desc: 'State your question.'}\n]\n```\n\nApart from [`key`](#key), [`args`](#args), [`types`](#types), [`opts`](#opts), and [`values`](#values)\nthat we have already seen and that determine an option's type,\ncommand-line option objects may be given any other \u003ccode\u003efields\u003c/code\u003e,\nthat may be used to provide information to parser stages\n(e.g. [`defaultValues`](#defaultValues), [`only`](#only)),\nor to provide descriptions for usage documentation generation\n(e.g. \u003ccode\u003e\u003ca href=\"#desc\"\u003edesc\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e).\nIf you write your own parser stages, you may also define your own fields.\n\n#### Option Fields\n\nThe following fields are used by [`shargs-core`][shargs-core], [`shargs-parser`][shargs-parser] stages\nor [`shargs-usage`][shargs-usage] functions:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eField\u003c/th\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Type\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\n\u003ctr name=\"args\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#args\"\u003eargs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003estring[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eargs\u003c/code\u003e defines argument names for command-line options (e.g. \u003ccode\u003e['-h', '--help']\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nArgument names have no restrictions and can be any string.\nE.g. \u003ccode\u003e['-h', '--help']\u003c/code\u003e could be used for a help \u003ccode\u003e\u003ca href=\"#flag\"\u003eflag\u003c/a\u003e\u003c/code\u003e\nor \u003ccode\u003e['ask']\u003c/code\u003e could be used for a \u003ccode\u003e\u003ca href=\"#command\"\u003ecommand\u003c/a\u003e\u003c/code\u003e.\nPositional arguments must not have an \u003ccode\u003eargs\u003c/code\u003e field,\nas they are not given by argument, but by their position.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"contradicts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#contradicts\"\u003econtradicts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003econtradicts\u003c/code\u003e defines what \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003es an option is incompatible with.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThis information is used by the \u003ccode\u003e\u003ca href=\"#contradictOpts\"\u003econtradictOpts\u003c/a\u003e\u003c/code\u003e parser stage\nto report errors if incompatible options are used together.\nNote that \u003ccode\u003econtradicts\u003c/code\u003e is unidirectional and not transitive\n(e.g. if \u003ccode\u003ea\u003c/code\u003e contradicts \u003ccode\u003eb\u003c/code\u003e and \u003ccode\u003eb\u003c/code\u003e contradicts \u003ccode\u003ec\u003c/code\u003e,\n\u003ccode\u003ea\u003c/code\u003e does not contradict \u003ccode\u003ec\u003c/code\u003e, and thus \u003ccode\u003ea\u003c/code\u003e and \u003ccode\u003ec\u003c/code\u003e are compatible).\nOnly two \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003es that each contradict the other \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e\nare mutually exclusive.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"defaultValues\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#defaultValues\"\u003edefaultValues\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e*\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003edefaultValues\u003c/code\u003e defines default \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e for command-line options.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThey are used by the \u003ccode\u003e\u003ca href=\"#setDefaultValues\"\u003esetDefaultValues\u003c/a\u003e\u003c/code\u003e parser stage\nthat sets the \u003ccode\u003evalues\u003c/code\u003e field if no \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e are supplied.\nThe \u003ccode\u003edefaultValues\u003c/code\u003e' type depends on the command-line option type:\n\u003ca href=\"#subcommand-option\"\u003eSubcommands\u003c/a\u003e takes the same array of options as \u003ccode\u003e\u003ca href=\"#opts\"\u003eopts\u003c/a\u003e\u003c/code\u003e.\n\u003ca href=\"#flag-option\"\u003eFlag options\u003c/a\u003e' values have to be a number.\nAll other options take an array of values,\nthat must have the same length as their \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e field.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"desc\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#desc\"\u003edesc\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003edesc\u003c/code\u003e defines an option description used by various usage functions.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nMore specifically, \u003ccode\u003edesc\u003c/code\u003e is used by\n\u003ccode\u003e\u003ca href=\"#usage-desc\"\u003edesc\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e and their \u003ccode\u003e*With\u003c/code\u003e versions.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"descArg\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003edescArg\u003c/code\u003e defines a description for an argument value\n(e.g. \u003ccode\u003e{descArg: 'format'}\u003c/code\u003e would print \u003ccode\u003e--format=\u0026lt;format\u0026gt;\u003c/code\u003e\ninstead of \u003ccode\u003e--format=\u0026lt;string\u0026gt;\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt is used by the \u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e usage functions\nand their \u003ccode\u003e*With\u003c/code\u003e versions.\n\u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e \nare other fields that change the argument value description.\nThese fields are applied in the following order (highest priority first):\n\u003ccode\u003edescArg\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e.\nIf \u003ccode\u003edescArg\u003c/code\u003e is an empty string, no argument value description is displayed.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"descDefault\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#descDefault\"\u003edescDefault\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003edescDefault\u003c/code\u003e overrides the default shield (e.g. \u003ccode\u003e[default: 42]\u003c/code\u003e) displayed in several usage commands.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt is used by the \u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e usage functions\nand their \u003ccode\u003e*With\u003c/code\u003e versions.\nIf \u003ccode\u003edescDefault\u003c/code\u003e is an empty string, the default shield is hidden.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"implies\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#implies\"\u003eimplies\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eimplies\u003c/code\u003e defines what \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003es an option must be defined with.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThis information is used by the \u003ccode\u003e\u003ca href=\"#implyOpts\"\u003eimplyOpts\u003c/a\u003e\u003c/code\u003e parser stage\nto report errors if mandatory options are missing.\nNote that \u003ccode\u003eimplies\u003c/code\u003e is unidirectional\n(e.g. if \u003ccode\u003ea\u003c/code\u003e implies \u003ccode\u003eb\u003c/code\u003e and \u003ccode\u003ea\u003c/code\u003e is present, \u003ccode\u003eb\u003c/code\u003e must be present as well,\nbut if \u003ccode\u003eb\u003c/code\u003e is present, \u003ccode\u003ea\u003c/code\u003e does not have to be present)\nand transitive\n(e.g. if \u003ccode\u003ea\u003c/code\u003e implies \u003ccode\u003eb\u003c/code\u003e and \u003ccode\u003eb\u003c/code\u003e implies \u003ccode\u003ec\u003c/code\u003e,\n\u003ccode\u003ea\u003c/code\u003e also implies \u003ccode\u003ec\u003c/code\u003e,\nand thus if \u003ccode\u003ea\u003c/code\u003e is present, \u003ccode\u003ec\u003c/code\u003e must also be present).\nOnly two \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003es that each imply the other \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e\nare mutually inclusive.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"key\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ekey\u003c/code\u003e defines the name of a command-line option.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt is used by the \u003ccode\u003e\u003ca href=\"#the-parserSync-function\"\u003eparser\u003c/a\u003e\u003c/code\u003e function\nas a field name for the parsed values in the resulting \u003ccode\u003eargs\u003c/code\u003e object.\nMost command-line options should have a unique \u003ccode\u003ekey\u003c/code\u003e to avoid collisions with other options.\nHowever, if two different options describe the same result field, it may make sense to give them a shared key.\nSee \u003ccode\u003e\u003ca href=\"#complement\"\u003ecomplement\u003c/a\u003e\u003c/code\u003e for an example.\nA \u003ccode\u003ekey\u003c/code\u003e must not be named \u003ccode\u003e_\u003c/code\u003e.\nIt is also used by the\n\u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#synopses\"\u003esynopses\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#synopsis\"\u003esynopsis\u003c/a\u003e\u003c/code\u003e usage functions\nand their \u003ccode\u003e*With\u003c/code\u003e versions to describe argument values (e.g. \u003ccode\u003e--format=\u0026lt;format\u0026gt;\u003c/code\u003e).\n\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e are other fields that change the argument value description.\nThese fields are applied in the following order (highest priority first):\n\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003ekey\u003c/code\u003e.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"only\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003eany[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eonly\u003c/code\u003e defines valid values of an option.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt is used by the \u003ccode\u003e\u003ca href=\"#restrictToOnly\"\u003erestrictToOnly\u003c/a\u003e\u003c/code\u003e parser stage to validate user input.\n\u003ccode\u003eonly\u003c/code\u003e may be used to \u003ca href=\"#can-i-use-enums\"\u003eimplement enumerations\u003c/a\u003e.\nIt is also used by the \u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e usage functions\nand their \u003ccode\u003e*With\u003c/code\u003e versions to describe argument values (e.g. \u003ccode\u003e--format=\u0026lt;json|xml\u0026gt;\u003c/code\u003e).\n\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e are other fields that change the argument value description.\nThese fields are applied in the following order (highest priority first):\n\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003eonly\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"opts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#opts\"\u003eopts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#command-line-options\"\u003eoption\u003c/a\u003e[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003ccode\u003eopts\u003c/code\u003e defines the command-line options of \u003ccode\u003e\u003ca href=\"#command\"\u003ecommand\u003c/a\u003e\u003c/code\u003es\nand \u003ccode\u003e\u003ca href=\"#subcommand\"\u003esubcommand\u003c/a\u003e\u003c/code\u003es.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"required\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#required\"\u003erequired\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003eboolean\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003erequired\u003c/code\u003e defines whether a command-line option has to be present or not.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt is used by the \u003ccode\u003e\u003ca href=\"#requireOpts\"\u003erequireOpts\u003c/a\u003e\u003c/code\u003e stage that reports an error\nif a \u003ccode\u003erequired\u003c/code\u003e option does not have \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e.\nA positional argument (\u003ccode\u003e*Pos\u003c/code\u003e) can only be \u003ccode\u003erequired\u003c/code\u003e,\nif all previously defined positional arguments are \u003ccode\u003erequired\u003c/code\u003e as well.\nThe \u003ccode\u003e\u003ca href=\"#synopsis\"\u003esynopsis\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#synopses\"\u003esynopses\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e usage functions\nand their \u003ccode\u003e*With\u003c/code\u003e versions mark \u003ccode\u003erequired\u003c/code\u003e options.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"reverse\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#reverse\"\u003ereverse\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003eboolean\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003ccode\u003ereverse\u003c/code\u003e defines whether the \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e of a given option should be reversed by\nthe \u003ccode\u003e\u003ca href=\"#reverseBools\"\u003ereverseBools\u003c/a\u003e\u003c/code\u003e or \u003ccode\u003e\u003ca href=\"#reverseFlags\"\u003ereverseFlags\u003c/a\u003e\u003c/code\u003e\nparser stages.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"types\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003estring[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003etypes\u003c/code\u003e defines what user input a command-line option takes.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n\u003ca href=\"#flag-option\"\u003eFlag options\u003c/a\u003e' \u003ccode\u003etypes\u003c/code\u003e must be \u003ccode\u003e[]\u003c/code\u003e.\n\u003ca href=\"#primitive-option\"\u003ePrimitive options\u003c/a\u003e' and \u003ca href=\"#primitive-pos-arg\"\u003eprimitive positional arguments\u003c/a\u003e'\n\u003ccode\u003etypes\u003c/code\u003e must be \u003ccode\u003e[\\_]\u003c/code\u003e,\nand \u003ca href=\"#array-option\"\u003earray options\u003c/a\u003e' and \u003ca href=\"#array-pos-arg\"\u003earray positional arguments\u003c/a\u003e'\n\u003ccode\u003etypes\u003c/code\u003e must be \u003ccode\u003e[\\_, \\_, ...]\u003c/code\u003e,\nwhere \u003ccode\u003e_\u003c/code\u003e is the name of a type given as a string.\n\u003ca href=\"#variadic-option\"\u003eVariadic options\u003c/a\u003e, \u003ca href=\"#variadic-pos-arg\"\u003evariadic positional arguments\u003c/a\u003e,\n\u003ca href=\"#subcommand-option\"\u003esubcommand options\u003c/a\u003e, and \u003ca href=\"#command-pos-arg\"\u003ecommand positional arguments\u003c/a\u003e\nmust not have a \u003ccode\u003etypes\u003c/code\u003e field.\n\u003ccode\u003etypes\u003c/code\u003e is also used by the\n\u003ccode\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#optsLists\"\u003eoptsLists\u003c/a\u003e\u003c/code\u003e,\n\u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e, and \u003ccode\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e usage functions\nand their \u003ccode\u003e*With\u003c/code\u003e versions to describe argument values\n(e.g. \u003ccode\u003e--format=\u0026lt;bool\u0026gt;\u003c/code\u003e for a \u003ccode\u003e\u003ca href=\"#bool\"\u003ebool\u003c/a\u003e\u003c/code\u003e option).\n\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e are other fields that change the argument value description.\nThese fields are applied in the following order (highest priority first):\n\u003ccode\u003e\u003ca href=\"#descArg\"\u003edescArg\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e, \u003ccode\u003etypes\u003c/code\u003e,\nand \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"values\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003eany[]\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cb\u003eThis field should only be set by parser stages and never manually.\u003c/b\u003e\n\u003ccode\u003evalues\u003c/code\u003e are assigned by the parser.\nYou may want to use \u003ccode\u003e\u003ca href=\"#defaultValues\"\u003edefaultValues\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThe length of a \u003ccode\u003evalues\u003c/code\u003e' array depends on the command-line option type:\n\u003ca href=\"#flag-option\"\u003eFlag options\u003c/a\u003e, \u003ca href=\"#primitive-option\"\u003eprimitive options\u003c/a\u003e,\n\u003ca href=\"#primitive-pos-arg\"\u003eprimitive positional arguments\u003c/a\u003e, and \u003ca href=\"#rest\"\u003erest\u003c/a\u003e\nmust each have \u003ccode\u003evalues\u003c/code\u003e of length \u003ccode\u003e1\u003c/code\u003e.\n\u003ca href=\"#array-option\"\u003eArray options\u003c/a\u003e' and \u003ca href=\"#array-pos-arg\"\u003earray positional arguments\u003c/a\u003e'\n\u003ccode\u003evalues\u003c/code\u003e field must match their \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e in length.\n\u003ca href=\"#subcommand-option\"\u003esubcommand option\u003c/a\u003e's, \u003ca href=\"#command-pos-arg\"\u003ecommand positional argument\u003c/a\u003e's,\n\u003ca href=\"#variadic-option\"\u003evariadic option\u003c/a\u003e's, and \u003ca href=\"#variadic-pos-arg\"\u003evariadic positional argument\u003c/a\u003e's\n\u003ccode\u003evalues\u003c/code\u003e may have any number of entries.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### Option Decorators\n\nCertain changes to options are so frequent, that [`shargs-opts`][shargs-opts] provides decorators for them.\nYou may think of decorators as recurring patterns that are provided as functions.\n\n[`shargs-opts`][shargs-opts] provides the following decorators:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Decorator\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"complement\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#complement\"\u003ecomplement\u003c/a\u003e(prefix)(opt)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ecomplement\u003c/code\u003e transforms a \u003ccode\u003e\u003ca href=\"#bool\"\u003ebool\u003c/a\u003e\u003c/code\u003e or \u003ccode\u003e\u003ca href=\"#flag\"\u003eflag\u003c/a\u003e\u003c/code\u003e \noption into a complementary option prefixed with a given string\n(e.g. \u003ccode\u003e--no-html\u003c/code\u003e if used on \u003ccode\u003e--html\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThe complementary option has the same \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e as the original option,\nbut \u003ccode\u003e\u003ca href=\"#reverse\"\u003ereverses\u003c/a\u003e\u003c/code\u003e its value.\nIf \u003ccode\u003ecomplement\u003c/code\u003e is used,\nyou most probably want to also use the \u003ccode\u003e\u003ca href=\"#reverseBools\"\u003ereverseBools\u003c/a\u003e\u003c/code\u003e\nor \u003ccode\u003e\u003ca href=\"#reverseFlags\"\u003ereverseFlags\u003c/a\u003e\u003c/code\u003e parser stage.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {flag, complement} = require('shargs/opts')\n\nconst no = complement('--no-')\n\nconst html = flag('html', ['-H', '--html'], {defaultValues: ['false']})\nconst noHtml = no(html)\n```\n\nIs the same as:\n\n```js\nconst {flag} = require('shargs/opts')\n\nconst html = flag('html', ['-H', '--html'], {defaultValues: ['false']})\nconst noHtml = flag('html', ['--no-H', '--no-html'], {reverse: true})\n```\n\nNote the differences in `defaultValues` and `reverse`.\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"posArgToOpt\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#posArgToOpt\"\u003eposArgToOpt\u003c/a\u003e(args)(opt)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eposArgToOpt\u003c/code\u003e transforms a positional argument into an option\nby adding \u003ccode\u003e\u003ca href=\"#args\"\u003eargs\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {command, stringPos} = require('shargs/opts')\n\nconst opts = [stringPos('question')]\nconst deepThought = command('deepThought', opts)\n\nconst args = ['deepThought', 'D']\nposArgToOpt(args)(deepThought)\n```\n\nIs the same as:\n\n```js\nconst {subcommand} = require('shargs/opts')\n\nsubcommand(opts)('deepThought', args)\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### Verify Commands\n\nShargs provides a function for verifying that commands have the correct structure:\n\n```js\nconst {verifyCommand} = require('shargs')\n\nconst {errs, opt} = verifyCommand(deepThought)\n```\n\nIn the example, it would return a list of `errs` if `deepThought` was invalid.\nIf the command is valid, the `errs` list is empty.\n`verifyCommand` is used internally by `parserSync` and `parser`, but may be used independently.\n\n### The `parserSync` Function\n\nThe `parserSync` function is [`shargs`][shargs]' core abstraction.\nIt generates a command-line parser from a collection of parser stages\nand is usually used alongside [`shargs-parser`][shargs-parser]:\n\n```js\nconst {parserSync} = require('shargs')\nconst {cast, flagsAsBools, requireOpts, restrictToOnly} = require('shargs/parser')\nconst {reverseFlags, setDefaultValues, splitShortOpts} = require('shargs/parser')\n\nconst stages = {\n argv: [splitShortOpts],\n opts: [setDefaultValues, requireOpts, reverseFlags, cast],\n args: [flagsAsBools]\n}\n\nconst substages = {\n ask: [...stages.opts, restrictToOnly]\n}\n\nconst parser = parserSync(stages, substages)\n```\n\n`parserSync` takes two parameters:\n\n1. A [`stages`](#stages) object that takes [parser stages](#command-line-parsers)\n and defines what transformations should be applied in which order.\n2. An optional [`substages`](#substages) object that defines subcommand-specific `opts` parser stages.\n\n`parserSync` has a twin function called [`parser`](#async-parsers) that does the same, but works asynchronously.\n\n#### `stages`\n\nShargs has seven different processing steps called stages that are applied in a predefined order\nand transform argument values (`process.argv`) via command-line options (`opts`) to arguments (`args`):\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eStage\u003c/th\u003e\n\u003cth\u003eField\u003c/th\u003e\n\u003cth\u003eType\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"toArgv-field\"\u003e\n\u003ctd align=\"right\"\u003e1\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#toArgv-field\"\u003etoArgv\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;any =\u003e {errs, argv}\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms a value into command-line argument values syntax, e.g.\n\n```js\n\"-p commit -am 'First commit'\"\n```\n\ncould be transformed to\n\n```js\n['-p', 'commit', '-am', 'First commit']\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"argv-field\"\u003e\n\u003ctd align=\"right\"\u003e2\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#argv-field\"\u003eargv\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, argv} =\u003e {errs, argv}\u003e\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSeveral stages that modify command-line argument values, e.g.\n\n```js\n['-p', 'commit', '-am', 'First commit']\n```\n\ncould be transformed to\n\n```js\n['-p', 'commit', '-a', '-m', 'First commit']\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"toOpts-field\"\u003e\n\u003ctd align=\"right\"\u003e3\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#toOpts-field\"\u003etoOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ecommand =\u003e {errs, argv} =\u003e {errs, opts}\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms argument values into command-line options, e.g.\n\n```js\n['-p', 'commit', '-a', '-m', 'First commit']\n```\n\ncould be transformed to\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: [], values: [1]},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"opts-field\"\u003e\n\u003ctd align=\"right\"\u003e4\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#opts-field\"\u003eopts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, opts} =\u003e {errs, opts}\u003e\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSeveral stages that modify command-line options, e.g.\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: [], values: [1]},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\ncould be transformed to\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: ['bool'], values: ['true']},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"toArgs-field\"\u003e\n\u003ctd align=\"right\"\u003e5\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#toArgs-field\"\u003etoArgs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, opts} =\u003e {errs, args}\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms command-line options into arguments object arrays, e.g.\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: ['bool'], values: ['true']},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\ncould be transformed to\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: [\n {_: [], all: 'true', message: 'First commit'}\n ]}\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"args-field\"\u003e\n\u003ctd align=\"right\"\u003e6\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#args-field\"\u003eargs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, args} =\u003e {errs, args}\u003e\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSeveral stages that modify arguments object arrays, e.g.\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: [\n {_: [], all: 'true', message: 'First commit'}\n ]}\n]\n```\n\ncould be transformed to\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: {\n {_: [], all: true, message: 'First commit'}\n }}\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"fromArgs-field\"\u003e\n\u003ctd align=\"right\"\u003e7\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#fromArgs-field\"\u003efromArgs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, args} =\u003e any\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms argument object arrays into any result value:\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: [\n {_: [], all: true, message: 'First commit'}\n ]}\n]\n```\n\ncould be transformed to\n\n```js\n{\n _: [],\n paginate: {type: 'flag', count: 1},\n commit: {\n _: [],\n all: true,\n message: 'First commit'\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nThe [`argv`](#argv-field), [`opts`](#opts-field), and [`args`](#args-field) stages\nare the user-facing API to declare a parser's behavior.\n\nThe [`toOps`](#toOpts-field) and [`toArgs`](#toArgs-field) stages\ndefine the core behavior of [`parserSync`](#the-parserSync-function) (and [`parser`](#async-parsers))\nand shargs defines sensible defaults that should not have to be changed in most use cases.\nHowever, if you do have a use case that needs adjustments to those stages, you may carefully swap them out.\n\nIf you read the types from top to bottom, you get a good impression of how `parserSync` works.\n\n#### `substages`\n\n`substages` define custom `opts` stages for subcommands.\nThat means, while most subcommands are parsed using the `opts` defined in `stages`,\nthose whose [`key`](#key) matches a key in the `substages` object are parsed using the `opts` defined under that key.\n\nKeys may be deeply nested to account for [`subcommand`](#subcommand)s of [`subcommand`](#subcommand)s:\nE.g. if `ask` had a subcommand with the `question` [`key`](#key), `{ask: {question: [...stages.opts, restrictToOnly]}}` would assign custom `opts` to `question`.\n\nThe `_` [`key`](#key) is special in `substages`:\nIt is a wildcard that is used by any [`subcommand`](#subcommand) that is not given explicitly by [`key`](#key).\nE.g. `{ask: {_: [...stages.opts, restrictToOnly]}}` and `{_: {_: [...stages.opts, restrictToOnly]}}` both work for `question`.\n\n#### Async Parsers\n\nThe [`parserSync`](#the-parsersync-function) function has an asynchronous alternative called `parser`.\nIt is used exactly like `parserSync`, but also works with stages returning\n[JavaScript Promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\nand returns a Promise itself:\n\n```js\n// stages, substages, deepThought, argv are taken from the Getting Started section\n\nconst {parser} = require('shargs')\n\nconst asyncParser = parser(stages, substages)\nconst parse = asyncParser(deepThought)\nconst {errs, args} = await parse(argv)\n```\n\n In addition to `parserSync`'s parameters,\n `parser`'s [`stages`](#stages) and [`substages`](#substages) parameters also take parser stages that return Promises:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eStage\u003c/th\u003e\n\u003cth\u003eField\u003c/th\u003e\n\u003cth\u003eType\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"toArgv-field-async\"\u003e\n\u003ctd align=\"right\"\u003e1\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#toArgv-field-async\"\u003etoArgv\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;any =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, argv}\u0026nbsp;\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;any =\u003e Promise\u003c{errs, argv}\u003e\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms a value into command-line argument values syntax, e.g.\n\n```js\n\"-p commit -am 'First commit'\"\n```\n\ncould be transformed to\n\n```js\n['-p', 'commit', '-am', 'First commit']\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"argv-field-async\"\u003e\n\u003ctd align=\"right\"\u003e2\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#argv-field-async\"\u003eargv\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, argv} =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, argv}\u003e\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, argv} =\u003e Promise\u003c{errs, argv}\u003e\u003e\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSeveral stages that modify command-line argument values, e.g.\n\n```js\n['-p', 'commit', '-am', 'First commit']\n```\n\ncould be transformed to\n\n```js\n['-p', 'commit', '-a', '-m', 'First commit']\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"toOpts-field-async\"\u003e\n\u003ctd align=\"right\"\u003e3\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#toOpts-field-async\"\u003etoOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003ecommand =\u003e {errs, argv} =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, opts}\u0026nbsp;\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;command =\u003e {errs, argv} =\u003e Promise\u003c{errs, opts}\u003e\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms argument values into command-line options, e.g.\n\n```js\n['-p', 'commit', '-a', '-m', 'First commit']\n```\n\ncould be transformed to\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: [], values: [1]},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"opts-field-async\"\u003e\n\u003ctd align=\"right\"\u003e4\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#opts-field-async\"\u003eopts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, opts} =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, opts}\u003e\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, opts} =\u003e Promise\u003c{errs, opts}\u003e\u003e\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSeveral stages that modify command-line options, e.g.\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: [], values: [1]},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\ncould be transformed to\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: ['bool'], values: ['true']},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"toArgs-field-async\"\u003e\n\u003ctd align=\"right\"\u003e5\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#toArgs-field-async\"\u003etoArgs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, opts} =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, args}\u0026nbsp;\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, opts} =\u003e Promise\u003c{errs, args}\u003e\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms command-line options into arguments object arrays, e.g.\n\n```js\n[\n {key: 'paginate', args: ['-p'], types: [], values: [1]},\n {key: 'commit', args: ['commit'], opts: [...], values: [\n {key: 'all', args: ['-a'], types: ['bool'], values: ['true']},\n {key: 'message', args: ['-m'], types: ['string'], values: ['First commit']},\n ...\n ]},\n ...\n]\n```\n\ncould be transformed to\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: [\n {_: [], all: 'true', message: 'First commit'}\n ]}\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"args-field-async\"\u003e\n\u003ctd align=\"right\"\u003e6\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#args-field-async\"\u003eargs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, args} =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, args}\u003e\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Array\u003c{errs, args} =\u003e Promise\u003c{errs, args}\u003e\u003e\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSeveral stages that modify arguments object arrays, e.g.\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: [\n {_: [], all: 'true', message: 'First commit'}\n ]}\n]\n```\n\ncould be transformed to\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: {\n {_: [], all: true, message: 'First commit'}\n }}\n]\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"fromArgs-field-async\"\u003e\n\u003ctd align=\"right\"\u003e7\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#fromArgs-field-async\"\u003efromArgs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, args} =\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;any\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/code\u003e\u003cbr /\u003e\n\u0026nbsp;\u003ccode\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;{errs, args} =\u003e Promise\u0026lt;any\u0026gt;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/code\u003e\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms argument object arrays into any result value:\n\n```js\n[\n {_: [], paginate: {type: 'flag', count: 1}},\n {commit: [\n {_: [], all: true, message: 'First commit'}\n ]}\n]\n```\n\ncould be transformed to\n\n```js\n{\n _: [],\n paginate: {type: 'flag', count: 1},\n commit: {\n _: [],\n all: true,\n message: 'First commit'\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nIf you read the stages' field types from top to bottom, you get a good impression of what an asynchronous parser does.\nInternally, an asynchronous shargs parser really differs only in one major way from a synchronous parser:\nInstead of using function composition, it uses [Promise.prototype.then][then] to chain parser stages.\n\n#### Advanced Parsers\n\n+ [Multiple subcommands](#multiple-subcommands)\n\n### Command-line Parsers\n\nYou do not have to write all parser stages yourself.\nThe [`shargs-parser`][shargs-parser] library offers a large collection of common parser stages, you can use.\n\nThe parser stages presented here are split into *checks* and *stages*.\nWhile *checks* only report errors, *stages* also transform their `argv`, `opts`, or `args`.\nUsually, it makes sense to declare *checks* before *stages*.\n\n#### `argv` Checks\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"verifyArgv\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#verifyArgv\"\u003everifyArgv\u003c/a\u003e(rules)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports a \u003ca href=\"#FalseArgvRules\"\u003e\u003ccode\u003eFalseArgvRules\u003c/code\u003e\u003c/a\u003e error\nif the passed \u003ccode\u003erules\u003c/code\u003e predicate returns \u003ccode\u003efalse\u003c/code\u003e for an argument value.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf `rules` is not a function, reports a [`WrongArgvRulesType`](#WrongArgvRulesType) error.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {verifyArgv} = require('shargs/parser')\n\nconst rules = argv =\u003e (\n argv.some(_ =\u003e _ === '--question') \u0026\u0026\n argv.some(_ =\u003e _ === '--answer')\n)\n\nconst argv = ['--answer', '42']\n\nverifyArgv(rules)({argv})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'FalseArgvRules',\n msg: 'Your argv rules returned false...',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### `argv` Stages\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"equalsSignAsSpace\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#equalsSignAsSpace\"\u003eequalsSignAsSpace\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nAllows arguments of the form \u003ccode\u003e--answer=42\u003c/code\u003e to be interpreted like \u003ccode\u003e--answer 42\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt only removes the first `=`,\nso `['--question=1+2=3?']` is transformed into `['--question', '1+2=3?']`.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {equalsSignAsSpace} = require('shargs/parser')\n\nconst argv = ['--answer=42']\n\nequalsSignAsSpace({argv})\n```\n\nResult:\n\n```js\n{\n argv: ['--answer', '42']\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"shortOptsNoSpace\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#shortOptsNoSpace\"\u003eshortOptsNoSpace\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nAllows to omit whitespaces between short arguments and their values.\nPassing \u003ccode\u003e-a42\u003c/code\u003e would be the same as passing \u003ccode\u003e-a 42\u003c/code\u003e.\nCannot be used together with \u003ccode\u003e\u003ca href=\"#splitShortOpts\"\u003esplitShortOpts\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {shortOptsNoSpace} = require('shargs/parser')\n\nconst argv = ['-a42']\n\nshortOptsNoSpace({argv})\n```\n\nResult:\n\n```js\n{\n argv: ['-a', '42']\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"splitShortOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#splitShortOpts\"\u003esplitShortOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nAllows using short option groups.\nThe group \u003ccode\u003e-xvzf\u003c/code\u003e would be interpreted as \u003ccode\u003e-x -v -z -f\u003c/code\u003e.\nCannot be used together with \u003ccode\u003e\u003ca href=\"#shortOptsNoSpace\"\u003eshortOptsNoSpace\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {splitShortOpts} = require('shargs/parser')\n\nconst argv = ['-ha', '42']\n\nsplitShortOpts({argv})\n```\n\nResult:\n\n```js\n{\n argv: ['-h', '-a', '42']\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"traverseArgv\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#traverseArgv\"\u003etraverseArgv\u003c/a\u003e(p)(f)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms arguments by applying a function \u003ccode\u003ef\u003c/code\u003e to each argument satisfying a predicate \u003ccode\u003ep\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nWhile `p`'s signature is `arg =\u003e true|false`,\n`f`'s signature must be `(arg, index, argv) =\u003e ({errs = [], argv = []})`.\nMany other `argv` checks and stages are defined in terms of `traverseArgv`\nand it is of great help for writing custom `argv` stages.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {traverseArgv} = require('shargs/parser')\n\nconst argv = [\n '--answer=42',\n '--help'\n]\n\nconst hasEqualsSign = arg =\u003e arg.indexOf('=') \u003e -1\n\nconst replaceFirstEqualsSign = arg =\u003e ({\n argv: [\n arg.slice(0, arg.indexOf('=')),\n arg.slice(arg.indexOf('=') + 1)\n ]\n})\n\ntraverseArgv(hasEqualsSign)(replaceFirstEqualsSign)({argv})\n```\n\nResult:\n\n```js\n{\n argv: [\n '--answer', '42',\n '--help'\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### `opts` Checks\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"contradictOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#contradictOpts\"\u003econtradictOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports a \u003ca href=\"#ContradictionDetected\"\u003e\u003ccode\u003eContradictionDetected\u003c/code\u003e\u003c/a\u003e error if options with a \u003ccode\u003e\u003ca href=\"#contradicts\"\u003econtradicts\u003c/a\u003e\u003c/code\u003e list violate their constraints.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThis is the case, if both, the option and an option from its [`contradicts`](#contradicts) list, have [`values`](#values).\nIf [`contradicts`](#contradicts) is not a list, it reports a [`WrongContradictsType`](#WrongContradictsType) error.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {contradictOpts} = require('shargs/parser')\nconst {number, string} = require('shargs/opts')\n\nconst opts = [\n number('age', ['-a'], {\n values: ['27']\n }),\n string('birthday', ['-b'], {\n contradicts: ['age'],\n values: ['27.7.1927']\n })\n]\n\ncontradictOpts({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'ContradictionDetected',\n msg: 'Some given keys contradict each other.',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"demandASubcommand\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#demandASubcommand\"\u003edemandASubcommand\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports a \u003ca href=\"#SubcommandRequired\"\u003e\u003ccode\u003eSubcommandRequired\u003c/code\u003e\u003c/a\u003e\nunless at least one \u003ccode\u003e\u003ca href=\"#subcommand\"\u003esubcommand\u003c/a\u003e\u003c/code\u003e has \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {demandASubcommand} = require('shargs/parser')\nconst {flag, number, subcommand} = require('shargs/opts')\n\nconst opts = [\n subcommand([])('ask', ['ask'], {desc: 'Ask a question.'}),\n number('answer', ['-a', '--answer'], {\n values: ['42'],\n desc: 'The answer.'\n }),\n flag('help', ['-h', '--help'], {\n desc: 'Print this help message and exit.'\n })\n]\n\ndemandASubcommand({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'SubcommandRequired',\n msg: 'No subcommand found. Please use at least one subcommand!',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"implyOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#implyOpts\"\u003eimplyOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports an \u003ca href=\"#ImplicationViolated\"\u003e\u003ccode\u003eImplicationViolated\u003c/code\u003e\u003c/a\u003e error\nif options with an \u003ccode\u003e\u003ca href=\"#implies\"\u003eimplies\u003c/a\u003e\u003c/code\u003e list violate their constraints.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThis is the case, if the option has [`values`](#values), but an option from its [`implies`](#implies) list has not.\nIf [`implies`](#implies) is not a list, it reports a [`WrongImpliesType`](#WrongImpliesType) error.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {implyOpts} = require('shargs/parser')\nconst {number, string} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['-a']),\n string('question', ['-q'], {\n implies: ['answer'],\n values: ['How much is the fish?']\n })\n]\n\nimplyOpts({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'ImplicationViolated',\n msg: 'Some given keys that imply...',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"requireOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#requireOpts\"\u003erequireOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports a \u003ca href=\"#RequiredOptionMissing\"\u003e\u003ccode\u003eRequiredOptionMissing\u003c/code\u003e\u003c/a\u003e error\nif an option whose \u003ccode\u003e\u003ca href=\"#required\"\u003erequired\u003c/a\u003e\u003c/code\u003e field is \u003ccode\u003etrue\u003c/code\u003e is missing.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf [`values`](#values) is not an array,\nit reports a [`WrongFormatForRequiredOption`](#WrongFormatForRequiredOption) error.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {requireOpts} = require('shargs/parser')\nconst {string} = require('shargs/opts')\n\nconst opts = [\n string('question', ['--question'], {required: true})\n]\n\nrequireOpts({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'RequiredOptionIsMissing',\n msg: 'A required option has not been provided.',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"suggestOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#suggestOpts\"\u003esuggestOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nCorrects spelling mistakes by suggesting existing command-line arguments for all unknown provided arguments.\nE.g. if \u003ccode\u003e--asnwer\u003c/code\u003e was provided, the \u003ccode\u003e--answer\u003c/code\u003e argument would be suggested.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt checks all [rest](#rest) [`values`](#values),\nassuming they are in the [rest](#rest) category because of spelling mistakes.\nIt collects all command-line options' [`args`](#args)\nand computes a distance metric (currently Levenshtein distance) between each arg and each [`rest`](#rest).\nIt reports the results in a [`DidYouMean`](#DidYouMean) error,\nsuggesting probable [`args`](#args) replacements for spelling mistakes.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {suggestOpts} = require('shargs/parser')\nconst {number} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['-a', '--ans']),\n {values: ['--asn']}\n]\n\nsuggestOpts({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'DidYouMean',\n msg: 'An unknown command-line argument...',\n info: {\n argv: '--asn',\n options: [\n [],\n [],\n [{'--ans': number('answer', ['-a', '--ans'])}],\n [{'-a': number('answer', ['-a', '--ans'])}]\n ]\n }\n }\n ]\n}\n```\n\nThe `options` array looks a little bit strange, so an explanation is in order.\nThe array's index is the cost necessary to transform the unknown option in the arguments, represented as keys.\nBecause of this, you can conveniently work with the results, e.g. by only using the most probable ones:\n\n```js\n'Did you mean: ' + (\n options\n .slice(0, 3)\n .reduce((a, b) =\u003e a.concat(b))\n .flatMap(Object.keys)\n .join(', ')\n)\n```\n\nResults in:\n\n```bash\nDid you mean: --age\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"validatePosArgs\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#validatePosArgs\"\u003evalidatePosArgs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports an \u003ca href=\"#InvalidRequiredPositionalArgument\"\u003e\u003ccode\u003eInvalidRequiredPositionalArgument\u003c/code\u003e\u003c/a\u003e error\nif defined positional arguments (\u003ccode\u003e*Pos\u003c/code\u003e) violate their rules for the\n\u003ccode\u003e\u003ca href=\"#required\"\u003erequired\u003c/a\u003e\u003c/code\u003e field\nor the position of \u003ccode\u003e\u003ca href=\"#variadicPos\"\u003evariadicPos\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf a positional argument is [`required`](#required),\nall previously defined positional arguments must be [`required`](#required), as well,\nand no other positional arguments can be defined after a [`variadicPos`](#variadicPos).\nIn case of a violation of the second rule, `validatePosArgs` reports an\n[`InvalidVariadicPositionalArgument`](#InvalidVariadicPositionalArgument) error.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {validatePosArgs} = require('shargs/parser')\nconst {stringPos, variadicPos} = require('shargs/opts')\n\nconst opts = [\n stringPos('name1', {required: true, values: ['Arthur']}),\n stringPos('name2', {required: false, values: ['Ford']}),\n stringPos('name3', {required: true, values: ['Trillian']}),\n variadicPos('names', {values: ['Zaphod', 'Marvin']}),\n stringPos('name4', {values: ['Douglas']})\n]\n\nvalidatePosArgs({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'InvalidRequiredPositionalArgument',\n msg: 'If a positional argument is required, all prev...',\n info: {...}\n },\n {\n code: 'InvalidVariadicPositionalArgument',\n msg: 'Only the last positional argument may be variadic.',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"verifyOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#verifyOpts\"\u003everifyOpts\u003c/a\u003e(rules)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports a \u003ca href=\"#FalseOptsRules\"\u003e\u003ccode\u003eFalseOptsRules\u003c/code\u003e\u003c/a\u003e error\nif the \u003ccode\u003eopts\u003c/code\u003e array does not adhere to the \u003ccode\u003erules\u003c/code\u003e predicate.\n\u003ccode\u003erules\u003c/code\u003e must have the following function signature: \u003ccode\u003eopt =\u003e true|false\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf `rules` is not a function, `verifyOpts` reports a [`WrongOptsRulesType`](#WrongOptsRulesType) error.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {verifyOpts} = require('shargs/parser')\nconst {string} = require('shargs/opts')\n\nconst implies = (p, q) =\u003e !p || q\n\nconst rules = opts =\u003e implies(\n opts.some(_ =\u003e _.key === 'question' \u0026\u0026 _.values),\n opts.some(_ =\u003e _.key === 'answer' \u0026\u0026 _.values)\n)\n\nconst opts = [\n string('question', ['--question'], {\n values: ['How much is the fish?']\n }),\n number('answer', ['-a'])\n]\n\nverifyOpts(rules)({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'FalseOptsRules',\n msg: 'Your opts rules returned false...',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"verifyValuesArity\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#verifyValuesArity\"\u003everifyValuesArity\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports an error if an option's\n\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e do not fit its \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSee the [`values`](#values) documentations for the exact rules.\nIf the lengths of [`values`](#values) and [`types`](#types) do not match,\nan [`InvalidArity`](#InvalidArity) error is reported.\nIf the [`types`](#types) field has an invalid value, an [`InvalidTypes`](#InvalidTypes) error is reported\nand `verifyValuesArity` reports an [`InvalidValues`](#InvalidValues) error in case of invalid [`values`](#values).\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {verifyValuesArity} = require('shargs/parser')\nconst {number} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['--answer'], {values: ['42', '23']})\n]\n\nverifyValuesArity({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'InvalidArity',\n msg: \"An option's types arity does not match...\",\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### `opts` Stages\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"arrayOnRepeat\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#arrayOnRepeat\"\u003earrayOnRepeat\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nCollects all repeated \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003es in an array,\ninstead of keeping only the first mention of a \u003ccode\u003e\u003ca href=\"#key\"\u003ekey\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {arrayOnRepeat} = require('shargs/parser')\nconst {number, string} = require('shargs/opts')\n\nconst opts = [\n string('answer', ['-a'], {values: ['42']}),\n number('answer', ['-a'], {values: [42]})\n]\n\narrayOnRepeat({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n array(['string', 'number'])('answer', ['-a'], {\n values: ['42', 42]\n })\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"bestGuessOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#bestGuessOpts\"\u003ebestGuessOpts\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTakes a best guess approach to transform \u003ca href=\"#rest\"\u003erest\u003c/a\u003e values that did not match a command-line option\ninto new command-line options.\nE.g. \u003ccode\u003e{values: ['--version']}\u003c/code\u003e becomes \u003ccode\u003e{key: 'version', types: [], values: [1]}\u003c/code\u003e and\n\u003ccode\u003e[{values: ['--not']}, {values: ['panic']}]\u003c/code\u003e\nbecomes \u003ccode\u003e{key: 'not', types: ['string'], args: ['--not'], values: ['panic']}\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nSingle [`rest`](#rest) options are interpreted as [`flag`](#flag)s\nwhile two consecutive [`rest`](#rest) options are interpreted as [`string`](#string)s\nif the first [`rest`](#rest) is in short option format\n(one minus with a single character, e.g. `-n`, `-a`)\nor in long option format (two minuses with any more characters, e.g. `--name`, `--answer`).\n[`bestGuessArgs`](#bestGuessArgs) is very similar to `bestGuessOpts`,\nbut also considers non-consecutive rest [`values`](#values).\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {bestGuessOpts} = require('shargs/parser')\nconst {flag, string} = require('shargs/opts')\n\nconst opts = [\n string('age', ['--age'], {values: ['unknown']}),\n {values: ['--paranoid']},\n {values: ['--name']},\n {values: ['Marvin']},\n {values: ['foo']}\n]\n\nbestGuessOpts({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n string('age', ['--age'], {values: ['unknown']}),\n flag('paranoid', [], {values: [1]}),\n string('name', [], {values: ['Marvin']}),\n {values: ['foo']}\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"broadenBools\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#broadenBools\"\u003ebroadenBools\u003c/a\u003e(alt)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms \u003ccode\u003e\u003ca href=\"#bool\"\u003ebool\u003c/a\u003e\u003c/code\u003es with\n\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e like \u003ccode\u003e'yes'\u003c/code\u003e or \u003ccode\u003e'no'\u003c/code\u003e into\n\u003ccode\u003e\u003ca href=\"#bool\"\u003ebool\u003c/a\u003e\u003c/code\u003es with \u003ccode\u003e'true'\u003c/code\u003e or \u003ccode\u003e'false'\u003c/code\u003e\n\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e based on an \u003ccode\u003ealt\u003c/code\u003e mapping\n(e.g. \u003ccode\u003e{true: ['yes'], false: ['no']}\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {broadenBools} = require('shargs/parser')\nconst {bool, number} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['-a', '--answer'], {values: ['42']}),\n bool('verbose', ['--verbose'], {values: ['no']})\n]\n\nconst alt = {\n true: ['yes'],\n false: ['no', 'f']\n}\n\nbroadenBools(alt)({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n number('answer', ['-a', '--answer'], {values: ['42']}),\n bool('verbose', ['--verbose'], {values: ['false']})\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"cast\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#cast\"\u003ecast\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nCasts string \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e\ninto other JavaScript types (e.g. numbers, booleans)\naccording to the command-line options' \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e\n(e.g. \u003ccode\u003e{key: 'answer', types: ['number'], values: ['42']}\u003c/code\u003e is transformed to\n\u003ccode\u003e{key: 'answer', types: ['number'], values: [42]}\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf [`types`](#types) contains `'number'`, but [`values`](#values)\ncannot be cast into a number, an [`ArgumentIsNotANumber`](#ArgumentIsNotANumber) error is reported.\nIf [`types`](#types) contains `'bool'`, but [`values`](#values)\nis not `['true']` or `['false']`, an [`ArgumentIsNotABool`](#ArgumentIsNotABool) error is reported.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {cast} = require('shargs/parser')\nconst {bool, number} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['-a', '--answer'], {values: ['42']}),\n bool('verbose', ['--verbose'], {defaultValues: ['false']})\n]\n\ncast({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n number('answer', ['-a', '--answer'], {values: [42]}),\n bool('verbose', ['--verbose'], {defaultValues: [false]})\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"restrictToOnly\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#restrictToOnly\"\u003erestrictToOnly\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nValidates all command-line options with both, \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e\nand \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e fields,\nby making sure that all values in \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e\nare also contained in \u003ccode\u003e\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf values are not found in [`only`](#only),\na [`ValueRestrictionsViolated`](#ValueRestrictionsViolated) error is reported for each value.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {restrictToOnly} = require('shargs/parser')\nconst {number} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['--answer'], {only: ['42'], values: ['23']})\n]\n\nrestrictToOnly({opts})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'ValueRestrictionViolated',\n msg: 'A value lies outside the allowed values...',\n info: {...}\n }\n ],\n opts\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"reverseBools\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#reverseBools\"\u003ereverseBools\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms\n\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e of\n\u003ca href=\"#primitive-option\"\u003eprimitive options\u003c/a\u003e and\n\u003ca href=\"#array-option\"\u003earray options\u003c/a\u003e\nwhose \u003ccode\u003e\u003ca href=\"#types\"\u003etypes\u003c/a\u003e\u003c/code\u003e contain \u003ccode\u003e'bool'\u003c/code\u003e and whose\n\u003ccode\u003e\u003ca href=\"#reverse\"\u003ereverse\u003c/a\u003e\u003c/code\u003e field is \u003ccode\u003etrue\u003c/code\u003e\nby replacing \u003ccode\u003e'true'\u003c/code\u003e/\u003ccode\u003etrue\u003c/code\u003e with \u003ccode\u003e'false'\u003c/code\u003e/\u003ccode\u003efalse\u003c/code\u003e and vice versa.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {reverseBools} = require('shargs/parser')\nconst {bool} = require('shargs/opts')\n\nconst opts = [\n bool('verbose', ['-v'], {reverse: true, values: [true]}),\n bool('verbose', ['-v'], {reverse: true, values: ['true']})\n]\n\nreverseBools({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n bool('verbose', ['-v'], {reverse: true, values: [false]}),\n bool('verbose', ['-v'], {reverse: true, values: ['false']})\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"reverseFlags\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#reverseFlags\"\u003ereverseFlags\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms\n\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e of\n\u003ca href=\"#flag-option\"\u003eflag options\u003c/a\u003e whose \u003ccode\u003e\u003ca href=\"#reverse\"\u003ereverse\u003c/a\u003e\u003c/code\u003e field is \u003ccode\u003etrue\u003c/code\u003e\nby inverting the \u003ccode\u003e\u003ca href=\"#flag\"\u003eflag\u003c/a\u003e\u003c/code\u003e's value (e.g. \u003ccode\u003e1\u003c/code\u003e becomes \u003ccode\u003e-1\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {reverseFlags} = require('shargs/parser')\nconst {flag} = require('shargs/opts')\n\nconst opts = [\n flag('help', ['-h'], {reverse: true, values: [1]})\n]\n\nreverseFlags({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n flag('help', ['-h'], {reverse: true, values: [-1]})\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"setDefaultValues\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#setDefaultValues\"\u003esetDefaultValues\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms all options that have no\n\u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e, but \u003ccode\u003e\u003ca href=\"#defaultValues\"\u003edefaultValues\u003c/a\u003e\u003c/code\u003e,\nby setting the \u003ccode\u003e\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\u003c/code\u003e field\nto the \u003ccode\u003e\u003ca href=\"#defaultValues\"\u003edefaultValues\u003c/a\u003e\u003c/code\u003e' value.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst opts = [\n flag(['-f'], {defaultValues: [1]}),\n bool(['-b'], {defaultValues: ['true']})\n]\n\nsetDefaultValues({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n flag(['-f'], {values: [1]}),\n bool(['-b'], {values: ['true']})\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"traverseOpts\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#traverseOpts\"\u003etraverseOpts\u003c/a\u003e(p)(f)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms \u003ccode\u003eopts\u003c/code\u003e by applying a function \u003ccode\u003ef\u003c/code\u003e\nto each option satisfying a predicate \u003ccode\u003ep\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nWhile `p`'s signature is `opt =\u003e true|false`,\n`f`'s signature must be `(opt, index, opts) =\u003e ({errs = [], opts = []})`.\nMany other `opts` checks and stages are defined in terms of `traverseOpts`\nand it is of great help for writing custom `opts` stages.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {traverseOpts} = require('shargs/parser')\nconst {flag, number} = require('shargs/opts')\n\nconst opts = [\n number('answer', ['-a'], {values: ['42']}),\n flag('verbose', ['-v'], {values: [1]}),\n flag('help', ['-h'], {values: [1]})\n]\n\nconst isFlag = _ =\u003e Array.isArray(_.types) \u0026\u0026 _.types.length === 0\n\nconst reverseFlags = opt =\u003e ({\n opts: [\n {...opt, values: [-opt.values[0]]}\n ]\n})\n\ntraverseOpts(isFlag)(reverseFlags)({opts})\n```\n\nResult:\n\n```js\n{\n opts: [\n number('answer', ['-a'], {values: ['42']}),\n flag('verbose', ['-v'], {values: [-1]}),\n flag('help', ['-h'], {values: [-1]})\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### `args` Checks\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"failRest\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#failRest\"\u003efailRest\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports an \u003ccode\u003e\u003ca href=\"#UnexpectedArgument\"\u003eUnexpectedArgument\u003c/a\u003e\u003c/code\u003e error\nfor each value in the rest field \u003ccode\u003e_\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {failRest} = require('shargs/parser')\n\nconst args = {\n _: ['--help']\n}\n\nfailRest({args})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'UnexpectedArgument',\n msg: 'An unexpected argument was used...',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"verifyArgs\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#verifyArgs\"\u003everifyArgs\u003c/a\u003e(rules)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nReports a \u003ca href=\"#FalseArgsRules\"\u003e\u003ccode\u003eFalseArgsRules\u003c/code\u003e\u003c/a\u003e error for each \u003ccode\u003eargs\u003c/code\u003e object\nthat does not adhere to the \u003ccode\u003erules\u003c/code\u003e predicate (with the signature \u003ccode\u003earg =\u003e true|false\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nReports a [`WrongArgsRulesType`](#WrongArgsRulesType) error if `rules` is not a function.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {verifyArgs} = require('shargs/parser')\n\nconst rules = args =\u003e (\n typeof args.question !== 'undefined' \u0026\u0026\n typeof args.answer !== 'undefined'\n)\n\nconst args = {\n question: 'How much is the fish?'\n}\n\nverifyArgs(rules)({args})\n```\n\nResult:\n\n```js\n{\n errs: [\n {\n code: 'FalseArgsRules',\n msg: 'Your args rules returned false...',\n info: {...}\n }\n ]\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### `args` Stages\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"bestGuessArgs\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#bestGuessArgs\"\u003ebestGuessArgs\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nIntroduces new arguments by best guess based on rest field values\n(e.g. \u003ccode\u003e{_: ['--version']}\u003c/code\u003e becomes \u003ccode\u003e{version: {type: 'flag', count: 1}}\u003c/code\u003e\nand \u003ccode\u003e{_: ['--not', 'panic']}\u003c/code\u003e becomes \u003ccode\u003e{not: 'panic'}\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nTransforms single rest field values into a flag and two consecutive rest options into a string.\nIt only assumes rest field values to be strings if the first rest is in short option format\n(one minus with a single character, e.g. `-h`, `-v`)\nor in long option format (two minuses with any more characters, e.g. `--help`, `--verbose`).\n`bestGuessArgs` is very similar to [`bestGuessOpts`](#bestGuessOpts),\nbut also considers rest fields that originally did not directly follow each other.\nE.g. assuming `--help` to be a known argument, `--not --help panic` would produce `{not: 'panic'}`,\nalthough its components were not in tandem.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {bestGuessArgs} = require('shargs/parser')\n\nconst obj = {\n args: {\n _: ['--answer', '42', 'foo', '-h'],\n command: {\n _: ['bar', '-v', '--question', 'What is answer?', '-v']\n }\n }\n}\n\nbestGuessArgs(obj)\n```\n\nResult:\n\n```js\n{\n args: {\n _: ['foo'],\n answer: '42',\n h: {type: 'flag', count: 1},\n command: {\n _: ['bar'],\n v: {type: 'flag', count: 2},\n question: 'What is answer?'\n }\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"bestGuessCast\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#bestGuessCast\"\u003ebestGuessCast\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nCasts string \u003ccode\u003eargs\u003c/code\u003e into other JavaScript types\nusing a best guess approach based on their values (e.g. \u003ccode\u003e{answer: '42'}\u003c/code\u003e becomes \u003ccode\u003e{answer: 42}\u003c/code\u003e\nand \u003ccode\u003e{all: 'true'}\u003c/code\u003e becomes \u003ccode\u003e{all: true}\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIt supports numbers and booleans (e.g. `{help: 'true'}` becomes `{help: true}`).\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {bestGuessCast} = require('shargs/parser')\n\nconst args = {\n _: ['--name', 'Marvin'],\n str1: 'yay',\n num1: '42.3',\n num2: '123e-1',\n num3: '0x11',\n num4: '0b11',\n bool1: 'true',\n arr1: ['-42', 'true', 'yay'],\n obj: {\n num5: '0o11',\n num6: '-Infinity',\n num7: '',\n num8: null,\n bool2: 'false',\n bool3: undefined\n }\n}\n\nbestGuessCast({args})\n```\n\nResult:\n\n```js\n{\n args: {\n _: ['--name', 'Marvin'],\n str1: 'yay',\n num1: 42.3,\n num2: 12.3,\n num3: 17,\n num4: 3,\n bool1: true,\n arr1: [-42, true, 'yay'],\n obj: {\n num5: 9,\n num6: -Infinity,\n num7: '',\n num8: null,\n bool2: false,\n bool3: undefined\n }\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"boolAsFlag\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#boolAsFlag\"\u003eboolAsFlag\u003c/a\u003e(key)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms bool arguments with \u003ccode\u003ekey\u003c/code\u003e in \u003ccode\u003eargs\u003c/code\u003e to a flag object.\nE.g., assuming the \u003ccode\u003eall\u003c/code\u003e key,\n\u003ccode\u003e{all: true}\u003c/code\u003e is transformed to \u003ccode\u003e{all: {type: 'flag', count: 1}}\u003c/code\u003e and\n\u003ccode\u003e{all: false}\u003c/code\u003e to \u003ccode\u003e{all: {type: 'flag', count: -1}}\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst args = {\n _: [],\n version: true\n}\n\nboolAsFlag('version')({args})\n```\n\nResult:\n\n```js\n{\n _: [],\n version: {type: 'flag', count: 1}\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"boolsAsFlags\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#boolsAsFlags\"\u003eboolsAsFlags\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms all bool arguments in \u003ccode\u003eargs\u003c/code\u003e to flag objects\nusing \u003ccode\u003e\u003ca href=\"#boolAsFlag\"\u003eboolAsFlag\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst args = {\n _: [],\n html: false,\n version: true\n}\n\nboolsAsFlags({args})\n```\n\nResult:\n\n```js\n{\n _: [],\n html: {type: 'flag', count: -1},\n version: {type: 'flag', count: 1}\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"clearRest\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#clearRest\"\u003eclearRest\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nSets rest values to an empty array (i.e. \u003ccode\u003e{_: []}\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {clearRest} = require('shargs/parser')\n\nconst args = {_: ['--verbose']}\n\nclearRest({args})\n```\n\nResult:\n\n```js\n{\n args: {_: []}\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"flagAsBool\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#flagAsBool\"\u003eflagAsBool\u003c/a\u003e(key)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms flags with \u003ccode\u003ekey\u003c/code\u003e in \u003ccode\u003eargs\u003c/code\u003e to a bool value.\nE.g., assuming the \u003ccode\u003eall\u003c/code\u003e key,\n\u003ccode\u003e{all: {type: 'flag', count: 1}}\u003c/code\u003e is transformed to \u003ccode\u003e{all: true}\u003c/code\u003e and\n\u003ccode\u003e{all: {type: 'flag', count: -1}}\u003c/code\u003e to \u003ccode\u003e{all: false}\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf its `count` is greater than `0` it is considered `true`, otherwise it is considered `false`.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {flagAsBool} = require('shargs/parser')\n\nconst args = {\n verbose: {type: 'flag', count: 1}\n}\n\nflagAsBool('verbose')({args})\n```\n\nResult:\n\n```js\n{\n args: {\n verbose: true\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"flagAsNumber\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#flagAsNumber\"\u003eflagAsNumber\u003c/a\u003e(key)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms flags with \u003ccode\u003ekey\u003c/code\u003e in \u003ccode\u003eargs\u003c/code\u003e to a number using its \u003ccode\u003ecount\u003c/code\u003e.\nE.g., assuming the \u003ccode\u003everbose\u003c/code\u003e key,\n\u003ccode\u003e{verbose: {type: 'flag', count: 3}}\u003c/code\u003e becomes \u003ccode\u003e{verbose: 3}\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {flagAsNumber} = require('shargs/parser')\n\nconst args = {\n verbose: {type: 'flag', count: 2}\n}\n\nflagAsNumber('version')({args})\n```\n\nResult:\n\n```js\n{\n args: {\n verbose: 2\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"flagsAsBools\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#flagsAsBools\"\u003eflagsAsBools\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms all flag arguments in \u003ccode\u003eargs\u003c/code\u003e to bool values\nusing \u003ccode\u003e\u003ca href=\"#flagAsBool\"\u003eflagAsBool\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {flagsAsBools} = require('shargs/parser')\n\nconst args = {\n verbose: {type: 'flag', count: 1}\n}\n\nflagsAsBools({args})\n```\n\nResult:\n\n```js\n{\n args: {\n verbose: true\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"flagsAsNumbers\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#flagsAsNumbers\"\u003eflagsAsNumbers\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms all flag arguments in \u003ccode\u003eargs\u003c/code\u003e to numbers using their \u003ccode\u003ecount\u003c/code\u003e\nlike \u003ccode\u003e\u003ca href=\"#flagAsNumber\"\u003eflagAsNumber\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {flagsAsNumbers} = require('shargs/parser')\n\nconst args = {\n verbose: {type: 'flag', count: 2}\n}\n\nflagsAsNumbers({args})\n```\n\nResult:\n\n```js\n{\n args: {\n verbose: 2\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"mergeArgs\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#mergeArgs\"\u003emergeArgs\u003c/a\u003e(merge)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms \u003ccode\u003eargs\u003c/code\u003e by \u003ci\u003eflattening them\u003c/i\u003e\nby recursively merging nested objects into their parent object\n(e.g. \u003ccode\u003e{ask: {question: '42?'}, answer: 42}\u003c/code\u003e becomes \u003ccode\u003e{question: '42?', answer: 42}\u003c/code\u003e).\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nA custom `merge` function may be passed with the following function signature:\n`(obj1 = {}, obj2 = {}) =\u003e {}`.\nThe default `merge` function (if `merge` is `undefined`)\nprefers keys from the parent object over keys from nested objects,\nbut concatenates rest values (`_`) from both objects\n(e.g. `{_: ['foo'], answer: 42, ask: {_: ['bar'], answer: 23}}` becomes\n`{_: ['foo', 'bar'], answer: 42}`).\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {mergeArgs} = require('shargs/parser')\n\nconst args = {\n _: ['--help'],\n version: {type: 'flag', count: 2},\n name: 'Arthur',\n command: {\n _: ['-v'],\n version: {type: 'flag', count: 1},\n name: 'Trillian',\n help: true\n },\n verbose: true\n}\n\nconst mergeLeft = (outer, inner) =\u003e ({\n ...inner,\n ...outer,\n _: [\n ...(outer._ || []),\n ...(inner._ || [])\n ]\n})\n\nmergeArgs(mergeLeft)({args})\n```\n\nResult:\n\n```js\n{\n args: {\n _: ['--help', '-v'],\n version: {type: 'flag', count: 2},\n name: 'Arthur',\n help: true,\n verbose: true\n }\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"numberAsFlag\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#numberAsFlag\"\u003enumberAsFlag\u003c/a\u003e(key)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms numbers with \u003ccode\u003ekey\u003c/code\u003e in \u003ccode\u003eargs\u003c/code\u003e to flag objects.\nThe number becomes the flag's \u003ccode\u003ecount\u003c/code\u003e.\nE.g. \u003ccode\u003e{answer: 42}\u003c/code\u003e becomes \u003ccode\u003e{answer: {type: 'flag', count: 42}}\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst args = {\n _: [],\n answer: 42\n}\n\nnumberAsFlag('answer')({args})\n```\n\nResult:\n\n```js\n{\n _: [],\n answer: {type: 'flag', count: 42}\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"numbersAsFlags\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#numbersAsFlags\"\u003enumbersAsFlags\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms all numbers in \u003ccode\u003eargs\u003c/code\u003e to flag objects using \u003ccode\u003e\u003ca href=\"#numberAsFlag\"\u003enumberAsFlag\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst args = {\n _: [],\n answer: 42\n}\n\nnumbersAsFlags({args})\n```\n\nResult:\n\n```js\n{\n _: [],\n answer: {type: 'flag', count: 42}\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"traverseArgs\"\u003e\n\u003ctd\u003e\u003ccode\u003e\u003ca href=\"#traverseArgs\"\u003etraverseArgs\u003c/a\u003e(fs)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nTransforms \u003ccode\u003eargs\u003c/code\u003e by applying functions \u003ccode\u003efs\u003c/code\u003e to each key/value pair based on the value's type.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n`fs` supports the following types:\n`array`, `boolean`, `flag`, `function`, `null`, `number`, `object`, `string`, `undefined`, and `otherwise`.\nThe default behavior for most types is to not change the value, with three notable exceptions:\n`function`s and `otherwise`s key/value pairs are removed from args,\nwhile `object`'s default function applies `fs` to nested objects.\n`{flag: ({key, val, errs, args}) =\u003e ({errs, args})}`\nis the signature for `fs` with fields for each type.\nMany other `args` checks and stages are defined in terms of `traverseArgs`\nand it is of great help for writing custom `args` stages.\n\n\u003cbr /\u003e\n\nExample:\n\n```js\nconst {traverseArgs} = require('shargs/parser')\n\nconst args = {\n verbose: {type: 'flag', count: 2},\n answer: 23\n}\n\nconst fs = {\n flag: ({key, val, errs, args}) =\u003e ({\n errs,\n args: {...args, [key]: val.count}\n }),\n number: ({key, val, errs, args}) =\u003e ({\n errs,\n args: {...args, [key]: val + 19}\n })\n}\n\ntraverseArgs(fs)({args})\n```\n\nResult:\n\n```js\n{\n args: {\n verbose: 2,\n answer: 42\n }\n}\n```\n\nAllowed \u003ccode\u003efs\u003c/code\u003e fields:\n\n```js\nconst fs = {\n array: ({key, val, errs, args}) =\u003e ({errs, args}),\n boolean: ({key, val, errs, args}) =\u003e ({errs, args}),\n flag: ({key, val, errs, args}) =\u003e ({errs, args}),\n function: ({key, val, errs, args}) =\u003e ({errs, args}),\n null: ({key, val, errs, args}) =\u003e ({errs, args}),\n number: ({key, val, errs, args}) =\u003e ({errs, args}),\n otherwise: ({key, val, errs, args}) =\u003e ({errs, args}),\n object: ({key, val, errs, args}) =\u003e ({errs, args}),\n string: ({key, val, errs, args}) =\u003e ({errs, args}),\n undefined: ({key, val, errs, args}) =\u003e ({errs, args})\n}\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### Advanced Parser Stages\n\n+ [Custom checks and stages](#custom-checks-and-stages)\n\n### Automatic Usage Documentation Generation\n\nShargs strictly separates the concerns of parsing command-line arguments and generating usage documentation.\nThe [`shargs-usage`][shargs-usage] module specializes on\ngenerating terminal-based usage documentation for `--help` flags\nfrom [command-line options](#command-line-options):\n\n```js\nconst {desc, optsLists, space, synopses, usage} = require('shargs/usage')\n\nconst docs = usage([\n synopses,\n space,\n optsLists,\n space,\n desc\n])\n```\n\n[`shargs-usage`][shargs-usage] lets you define how your usage documentation should look like in a declarative way.\nIn the example, we tell our `docs` to start with [`synopses`](#synopses), have [`optsLists`](#optsLists) in the body,\nand close with a [`desc`](#usage-desc)ription.\nWe separate these three parts with [`space`](#space)s and enclose everything in a [`usage`](#usage) function.\n\nNote that we did not mention any command-line options, yet:\n\n```js\nconst {command, flag, number, stringPos} = require('shargs/opts')\n\nconst opts = [\n stringPos('question', {desc: 'Ask a question.', required: true}),\n number('answer', ['-a', '--answer'], {desc: 'The answer.', defaultValues: [42]}),\n flag('help', ['-h', '--help'], {desc: 'Print this help message and exit.'})\n]\n\nconst deepThought = command('deepThought', opts, {\n desc: 'Deep Thought was created to come up with the Answer to ' +\n 'The Ultimate Question of Life, the Universe, and Everything.'\n})\n\nconst optsDocs = docs(deepThought)\n```\n\n`optsDocs` now knows what to layout (`deepThought`), and how to layout it (`docs`).\nFinally, we `style` the different parts (lines and columns) of the documentation:\n\n```js\nconst style = {\n line: [{width: 60}],\n cols: [{width: 25}, {width: 35}]\n}\n\nconst text = optsDocs(style)\n```\n\nNow, if we `console.log(text)`, the following `text` is printed to the console:\n\n```bash\ndeepThought (\u003cquestion\u003e) [-a|--answer] [-h|--help] \n \n\u003cquestion\u003e Ask a question. [required] \n-a, --answer=\u003cnumber\u003e The answer. [default: 42] \n-h, --help Print this help message and exit. \n \nDeep Thought was created to come up with the Answer to The \nUltimate Question of Life, the Universe, and Everything. \n```\n\n`deepThought`, `docs`, and [`style`](#style)\nare the moving parts of [automatic usage documentation generation](#automatic-usage-documentation-generation)\nand are defined independently.\nWe have already talked about [command-line options](#command-line-options) before\nand will talk about [`style`](#style) in an upcoming section.\n\n#### Usage Functions\n\n[`shargs-usage`][shargs-usage] provides the following usage functions to declare layouts:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Usage\u0026nbsp;Function\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr name=\"usage-desc\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"usage-descWith\"\u003e\u003ca href=\"#usage-desc\"\u003edesc\u003c/a\u003e\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#usage-descWith\"\u003edescWith\u003c/a\u003e({id})\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003edesc\u003c/code\u003e takes a command-line option's \u003ccode\u003e\u003ca href=\"#desc\"\u003edesc\u003c/a\u003e\u003c/code\u003e field\nand formats it according to a \u003ccode\u003e\u003ca href=\"#style\"\u003estyle\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf the description is too long to fit one line, it is split and spread over several lines.\n`desc` is defined as `descWith({id: 'line'})`.\n\n\u003cbr /\u003e\n\nExample:\n\n```bash\nDeep Thought should answer the Ultimate \nQuestion \n```\n\nCode:\n\n```js\nconst {desc, usage} = require('shargs/usage')\n\nconst opt = {\n opts: [],\n desc: 'Deep Thought should answer the Ultimate Question'\n}\n\nconst style = {\n line: [{width: 40}]\n}\n\nusage([\n desc\n])(opt)(style)\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"note\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"noteWith\"\u003e\u003ca href=\"#note\"\u003enote\u003c/a\u003e(string)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#noteWith\"\u003enoteWith\u003c/a\u003e({id})(string)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003enote\u003c/code\u003e takes a \u003ccode\u003estring\u003c/code\u003e and formats it according to a \u003ccode\u003e\u003ca href=\"#style\"\u003estyle\u003c/a\u003e\u003c/code\u003e,\nignoring its second parameter.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf the string is too long to fit one line, it is split and spread over several lines.\n`note` is defined as `noteWith({id: 'line'})`.\n\n\u003cbr /\u003e\n\nExample:\n\n```bash\nDeep Thought was created to come up with\nthe Answer \n```\n\nCode:\n\n```js\nconst {note, usage} = require('shargs/usage')\n\nconst style = {\n line: [{width: 40}]\n}\n\nusage([\n note('Deep Thought was created to come up with the Answer')\n])()(style)\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"notes\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"notesWith\"\u003e\u003ca href=\"#notes\"\u003enotes\u003c/a\u003e(strings)\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#notesWith\"\u003enotesWith\u003c/a\u003e({id})(strings)\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003enotes\u003c/code\u003e takes a list of \u003ccode\u003estrings\u003c/code\u003e and formats it\naccording to a \u003ccode\u003e\u003ca href=\"#style\"\u003estyle\u003c/a\u003e\u003c/code\u003e,\nignoring its second parameter.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nIf a string is too long to fit one line, it is split and spread over several lines.\n`notes` is defined as `notesWith({id: 'line'})`.\n\n\u003cbr /\u003e\n\nExample:\n\n```bash\nDeep Thought was created to come up with\nthe Answer \nto The Ultimate Question. \n```\n\nCode:\n\n```js\nconst {notes, usage} = require('shargs/usage')\n\nconst style = {\n line: [{width: 40}]\n}\n\nusage([\n notes([\n 'Deep Thought was created to come up with the Answer',\n 'to The Ultimate Question.'\n ])\n])()(style)\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"optsDef\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"optsDefWith\"\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#optsDefWith\"\u003eoptsDefWith\u003c/a\u003e({id, pad})\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eoptsDef\u003c/code\u003e layouts its \u003ccode\u003eopts\u003c/code\u003e as a definition list\nand formats it according to its \u003ccode\u003e\u003ca href=\"#style\"\u003estyle\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThe term part comprises of an opt's [`args`](#args), [`descArg`](#descArg),\n[`only`](#only), [`types`](#types), and [`key`](#key) fields, followed by the\n[`contradicts`](#contradicts), [`defaultValues`](#defaultValues),\n[`implies`](#implies), and [`required`](#required) fields.\nThe [`desc`](#desc) field is given in the definition part.\n`optsDef` is defined as `optsDefWith({id: 'line', pad: 4})`.\n\n\u003cbr /\u003e\n\nExample:\n\n```bash\n-a, --answer=\u003cnumber\u003e [default: 42] \n The answer. \n-h, --help \n Prints help. \n--version \n The version. \n```\n\nCode:\n\n```js\nconst {optsDef, usage} = require('shargs/usage')\nconst {flag, number} = require('shargs/opts')\n\nconst opt = {\n opts: [\n number('answer', ['-a', '--answer'], {\n desc: 'The answer.', defaultValues: ['42']\n }),\n flag('help', ['-h', '--help'], {desc: 'Prints help.'}),\n flag('version', ['--version'], {desc: 'The version.'})\n ]\n}\n\nconst style = {\n line: [{width: 40}]\n}\n\nusage([\n optsDef\n])(opt)(style)\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"optsDefs\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"optsDefsWith\"\u003e\u003ca href=\"#optsDefs\"\u003eoptsDefs\u003c/a\u003e\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#optsDefsWith\"\u003eoptsDefsWith\u003c/a\u003e({id, pad})\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eoptsDefs\u003c/code\u003e first layouts its \u003ccode\u003eopts\u003c/code\u003e and then the \u003ccode\u003e\u003ca href=\"#opts\"\u003eopts\u003c/a\u003e\u003c/code\u003e\nof all its \u003ccode\u003e\u003ca href=\"#subcommand\"\u003esubcommand\u003c/a\u003e\u003c/code\u003es recursively,\nusing \u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003es,\nindenting each \u003ccode\u003e\u003ca href=\"#optsDef\"\u003eoptsDef\u003c/a\u003e\u003c/code\u003e layer by \u003ccode\u003epad\u003c/code\u003e spaces.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n`optsDefs` is defined as `optsDefsWith({id: 'line', pad: 4})`.\n\n\u003cbr /\u003e\n\nExample:\n\n```bash\n-a, --answer=\u003cnumber\u003e [default: 42] \n The answer. \n-h, --help \n Show the usage docs. \nask [required] \n Ask questions. \n -h \n Usage docs. \n \u003cquestions\u003e... [required] \n Questions. \n```\n\nCode:\n\n```js\nconst {optsDefs, usage} = require('shargs/usage')\nconst {flag, subcommand} = require('shargs/opts')\nconst {number, variadicPos} = require('shargs/opts')\n\nconst required = true\n\nconst askOpts = [\n flag('help', ['-h'], {desc: 'Show the usage docs.'}),\n variadicPos('questions', {required, desc: 'Questions.'})\n]\n\nconst ask = subcommand(askOpts)\n\nconst opt = {\n opts: [\n ask('ask', ['ask'], {desc: 'Ask questions.', required}),\n number('answer', ['-a', '--answer'], {\n desc: 'The answer.', defaultValues: ['42']\n }),\n flag('help', ['-h', '--help'], {desc: 'Usage docs.'})\n ]\n}\n\nconst style = {\n line: [{width: 40}]\n}\n\nusage([\n optsDefs\n])(opt)(style)\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr name=\"optsList\"\u003e\n\u003ctd\u003e\n\u003ccode name=\"optsListWith\"\u003e\u003ca href=\"#optsList\"\u003eoptsList\u003c/a\u003e\u003c/code\u003e\u003cbr /\u003e\n\u003ccode\u003e\u003ca href=\"#optsListWith\"\u003eoptsListWith\u003c/a\u003e({id})\u003c/code\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ccode\u003eoptsList\u003c/code\u003e layouts its \u003ccode\u003eopts\u003c/code\u003e as a \u003ccode\u003e\u003ca href=\"#table\"\u003etable\u003c/a\u003e\u003c/code\u003e with two columns\nand formats it according to its \u003ccode\u003e\u003ca href=\"#style\"\u003estyle\u003c/a\u003e\u003c/code\u003e.\n\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThe first column comprises of an opt's [`args`](#args), [`descArg`](#descArg),\n[`only`](#only), [`types`](#types), and [`key`](#key) fields.\nThe [`desc`](#desc) field is given in the second column, foll","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyord%2Fshargs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyord%2Fshargs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyord%2Fshargs/lists"}