- GitHub: axyjs/axy-cli-opts
- NPM: axy-cli-opts
- Author: Oleg Grigoriev
- LICENSE: MIT
Install:
npm install --save axy-cli-opts
Use:
var opts = require("axy-cli-opts");
var args = opts.parse();
The library work with follow format of command line arguments.
For example:
node index.js --opt=value -x2 -f arg1 arg2
All components that begin with -
is short options.
That begin with --
is long options.
All others is arguments.
--opt=value
.
Here opt
is the option name, value
is the option value.
--opt
it is "flag".
Value of this option is TRUE
.
--opt=
it is not flag.
Value of this options is empty string.
Short options consist of a signle character. The value immediately follows the option name (without spaces).
-qwer
is option q
with value wer
.
Analogue of --q=wer
.
-q
is flag.
mysqldump --add-locks --compress --ignore-table=log --ignore-table=sessions database
In the example the option --ignore-table
was specified multiple times.
The values of such options are stored into an array.
The library provides two methods: parse()
and help()
.
parse()
returns values of options.
If the argument format
is not specified then the library loads all options without cheking
without distinguishing between short and long and etc.
console.log(opts.parse());
Run:
node index.js -a -b2 --opt=1 --opt=2 arg1 arg2
Out:
{
args: [ // list of arguments
'arg1',
'arg2'
],
options: { // values of options
a: true, // -a - flag
b: '2', // -b2
opt: ['1', '2'] // multiple option
}
};
If the first argument argv
is not specified used process.argv.slice(2)
.
argv
taken the array of cli components.
opts.parse(["-a", "-b2", "--opt=1", "arg"]);
If the argument format
is specified then options are checked and loaded in accordance with it.
It is dictionary: the long option name => the option format. The options format contains the follows fields.
The short alias for the long name. Short options can not exist by themselves. Just as an alias.
var format = {
one: {
short: "o"
},
two: {
short: "t"
}
};
opts.parse(["--one=1", "-t2"], format); // {args: [], options: {one: "1", two: "2"}}
opts.parse(["--one=1", "-x3"], format); // Error: Unknown option '-x'
Indicates that the option is a flag.
var format = {
one: {
short: "o",
flag: true
},
two: {
short: "t"
}
};
opts.parse(["-o", "-t2"], format); // {args: [], options: {one: true, two: '2'}}
opts.parse(["-o1", "-t2"], format); // Error: Option '--one' is flag
opts.parse(["-o", "-t"], format); // Error: Option '--two' is not flag
Allows the option marked as flag also take other values.
Type validation.
Defines three types: string
(by default), int
and id
.
int
is an integer, id
is a positive integer > 0.
var format = {
id: {
type: "id"
}
};
opts.parse(["--id=-3"], format); // Option '--id' must be a positive integer
The values cast to number type (in other cases it will be a string).
Allows multiple options.
var format = {
one: {
short: "o"
},
two: {
short: "t",
many: true
}
};
opts.parse(["-o1", "-t2", "--two=3", "-t4"], format); // {args: [], options: {one: '1', two: ['2', '3', '4']}}
opts.parse(["-o1", "-t2"], format); // {args: [], options: {one: '1', two: ['2']}}
opts.parse(["-o1", "-o2", "-t3"], format); // Error: Duplicate option '--one'
Each value of many
-option will passes all the checks in other format fields.
parse()
returns all options that specified in the format.
If any option is not specified, then used defaults
field.
If this field is not specified, it option is required.
var format = {
one: {
},
two: {
defaults: "value"
}
};
opts.parse(["--one=1"], format); // {args: [], options: {one: '1', two: 'value'}}
opts.parse(["--two=2"], format); // Error: Required option '--one'
For many
options:
If defaults
is scalar and the option is not specified used an array [defaults]
for result.
If defaults
is scalar and the option is specified then defaults
is erased.
If defaults
is array then specified values will be added to this array.
var format = {
one: {
many: true,
defaults: 1
},
two: {
many: true,
defaults: 2
},
three: {
many: true,
type: "id",
defaults: [3, 4]
}
};
var args = ["--two=5", "--two=6", "--three=7", "--three=8"];
console.log(opts.parse(args, format));
/* Result:
{
args: [],
options: {
one: [1],
two: ['5', '6'],
three: [3, 4, '7', '8'],
}
}
*/
This function calls after other validations (type
and flag
).
The result of this function uses as option value.
The function can act as a validator - just throws an exception.
The arguments list of the filter:
value
- the value from CLI arguments listname
- the option namecurrent
- the current value of the option (formany
-options could contains an array of previous options)
The filter called in the context of the format array of this option.
See help()
method.
Any other values may be used in the filter
.
Returns the help information about the options format.
var format = {
version: {
short: "v",
flag: true,
description: "print version",
},
'icu-data-dir': {
description: "set ICU data load path to dir\n(overrides NODE_ICU_DATA)",
descriptionVal: "dir"
},
'enable-ssl-2': {
flag: true,
description: "enable ssl2"
},
'help': {
short: "h",
flag: true,
}
};
console.log(opts.help(format));
Output:
--enable-ssl-2 enable ssl2
-h, --help
--icu-data-dir=dir set ICU data load path to dir
(overrides NODE_ICU_DATA)
-v, --version print version
var opts = require("axy-cli-opts");
var format = {
// ...
};
try {
var args = opts.parse(null, format);
} catch (e) {
console.log("Error: " + e.message);
console.log("Format: ./script.js <options> argument");
console.log("");
console.log(opts.help(format));
process.exit(1);
}