commandos

commandos

Command line parser, compatible with DOS style command

LANGUAGES / 简体中文

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
• Go Advanced
  • ODL, Option Definition Language
  • Take Non-option Argument As Option Value
• 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 cmd = commandos.parse();

// -- example 2 --
// Parse command line with default settings.
const cmdline = 'foo -v 1.0 --name JACK';
const cmd = commandos.parse(cmdline);
// RETURN { v, name, $: [] };

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

See API: commandos.parse() for more powerful settings you may needed.

Generally Returned

Normally, commandos.parse() will return an object with properties of the same names as either the dash (- or --) prefixed option names in cmdline, or the names defined in settings.options (see the example below). Besides, the returned object will always has a array-typed property named $ containing other pieces in cmdline but not belonging to any options.

const cmdline = 'foo -v 1.0 --name JACK bar quz';
const options = [
    '--version -v',
    '--name -n' ];
const settings = { options };
const cmd = commandos.parse(cmdline, settings);
// RETURN { version, name, $: ['bar', 'quz'] }

Exceptions

In following cases, commandos.parse() will meet an exception:

• If cmdline contains option not declared in settings.options while settings.explicit set true at the same time.
• If incomprehensible pieces found in cmdline. E.g, --no-foo=bar is incomprehensible because a switching option should not be assigned with any literal value.
• If cmdline contains option violating the definition in settings and settings.options.

If settings.catcher exists, it will be invoked with the exception (an Error instance) as the only argument. Otherwise, the exception will be thrown directly:

let catcher = (ex) => { 
    console.warn(ex.message);
};
// The exception will be catched and passed into *catcher*.
commandos.parse('foo --no-foo=bar', { catcher });

Options Group

If the cmdline may be in multiple forms, we can run commandos.parse() more than one time to find out the options it carrying. However, using settings.groups is a more graceful way to achieve the same purpose.

// Option groups.
const settings = {
    explicit: true,
    groups: [
        [ '--version -v' ],
        [ '--name -n', '--gender -g' ]
    ]
};
commandos.parse('foo -v 1.0', settings);
// RETURN { version, $ }

commandos.parse('foo -n JACK -g male', settings);
// RETURN { name, gender, $ }

ATTENTIONS: If settings.explicit is not set true, you'd better declare options with keyword 'REQUIRED' to achieve expected result. The following is an anti-pattern example:

// -- ANTI PATTERN --
// Option groups.
const settings = {
    explicit: false,
    groups: [
        [ '--version -v' ],
        [ '--name -n', '--gender -g' ]
    ]
};
commandos.parse('foo -n JACK -g male', settings);
// RETURN { $ }
// The first option group matched, becuase it does NOT require any options.

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
• ignoreInvalidArgument boolean DEFAULT false OPTIONAL
• options Array OPTIONAL
• groups Array OPTIONAL

A standard definition of an option (item of array optionDefinitions or settings.options) 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
  Alias of option may be used in cmdline.

• assignable boolean DEFAULT true OPTIONAL
  If option is assignable, part following the dash-prefixed option name in cmdline 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.

• nonOption number | string | RegExp | Function OPTIONAL
  If named option not found, the matching non-option argument(s) will be taken as the value of the option. See Take Non-option Argument As Option Value for details.

• 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. For convenience, it is hereinafter referred to as ODL(Option Definition Language).

Go Advanced

ODL, Option Definition Language

ODL is a tiny language used to define option. It is an easy alternative for option define object. E.g.

// * 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'

// * If named option not offered, the first non-argument will be used as value of option "action".
'--action [0:~* (start|stop|restart)]'

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

Keywords in ODL is case-insensitive:

• []
• ALIAS
• ASSIGNABLE
• CASE_SENSITIVE
• CASE_INSENSITIVE
• COMMENT
• DEFAULT
• MULTIPLE
• NULLALBE
• OVERWRITE
• REQUIRED

Take Non-option Argument As Option Value

To make command line more flexiable, commandos.parse allows, by setting nonOption in definition of an option, to take non-option argument(s) as option value while named option not found. Property nonOption is overloaded with following types:

• nonOption number
• nonOption string
• nonOption RegExp
• nonOption Function(value, index)

In ODL, delimiters [] is used to define the nonOption property:

// * Fixed position of non-option argument.
// * Fixed value.
'--help [0:=* help] NOT ASSIGNABLE'

// * Any position.
// * Use regular expression (case-insensitive) to validate the arguments.
'--action [*:~* (start|stop|restart)]'

// * Position range.
'--name [>1]'

Examples

Read unit test code for examples:

• commandos.parse: basic usage
• commandos.parse: global settings
• commandos.parse: option settings
• commandos.parse: take non-option argument as option value
• commandos.parse: option groups

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.1.3] - Jan 2, 2018

Fixed

Fixed the bug taht Error None of the option groups matched throwed if no named options found even if there is at least one option group requiring no named options.