commandos

commandos

Command line parser, compatible with DOS style command

The name commandos is combination of command and DOS. commandos is a light-weighted command line parser which help to connect cli and Node.js application.

Table of contents

• Get Started
• API
• Examples
• Why commandos
• Honorable Dependents
• About
• References

Links

• CHANGE LOG
• Homepage

Get Started

const commandos = require('commandos');

// -- example 1 --
// Parse the command line of current process with default settings.
const options = commandos.parse();

// -- example 2 --
// Parse command line with default settings.
const cmdline = 'foo -v 1.0 --name JACK';
const options = commandos.parse(cmdline);

// -- example 3 --
// Parse command line with customised settings.
const cmdline = 'foo -v 1.0 --name JACK';
const settings = {
    explicit: true,
    options: [
        '--version -v',
        '--name -n' ]
};
const options = commandos.parse(cmdline, settings);

API

commandos.parse()

• Object commandos.parse()
• Object commandos.parse(string | string[] cmdline)
• Object commandos.parse(cmdline, Array optionDefinitions)
• Object commandos.parse(cmdline, Object settings)

To indicate how commandos.parse actions, parameter settings may contain following attributes:

• overwrite boolean DEFAULT true OPTIONAL
• caseSensitive boolean DEFAULT true OPTIONAL
• explicit boolean DEFAULT false OPTIONAL
• options Array OPTIONAL

A standard definition of an option (item of optionDefinitions) SHOULD be an object or a string. It may be an object made up of following attributes:

• name string
  Option's formal name which will be attribute name of the returned object.

• alias string | string[] OPTIONAL

• assignable boolean DEFAULT true OPTIONAL
  If option is assignable, part following the dash-prefixed option name in the command line will be regarded as value of the option if the part is not another dash-prefixed option name.

• caseSensitive boolean DEFAULT INHERIT OPTIONAL
  If caseSensitive is true, option version and Version will be regarded as two different options.

• multiple boolean DEFAULT false OPTIONAL
  If option is multiple, the parsed value will be an array.

• nullable boolean DEFAULT true OPTIONAL
  When we say some option is NOT nullable, we mean it SHOULD NOT appear in the command line without being followed by some value.

• overwrite boolean DEFAULT INHERIT OPTIONAL
  If overwrite set false, the option or its alias SHOULD NOT appear in the command line for more than one time.

• required boolean DEFAULT false OPTIONAL
  If option is required, it SHOULE appear in the command line at least once.

ATTENTION：Some of previous attributes are mutexes.
If option is multiple, it SHOULD NOT be a kind of switching value at the same time. That means the option is assignable and NOT nullable, attribute nullable, assignable and overwrite will be ignored.

It can also be a string according to private syntax looks like column definition in MySQL:

// * The option is named "version", or "v" in short. The first name is formal.
// * The option SHOULD be appended with some value.
// * The option SHOULD exist.
// * The name is case-insensitive, that means "Version" and "V" are also 
//   acceptable.
'--version -v NOT NULL REQUIRED NOT CASE_SENSITIVE'

// * The first word is regarded as formal name of the option.
// * Alias "v" and "edition" are also acceptable.
'version alias(v, edition)'

Examples

Read unit test code for examples:

• commandos.parse

Why commandos

There are already many packages help you to parse command line content, in which minimist and commander are probably most famous. However, sometimes minimist is too slim while commander is too heavy. That is why I wrote commandos.

Honorable Dependents

About

commandos = command + DOS

References

If commandos is not to your taste, maybe the following packages is considerable (in alphabetical order):

• commander
• getopts
• minimist
• nomnom
• optimist
• yargs

Changelog

[0.0.2] - Dec 22, 2017

• Assignment form like --name=value is supported.
• Paradoxical attributes in option definition will make exception throwed when commandos.parse() invoked.