Gitlab NPM Twitter
Kado
High Quality JavaScript Libraries

GetOpt

Introduced in 4.0.0

Stability: 2 - Stable

const GetOpt = require('kado/lib/GetOpt')

The GetOpt library implements the POSIX getopt() function, providing a functional interface for option parsing.

Class: GetOpt

GetOpt is a general-purpose command line parser that follows the POSIX guidelines for command-line utilities. Using these guidelines encourages common conventions among applications, including use of:

This implementation mirrors the Solaris getopt() implementation and supports long option names (e.g., --recurse), potentially with values specified using = (e.g., --file=/path/to/file).

Unlike other option parsers available for Node.js, the POSIX getopt() interface supports using the same option multiple times (e.g., -vvv, commonly used to indicate level of verbosity).

For further reference on the relevant POSIX standards, see the following:

The Utility Syntax Guidelines are described here:

static GetOpt.getInstance(argv, optstring, optind)

GetOpt.constructor(argv, optstring, optind)

Instantiates a new object for parsing the specified arguments using the specified option string. This interface is closest to the traditional getopt() C function. Callers first instantiate a GetOpt class and then invoke the getopt() method to iterate the options as they would in C, although this interface allows the same option to be specified multiple times. The optional third argument to the constructor optind is the number of arguments from argv to skip. By default optind is set to 2, so the first two arguments in argv are ignored, since they generally denote the path to the node executable and the script being run.

Format of optstring

The option string consists of an optional leading : (see below) followed by a sequence of option-specifiers. Each option-specifier consists of a single character denoting the short option name, optionally followed by a colon if the option takes an argument and/or a sequence of strings in parentheses representing long-option aliases for the option name.

Example option strings:

':r'            Command takes one option, with no args: -r
':ra'           Command takes two options, with no args: -r and -a
':raf:'         Command takes two options, with no args: -r and -a
                and a single option that takes an arg: -f
':f:(file)'     Command takes a single option with an argument: -f
                -f can also be specified as --file

The presence of a leading colon in the option string determines the behavior when an argument is not specified for an option which takes an argument. See GetOpt.getopt() below. Additionally, if no colon is specified, then error messages are printed to stderr when invalid options, options with missing arguments, or options with unexpected arguments are encountered.

GetOpt.parseOptionString(optstring)

Parse the option string and update the following internal vars:

GetOpt.buildOptionString(argv)

This method, usually called internally via omitting an optstring in the constructor, allows for quick usage without a static optstring. This allows for simplified usage slightly more like "minimist" or others.

GetOpt.optind()

Returns the next argv-argument to be parsed. When options are specified as separate argv arguments, this value is incremented with each option parsed. When multiple options are specified in the same argv-argument, the returned value is unspecified. This matches the variable "OPTIND" from the POSIX standard, but is read-only. (If you want to reset OPTIND, you must create a new GetOpt instance.) This is most useful after parsing has finished to examine the non-option arguments.

This value starts at 2 as described under Departures from POSIX below.

GetOpt.getopt()

This function scans argv starting at the current value of optind and returns an object describing the next argument based on the following cases:

GetOpt.opts()


Departures from POSIX