@open-tech-world/es-cli-args

A strict CLI arguments parser.

Features

• Strict parsing (See parser rules below)

• Converts options to camelCase

• Supports multiple option types (Boolean, String, Number, Array, Object)

Installation

Using npm

npm install @open-tech-world/es-cli-args

Using Yarn

yarn add @open-tech-world/es-cli-args

Usage

import { parser } from '@open-tech-world/es-cli-args';

parser(args: string | string[]): IOutObj;

Examples

Input:

parser('-a');

Output:

{ "args": [], "opts": { "a": true } }

Input:

parser('rm -rf a.txt');

Output:

{
  "args": ["rm", "a.txt"],
  "opts": { "r": true, "f": true }
}

Input:

parser('npm publish --dry-run');

Output:

{
  "args": ["npm", "publish"],
  "opts": { "dryRun": true }
}

Input:

parser('git commit -a -m="New commit msg"'));

Output:

{
  "args": ["git", "commit"],
  "opts": { "a": true, "m": "New commit msg" }
}

Input:

parser('git merge --no-commit');

Output:

{
  "args": ["git", "merge"],
  "opts": { "commit": false }
}

Input:

$ node example.js -x=1 -x=2

Output:

{
  "args": [],
  "opts": { "x": [1, 2] }
}

Input:

$ node example.js -y=1,2

Output:

{
  "args": [],
  "opts": { "y": [1, 2] }
}

Input:

parser('git config --system user.email=[e-mail]');

Output:

{
  "args": ["git", "config", { "user": { "email": "[e-mail]" } }],
  "opts": { "system": true }
}

Input:

parser('git config --global --alias.ci=commit'));

Output:

{
  "args": ["git", "config"],
  "opts": { "global": true, "alias": { "ci": "commit" } }
}

Parser Rules

Terminology:

The arguments may contain Commands, Positional arguments and Options.

The Options can be classified into Short options and Long options.

Commands:

A command represents an action name. It can have sub-commands.

Eg: git commit npm install

In the above example commit & install are commands for the git & npm respectively.

Positional arguments:

The positional arguments are parameters to a command. The order is often important.

Eg: cp SOURCE DEST

In the above example, the SOURCE & DEST are positional arguments for cp

Options:

The Options or Flags are named parameters.

Denoted with either a hyphen - and a single-letter name or a double hyphen -- and a multiple-letter name.

Eg:

Short option: rm -r file.ext

Long option: rm --recursive file.ext

Input:

The parser accepts both String and Array of Strings as input.

Eg:

'rm -rf photo.jpg'

['tar', '-tvf', 'archive.tar']

Or probably from process.argv.slice(2).

Parsing:

• The arguments are separated by space character.

• There is no additional configuration to specify arguments type.

• The arguments types are auto inferred.

• The commands & sub-commands are included in the args array property of the output object.

• The positional arguments are also included in the args array property of the output object.

• The options are default converted into camelCase and included in the opts object of output object.

  $ npm publish --dry-run

  { "args": ["npm", "publish"], "opts": { "dryRun": true } }

• The default value for an option is boolean true.

• A value can be set for options using = character.

  $ git commit -a -m='New commit msg'

  {
    "args": ["git", "commit"],
    "opts": { "a": true, "m": "New commit msg" }
  }

  $ ssh example.com -p=3322

  {
    "args": ["ssh", "example.com"],
    "opts": { "p": 3322 }
  }

  $ tar -cf archive.tar foo bar --level=5

  {
    "args": ["tar", "archive.tar", "foo", "bar"],
    "opts": { "c": true, "f": true, "level": 5 }
  }

• The Options can contain Array values, use the ,(comma) character without space to create an array of values.

  $ node example.js -x=1,2

  { "args": [], "opts": { "x": [1, 2] } }

• The short options can grouped.

  $ tar -tvf archive.tar

  {
    "args": ["tar", "archive.tar"],
    "opts": { "t": true, "v": true, "f": true }
  }

• The grouped short options cannot be assigned a value.

  The following does not work

  $ git commit -am="Commit msg"

• Boolean Negation: The options can be boolean negated using --no- prefix.

  $ git commit --no-verify

  { "args": ["git", "commit"], "opts": { "verify": false } }

• Dot-Notation: The value of long options that contain .(Dot) character are converted into object.

  $ node example.js --user.email=[e-mail]

  { "args": [], "opts": { "user": { "email": "[e-mail]" } } }

• Output

  The parser returns an object containing all Commands & Positional arguments in an args array prop and all short & long options set in an object opts prop.

  {
    "args": [...],
    "opts": {...}
  }

Notes:

• There is no distinction while parsing sub-commands, all commands & sub-commands are included in the args prop of output object in the given order.

  parser('docker container create --name=ubuntu01 ubuntu');

  {
    "args": ["docker", "container", "create", "ubuntu"],
    "opts": { "name": "ubuntu01" }
  }

• Due to auto-inference of types, the values might be mismatched.

  The following example shows the color value returning as type number converted from hex value.

  $ node example.js --color=0xFFFF

  {
    "args": [],
    "opts": { "color": 65535 }
  }

  If you need the value as string, you can surround it with single or double quotes accordingly.

  $ node example.js --color='0xFFFF'

  {
    "args": [],
    "opts": { "color": "0xFFFF" }
  }

• Currently true or false in the arguments will be parsed as string, Eg: --foo=false => { foo: 'false' }

  The auto-infer boolean types feature can be implemented later based on the user requests.

References

Command Line Interface Guidelines

License

Copyright (c) 2021, Thanga Ganapathy (MIT License).