a advanced cli arguments parser
npm install advanced-cli
A Cli parser with advanced arguments/command, very fast execution (more than mri).
The parser is inspired by python argsparser, the output is look like docker or cargo(rust lang) cli.
You can add arguments, command, command arguments, efficiency errors, very fast, chained alias ( ex: -lah ), inline arguments (ex: --foo=bar,boo,baz)
``bash`
yarn add advanced-cli
`js
const CliParser = require("advanced-cli");
const options = {
version: "1.0.1",
footer:
"To get more help with docker, check out our guides at https://docs.docker.com/go/guides/",
};
/*
initialize parser
*/
const parser = new CliParser(
"docker",
"A self-sufficient runtime for containers",
options
);
/*
add global arguments ( is can be used with all commands like --help)
flag config need a number after it like: "--config 42"
*/
parser.addArgument("config", {
description: "Location of client config files",
params: [{ type: Number }],
});
/*
flag debug need no arguments, so ou can use like --debug or -D
*/
parser.addArgument("debug", {
alias: "D",
description: "Enable debug mode",
});
/*
add command, the command need to be the first params in argv
the run command if is set, the call function is called, you put all your thing in
*/
parser.addCommand("run", "Run a command in a new container", {
call(context) {
if (context.flags.debug) {
console.log("rou are in debug mode");
}
// do something
},
});
/*
the command search, the command have 2 arguments (only availabe in search command )local
*/
parser.addCommand("search", "Search the Docker Hub for images", {
arguments: {
/*
first flags:
command have a alias so is can be set like --local or -l
the command need 1 arguments with type , but if not have value, the default is /home/local
ex: , --local otherparams, -l, -l path all work
*/
local: {
alias: "l",
params: [
{
type: String,
default: "/home/local",
},
],
},
/*
second flags: group
command have not alias so you os is can only set like
the command need 2 arguments with type , and boolean
type string need to be validate by a function, first fucntions arguments is the arugmments string,
if you dont throw a error, the arguments is valid, and is set by the return value
the second arguments need boolean, if is not exist is set to by default--group
ex:
BAD:
dont work need first string arguments--group other
the other not match in validator--group dev dev
have a invalid boolean
OK:
*/
group: {
params: [
{
type: String,
validator(value) {
const choices = ["root", "user", "dev"];
if (choices.includes(value)) {
return value;
}
throw new Error("invalid group");
},
},
{
type: Boolean,
default: false,
},
],
},
},
/*
if the command search is set
we call this function at the end of parser with context data (see #context)
*/
call(context) {
if (context.flags.debug) {
console.log("rou are in debug mode");
}
...
},
});
const argv = process.argv.slice(2)
if (!parser.parse(argv)) {
parser.printError()
}
`
if you dont want to use call attribute in command or flags, you can do this`js
const parser = new CliParser(
"docker",
"A self-sufficient runtime for containers",
options
);
parser.addArgument("config", {
description: "Location of client config files",
params: [{ type: Number }, {type:string}, {type:boolean}, {type:string, default: "all"}],
});
if (parser.parse(['hello', '--config', '6', 'user', 'true']) {
const {flags, anyArgs, cmd} = parser.context
/*
flags output:
{config: [6, 'user', true, 'all']}
anyArgs represant others arguments
output anyArgs:
['hello']
*/
} else {
parser.printError()
}
`
various options is available
`ts
/ Parser /
{
info: string, // your information for use your programm
footer: string, // display a footer message when usage is call
version: string, // you version of your app
stopFlags: "--" | ";" | undefined // stop parsing flag , default null
inline: false, // add posibility the flags are format like this --foo=bar,booz,bo
// inline mdoe have a big execution cost ( cause need to split )
}
/ Arguments /
{
description: string, // a description for your arguments
alias: string, // a alais
params: [ #Params ], // a list with object Params
call: Function // function, get the context,do the thing , and quit
}
/ Params /
{
type: Number | Boolean | String, // the arguments type, is convert to it, is required!
default?: boolean | number | string, // if is not have arguments,it get the default value
validator?: (value: string, params: any[]) // pass the value in funciton, and do complex validation on it
}
/ Command /
{
arguments: {
/*
object with key is ne name of your falgs
and argument is the options for your flags
*/
name: {
#Arguments
},
...
}
call?: (context) // function with cli context (flags,anyargs, cmd ..ect )
}
`
In parser you have p.usage() or p.commandUsage('search') provide output like bellow, with options defaultArg: true the parser add --help/-h arguments and if is set, is print usage or commandUsage
`js
/*
with example above the usage output look this
*/
Usage: docker [OPTIONS] COMMAND
A self-sufficient runtime for containers
Options:
-h, --help Prints help information
-v, --version Print version info and exit
--config
-D, --debug Enable debug mode
Commands:
run Run a command in a new container
search Search the Docker Hub for images
To get more help with docker, check out our guides at https://docs.docker.com/go/guides/
/*
command usage
*/
Usage: docker search [OPTIONS]
Search the Docker Hub for images
Global options:
-h, --help Prints help information
-v, --version Print version info and exit
--config
-D, --debug Enable debug mode
Command options:
-l, --local
--group
To get more help with docker, check out our guides at https://docs.docker.com/go/guides/
When a flags/command/arguments is invalid the output generate is very helpful.
`
error: Invalid arugments for flag 'config', need 1 arguments.
docker search --config
^
--------------------------|
error: Invalid arugments for flag 'config', need a valid number.
docker search --config tre
^^^
--------------------------|
error: Invalid arugments for flag 'sh', need a valid boolean, choice are 'true' or 'false'
docker search --sh 44
^^
--------------------------|
error: no such command: 'seade'
docker seade --config r
^^^^^
--------------------------|
error: Invalid arugments for flag 'group', invalid group
docker search --group hupio
^^^^^
--------------------------|
error: Found argument '--prop' which wasn't expected, or isn't valid in this context.
docker search --prop
~~^^^^
--------------------------|
// With inline mode
error: Invalid arugments for flag 'group', invalid group
docker search --group=tu,54
~~~~~~~~^^~~~
--------------------------|
error: Invalid arugments for flag 'group', need a valid boolean, choice are 'true' or 'false'
docker search --group=tu,54
~~~~~~~~~~~^^
`
Benchmarks script made by mri, run various cli/argsparser
` nodejs v14.18.0
/---------------
/ inline mode disabe
/---------------
nopt: 2.163ms
yargs-parser: 4.11ms
minimist: 0.722ms
mri: 1.827ms
advanced-cli: 2.469ms
Benchmark: small: [-b, --bool, --no-meep, --multi=baz]
advanced-cli x 1,009,619 ops/sec ±0.62% (94 runs sampled)
mri x 802,334 ops/sec ±0.46% (91 runs sampled)
nopt x 539,295 ops/sec ±0.43% (90 runs sampled)
minimist x 214,159 ops/sec ±2.52% (88 runs sampled)
yargs-parser x 24,081 ops/sec ±1.06% (89 runs sampled)
Benchmark: big: [-b, --bool, --no-meep, --multi=baz, -a, hellow, world, --pop, youpiii, --soulapa, gooogg, poeppd, ofoooo, --poloiepdi, doouicll, -e, -t, i, -i]
advanced-cli x 387,050 ops/sec ±0.76% (87 runs sampled)
mri x 310,990 ops/sec ±0.31% (90 runs sampled)
nopt x 258,311 ops/sec ±0.60% (89 runs sampled)
minimist x 88,641 ops/sec ±0.37% (92 runs sampled)
yargs-parser x 8,319 ops/sec ±1.56% (85 runs sampled)
/---------------
/ inline mode enable
/---------------
Benchmark: small: [-b, --bool, --no-meep, --multi=baz]
mri x 833,752 ops/sec ±0.26% (93 runs sampled)
advanced-cli x 699,021 ops/sec ±0.25% (94 runs sampled)
nopt x 540,303 ops/sec ±0.25% (93 runs sampled)
minimist x 213,273 ops/sec ±2.39% (89 runs sampled)
yargs-parser x 23,048 ops/sec ±2.55% (86 runs sampled)
Benchmark: big: [-b, --bool, --no-meep, --multi=baz, -a, hellow, world, --pop, youpiii, --soulapa, gooogg, poeppd, ofoooo, --poloiepdi, doouicll, -e, -t, i, -i]
mri x 315,247 ops/sec ±0.30% (95 runs sampled)
advanced-cli x 300,114 ops/sec ±0.39% (92 runs sampled)
nopt x 260,410 ops/sec ±0.29% (92 runs sampled)
minimist x 89,358 ops/sec ±0.38% (92 runs sampled)
yargs-parser x 8,284 ops/sec ±1.08% (89 runs sampled)
``