GetOptions
The JavaScript equivalent of getopts
. No frills, no bullshit; nothing but cold, hard option extraction.
Use this module if you
- Are happy validating and type-checking input yourself
- Don't mind writing your own documentation
- Prefer a hands-on approach without pointless array-fiddling
This lets you extract options so this...
$ program --log-path /var/log/stuff.txt generate all-files --verbose
... gets filtered down to this:
$ program generate all-files
... with everything neatly sorted into one little object:
let result = {
options: {
logPath: "/var/log/stuff.txt",
verbose: true
},
argv: [
"generate",
"all-files"
]
};
That's seriously all.
Example
getOpts(process.argv, {
"-v, --verbose": "",
"-l, --log-level": "[level]",
"-p, --log-path": "<path>",
"-s, --set-config": "<name> <value>",
"-f, --files": "<search-path> <variadic-file-list...>"
});
Left column:
Short and long forms of each defined option, separated by commas.
Right column:
Arguments each option takes, if any.
Note: There's no requirement to enclose each parameter's name with < > [ ] ( )
. These characters are just permitted for readability, and are ignored by the function when it runs. They're allowed because some authors might find them easier on the eyes than simple space-separation.
When omitted:
If you don't define any options, the function takes a "best guess" approach by absorbing anything with a dash in front of it. Specifically, the following assumptions are made:
- Anything beginning with at least one dash is an option name
- Options without arguments mean a boolean
true
- Option-reading stops at
--
- Anything caught between two options becomes the first option's value
Don't rely on this approach to give you foolproof results. Read about the caveats here.
Result
The value that's assigned to each corresponding .options
property is either:
- Boolean
true
if the option doesn't take any parameters (e.g., "--verbose": ""
) - A string holding the value of the option's only argument (e.g.,
"--log-path": "path"
) - An array if more than one parameter was specified. (e.g.,
"-s, --set-config": "name value"
)
Given the earlier example, the following line...
program --files /search/path 1.jpg 2.txt 3.gif --log-path /path/to/ subcommand param --verbose
... would yield:
let result = {
argv: ["subcommand", "param"],
options: {
files: ["/search/path", "1.jpg", "2.txt", "3.gif"],
logPath: "/path/to",
verbose: true
}
};
I'm sure you get it by now.
That's it?
Yeah, that's it. You want fancy subcommands? Just leverage the .argv
property of the returned object:
let subcommands = {
generate: function(whichFiles){
console.log("Let's generate... " + whichFiles);
}
};
subcommands[ result.argv[0] ].apply(null, result.argv.slice(1));
This would work too, if you're an eval
kinda guy:
function generate(whichFiles){ }
eval(result.argv[0]).apply(null, result.argv.slice(1));
Obviously you'd be checking if the function existed and all that jazz. But that's up to you.
Further reading
I've broken the more convoluted documentation into different files, in an effort to keep this readme file terse:
Reminders
Why?
Yeah, there's billions of CLI-handling modules on NPM. Among the most well-known and popular are Commander.JS and yargs. Since I'm a control freak, though, I prefer doing things my way. So I developed a solution that'd permit more idiosyncratic approaches than those offered by "mainstream" option modules.