WizTools.org Cli Parse
Intro
A Node library to parse commands of structure:
cmd [global-options] [command] [command-options] [arguments]
Can be used for simple argument parsing too:
cmd [options] [arguments]
Was primarily written after getting disillusioned by existing libraries like commander.js. This aims to be the cli parsing library that Node deserves.
Install
npm install wiz-cliparse --save
Use
var Program = ; // Defining the program and its global options:var prg = 'mycli' 'short description.' // required. '[global-options] [command] [command-options] [arguments]' // usage. for rendering help o/p. optional. 'long description.'; // optional.prg; // description. // Adding commands and their options:var cmdA = prg; // optional.cmdA;var cmdX = prg; // Parsing: // 1. Success:var res = prg;console; // prints `true`console; // prints `abc`console; // prints `true`console; // prints `true`console; // prints `['arg1', 'arg2']` // 2. Failures:// Will throw error:prg; // Unrecognized global option: x.prg; // Unrecognized command: def.prg; // Unrecognized option frugal for command abc.
Parse result object
Has following elements:
cmd
(String): The command that was called.gopts
(Set): Global options. Has both the short and long options.opts
(Set): Command options. Has both the short and long options.goptArg
(Map): A map of arguments to global options.optArg
(Map): A map of arguments to command options.args
(Array): List of arguments.
Synchronous parse with callback
For developers who don't like using try/catch
:
prg;
Parsing cli arguments
var res = prg;
For callback:
prg;
Combining short options together
It is possible to combine multiple short options as one. For example, instead of giving -a -b
, it can be given as -ab
.
Options conf
Options can have configurations:
prg;
Both global and command option can have these configurations:
isMandatory
: Is a mandatory option. Check will happen in all cases except one: whenhelp
option / command is passed. We wanthelp
to be accessible even when mandatory option is not provided.hasArg
: Option has argument.defaultArg
: Default value to assign when an when an option supporting argument is not passed argument.multiArg
: Support multiple arguments like-H value1 -H value2
.noMandatoryOptCheck
: When few options like-v
(version) /-h
(help) is passed, mandatory option check should not be performed. Use along with similar options.
defaultArg
and multiArg
will be ignored if hasArg
is not set to true
.
Retrieving argument value of an option
For global option:
ifresgopts var arg = resgoptArg; // or: arg = resgoptArg;
For command option:
ifresopts var arg = resoptArg; // or: arg = resoptArg;
Note, both the retrievals above will return an array if the option multiArg
is set to true
. Otherwise, it returns the last string that is set.
help
Configure and display To add help option -h, --help
:
prg;
To add help command:
prg;
To add both help option and command:
prg;
All the three above commands accept a optional description
string to override the default short description.
help
Display // ...prg;// ...var res = prg; // From option:ifresgopts || rescmd === 'help' prg; // or: prg; // if you want to print help in STDERR. process;
This prints context sensitive help also. For example, cmd help mycmd
, will print detailed help about mycmd
. The order of printing help:
- Short description.
- Usage (if available).
- Long description (if available).
- Options (if available).