What is getopts?
The getopts npm package is a lightweight and fast option parser for Node.js. It is used to parse command-line options and arguments in a simple and efficient manner.
What are getopts's main functionalities?
Basic Option Parsing
This feature allows you to parse command-line options and arguments. The code sample demonstrates how to use getopts to parse the command-line arguments passed to a Node.js script.
const getopts = require('getopts');
const options = getopts(process.argv.slice(2));
console.log(options);
Default Values
This feature allows you to set default values for options. The code sample shows how to provide default values for the 'name' and 'age' options.
const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
default: {
name: 'defaultName',
age: 25
}
});
console.log(options);
Aliases
This feature allows you to define aliases for options. The code sample demonstrates how to set up aliases for the 'name' and 'age' options.
const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
alias: {
n: 'name',
a: 'age'
}
});
console.log(options);
Boolean Options
This feature allows you to specify which options should be treated as boolean. The code sample shows how to define 'verbose' and 'debug' as boolean options.
const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
boolean: ['verbose', 'debug']
});
console.log(options);
Unknown Option Handling
This feature allows you to handle unknown options. The code sample demonstrates how to log an error message for unknown options and prevent them from being included in the parsed options.
const getopts = require('getopts');
const options = getopts(process.argv.slice(2), {
unknown: (option) => {
console.error(`Unknown option: ${option}`);
return false;
}
});
console.log(options);
Other packages similar to getopts
minimist
Minimist is a popular option parser for Node.js that is similar to getopts. It provides a simple way to parse command-line arguments and supports features like default values, aliases, and boolean options. Compared to getopts, minimist is more widely used and has a larger community.
yargs
Yargs is a powerful option parser for Node.js that offers a rich set of features for building command-line tools. It supports advanced features like command handling, middleware, and interactive prompts. Yargs is more feature-rich compared to getopts, making it suitable for more complex CLI applications.
commander
Commander is a comprehensive option parser and command-line interface (CLI) framework for Node.js. It provides a robust set of features for defining commands, options, and arguments. Commander is more feature-complete compared to getopts and is ideal for building complex CLI applications with multiple commands.
Getopts
Getopts is a high performance CLI options parser for Node.js. It is used to parse and validate the command-line arguments passed to your program at runtime. It follows the Utility Syntax Guidelines so that your programs behave like typical UNIX utilities effortlessly. Once you learn how to use it, you'll never go back to parsing process.argv
on your own again.
Installation
npm i getopts
Usage
You want to parse the command-line arguments passed to your program at runtime. How do you do that?
$ example/demo --turbo -xw10 -- alpha beta
Getopts main export is a function that takes two arguments: an array of arguments and (optional) object with options.
The command-line arguments can be found in the process.argv
array. The first item in the array will be the path to the node executable, followed by the path to the file being executed. We don't need either one, so slice everything after the second index and pass it to getopts
.
const getopts = require("getopts")
const options = getopts(process.argv.slice(2), {
alias: {
w: "warp",
t: "turbo"
}
})
The return value is an object that maps the argument names to their values. Use it to look up the value of an option by its name. The underscore _
key is reserved for operands. Operands consist of bare arguments (non-options), the dash -
symbol and every argument after a double-dash --
sequence.
{
_: ["alpha", "beta"],
w: 10,
x: true,
t: true,
warp: 10,
turbo: true
}
Parsing Rules
Short Options
-
A short option consists of a dash -
followed by a single alphabetic character. Multiple short options can be clustered together without spaces. Short options will be casted to boolean unless followed by an operand or if adjacent to one or more non-alphabetic characters matching the regular expression /[!-@[-`{-~][\s\s]*/
.
getopts(["-ab", "-c"])
getopts(["-a", "alpha"])
getopts(["-abc1"])
-
Only the last character in a cluster of options can be parsed as a string or as a number depending on the argument that follows it. Any options preceding it will be true
. You can use opts.string
to indicate that one or more options should be parsed as strings.
getopts(["-abc-100"], {
string: ["b"]
})
-
The argument immediately following a short or a long option, which is not an option itself, will be parsed as the value of the option. You can use opts.boolean
to indicate that one or more options should be parsed as booleans, causing any adjacent argument to be parsed as an operand and not as a value.
getopts(["-a", "alpha"], {
boolean: ["a"]
})
-
Any character listed in the ASCII table can be used as a short option if it's the first character after the dash.
getopts(["-9", "-#10", "-%0.01"])
Long Options
-
A long option consists of two dashes --
followed by one or more characters. Any character listed in the ASCII table can be used to form a long option with the exception of the =
symbol, which separates an option's name and value.
getopts(["--turbo", "--warp=10"])
getopts(["--warp=e=mc^2"])
getopts(["----", "alpha"])
-
Options can be negated if they are prefixed with the sequence --no-
. Their value is always false
.
getopts(["--no-turbo"])
Operands
-
Every argument after the first double-dash sequence --
is saved to the operands array _
.
getopts(["--", "--alpha", "001"])
-
Every non-option, standalone argument is an operand.
getopts(["alpha", "-w9"])
getopts(["--code=alpha", "beta"])
-
A dash -
is an operand.
getopts(["--turbo", "-"])
Other
-
Options missing from the arguments array that have been designated as a boolean or string type will be added to the result object as false
and ""
respectively.
getopts([], {
string: ["a"],
boolean: ["b"]
})
-
The string "false"
is always casted to a boolean false
.
getopts(["--turbo=false"])
-
Options that appear multiple times are parsed as an array that consists of every value in the order they are found.
getopts(["-a?alpha=beta", "-aa0.1"]
-
A value may contain newlines or other control characters.
getopts(["--text=top\n\tcenter\bottom"])
API
getopts(argv, opts)
Parse command line arguments. Expects an array of arguments, e.g. process.argv
, and object with options, and returns an object that maps the argument names to their values.
argv
Array of arguments.
opts
opts.alias
An object of option aliases. An alias can be a string or an array of strings. Aliases let you define alternate names for an option, e.g. the short (abbreviated) and long (canonical) variations.
getopts(["-t"], {
alias: {
turbo: ["t", "T"]
}
})
opts.boolean
An array of options that should be parsed as booleans. In the example, declaring t
as boolean causes the next argument to be parsed as an operand and not as a value.
getopts(["-t", "alpha"], {
boolean: ["t"]
})
opts.string
An array of options that should be parsed as strings. In the example, by declaring t
as string, all adjacent characters are parsed as a single value and not as individual options.
getopts(["-atabc"], {
string: ["t"]
})
opts.default
An object of default values for options that are not present in the arguments array.
getopts(["--warp=10"], {
default: {
warp: 15,
turbo: true
}
})
opts.unknown
A function that will be invoked for every unknown option. Return false
to discard the option. Unknown options are those that appear in the arguments array, but are not present in opts.string
, opts.boolean
, opts.default
, or opts.alias
.
getopts(["-abc"], {
unknown: option => "a" === option
})
opts.stopEarly
A boolean property. If true, the operands array _
will be populated with all the arguments after the first non-option.
getopts(["-w9", "alpha", "--turbo", "beta"], {
stopEarly: true
})
This property is useful when implementing sub-commands in a CLI.
const { install, update, uninstall } = require("./commands")
const options = getopts(process.argv.slice(2), {
stopEarly: true
})
const [command, subargs] = options._
if (command === "install") {
install(subargs)
} else if (command === "update") {
update(subargs)
} else if (command === "uninstall") {
uninstall(subargs)
}
Benchmark Results
All tests run on a 2.4GHz Intel Core i7 CPU with 16 GB memory.
npm i -C bench && node bench
getopts × 1,315,998 ops/sec
minimist × 260,817 ops/sec
yargs × 33,520 ops/sec
mri × 386,495 ops/sec
License
Getopts is MIT licensed. See the LICENSE for details.