# Getopts
> Parse CLI arguments.
- Lightweight drop-in replacement for `minimist` and clones.
- Small (180 LOC), focused, no dependencies.
- Up to [6x faster](#benchmarks) than alternatives!
Break up command-line arguments into key-value pairs for easy look-up and retrieval. Built upon [utility conventions](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02) that have been used for decades, Getopts sane defaults help you write CLI tools that look and feel like the real deal.
```console
$ example --type=module -o main.js *.{js,json}
```
```js
import getopts from "getopts"
const options = getopts(process.argv.slice(2), {
alias: {
output: ["o", "f"],
type: "t",
},
})
```
The result is an object populated with all the parsed arguments.
```js
{
_: ["index.js", "package.json"],
output: "main.js",
type: "module",
o: "main.js",
f: "main.js",
t: "module",
}
```
## Installation
```console
npm install getopts
```
## Parsing rules
### Short options
A short option consists of a `-` followed by a single alphabetic character. Multiple options can be grouped together without spaces. Short options are boolean by default unless followed by an [operand](#operand) (non-option) or if adjacent to any non-alphabetic characters:
```js
getopts(["-ab", "-c"]) //=> { _: [], a:true, b:true, c:true }
```
```js
getopts(["-a", "alpha"]) //=> { _: [], a:"alpha" }
```
```js
getopts(["-abc1"]) //=> { _: [], a:true, b:true, c:1 }
```
Use [`opts.string`](#optsstring) to parse an option as a string regardless.
```js
getopts(["-kF12"], {
string: ["k"],
}) //=> { _: [], k:"F12" }
```
The first operand following an option will be used as its value. Use [`opts.boolean`](#optsboolean) to specify that an option should be parsed as a boolean regardless, causing the following argument to be treated as an operand instead.
```js
getopts(["-a", "alpha"], {
boolean: ["a"],
}) //=> { _: ["alpha"], a:true }
```
Any character listed in the ASCII table can be used as a short option if it's the first character after the dash.
```js
getopts(["-9", "-#10", "-%0.01"]) //=> { _:[], 9:true, #:10, %:0.01 }
```
### Long options
A long option consists of a `--` followed by a name and a value separated by an `=`. Long options without a value are boolean by default.
```js
getopts(["--turbo", "--warp=10"]) //=> { _: [], turbo:true, warp:10 }
```
```js
getopts(["--warp=e=mc^2"]) //=> { _: [], warp:"e=mc^2" }
```
```js
getopts(["--@", "alpha"]) //=> { _: [], @:"alpha" }
```
Negated options start with `--no-` and are always `false`.
```js
getopts(["--no-turbo"]) //=> { _: [], turbo:false }
```
### Operands
Every non-option argument is an operand. Operands are saved to the `result._` operands array.
```js
getopts(["alpha", "-w9", "bravo"]) //=> { _: ["alpha", "bravo"], w:9 }
```
```js
getopts(["--code=alpha", "bravo"]) //=> { _: ["bravo"], code:"alpha" }
```
Everything after a standalone `--` is an operand.
```js
getopts(["--alpha", "--", "--bravo", "--turbo"]) //=> { _:["--bravo", "--turbo"], alpha:true }
```
A single `-` is also treated as an operand.
```js
getopts(["--turbo", "-"]) //=> { _:["-"], turbo:true }
```
### Other
Options specified as boolean or string will be added to the result object as `false` or `""` (even if missing from the arguments array).
```js
getopts([], {
string: ["a"],
boolean: ["b"],
}) //=> { _:[], a:"", b:false }
```
Repeated options are stored as arrays with every value in order of appearance.
```js
getopts(["-x?alpha=bravo", "-x3.14", "-x"] //=> { _:[], a:["?alpha=bravo", 3.14, true] }
```
A value may contain newlines or other control characters.
```js
getopts(["--text=top\n\tbottom"]) //=> { _:[], text:"top\n\tbottom" }
```
`="false"` is converted to boolean by default.
```js
getopts(["--turbo=false"]) //=> { _:[], turbo:false }
```
## API
### `getopts(argv, opts)`
Parse command-line arguments. Returns an object mapping argument names to their values.
### `argv[]`
An array of arguments, usually [`process.argv`](https://nodejs.org/docs/latest/api/process.html#process_process_argv).
### `opts.alias`
An object of option aliases. An alias can be a string or an array of strings. Aliases let you declare substitute names for an option, e.g., the short (abbreviated) and long (canonical) variations.
```js
getopts(["-t"], {
alias: {
turbo: ["t", "T"],
},
}) //=> { _:[], t:true, T:true, turbo:true }
```
### `opts.boolean`
An array of options to parse as boolean. In the example below, `t` is parsed as a boolean, causing the following argument to be treated as an operand.
```js
getopts(["-t", "alpha"], {
boolean: ["t"],
}) //=> { _:["alpha"], t:true }
```
### `opts.string`
An array of flags to parse as strings. In the example below, `t` is parsed as a string, causing all adjacent characters to be treated as a single value and not as individual options.
```js
getopts(["-atabc"], {
string: ["t"],
}) //=> { _:[], a:true, t:"abc" }
```
### `opts.default`
An object of default values for options not present in the arguments array.
```js
getopts(["--warp=10"], {
default: {
warp: 15,
turbo: true,
},
}) //=> { _:[], warp:10, turbo:true }
```
### `opts.unknown()`
We call this function for each unknown option. Return `false` to discard the option. Unknown options are those that appear in the arguments array, but are not in `opts.string`, `opts.boolean`, `opts.default`, or `opts.alias`.
```js
getopts(["-abc"], {
unknown: (option) => "a" === option,
}) //=> { _:[], a:true }
```
### `opts.stopEarly`
A boolean property. If `true`, the operands array `_` will be populated with all the arguments after the first operand.
```js
getopts(["-w9", "alpha", "--turbo", "bravo"], {
stopEarly: true,
}) //=> { _:["alpha", "--turbo", "bravo"], w:9 }
```
This property is useful when implementing sub-commands in a CLI.
```js
import getopts from "getopts"
import { install, update, uninstall } from "./commands.js"
const options = getopts(process.argv.slice(2), {
stopEarly: true,
})
const [command, subargv] = options._
if (command === "install") {
install(subargv)
} else if (command === "update") {
update(subargv)
} else if (command === "uninstall") {
uninstall(subargv)
}
```
## Benchmarks
```console
npm --prefix bench start
```
## License
[MIT](LICENSE.md)
![[ICO]](/icons/blank.gif){kind=icon}
![[PARENTDIR]](/icons/back.gif){kind=icon}
![[TXT]](/icons/text.gif){kind=icon}
![[ ]](/icons/unknown.gif){kind=icon}