parsec

ES6 generator-based CLI options parser.

ES6 generator-based CLI options parser.

Install | Synopsis | Usage | Example | Development | About

Install

npm install parsec

Synopsis

Parsec is a hand-crafted CLI options parser using ES6 generators in ~150 LOC.

Parsec.parse(process.argv) // -T850 
  .options(["T", "terminator"], { default: 800 })
  .options("model", { default: 101 })
  .options("name", { default: "Schwa" })
{
  "T": "850",
  "terminator": "850",
  "model": "101",
  "m": "101",
  "name": "Schwa",
  "n": "Schwa"
}

Usage

Parsec automatically slices arguments starting from index 2, but you can specify the sliceIndex via the second argument to parse.

Parsec.parse(argv[, {
  sliceIndex = 2,
  operandsKey = "_",
  noFlags = true
}])
  .options("option string")
  .options([aliases], { default })
  ...
 

Parsec uses the first letter of an option string as an alias:

Parsec.parse(["-tla"], { sliceIndex: 0 })
  .options("three")
  .options("letter")
  .options("abbreviation")
{
  "t": true,
  "l": true,
  "a": true,
  "three": true,
  "letter": true,
  "abbreviation": true
}

Pass an array of aliases, or specify default values via { default: value }

Parsec.parse(["-G"], { sliceIndex: 0 })
  .options(["G", "g", "great"])
  .options(["r", "R"], { default: 8 })
{
  "G":true,
  "g":true,
  "great":true,
  "r":8,
  "R":8
}

You can negate options using a --no- prefix before an option.

Parsec.parse(["--no-woman-no-cry", "--no-wonder=false"],
  { sliceIndex: 0 })
{
  "woman-no-cry": false,
  "wonder": true
}

The only one method you will probably deal with.

  • operandsKey = "_"
  • sliceIndex = 2
  • noFlags = true

Returns an iterator that yields objects of the form { prev, curr, next } for each item in a list.

Maps CLI arguments to custom Token objects.

  • Short Options
{ isShort, tokens }
  • Long Options
{ isLong, key, value, token }
  • Operands
{ token, isBare }

Token sub-iterator for short options.

Token iterator for options:

{ curr, next, value }

Iterator for entries:

{ key, value }

Use a different key name for the operands list.

Set to false to opt out.

Parsec.parse(["--no-love=false", "--no-war", "--no-no", "ok"],
  { sliceIndex: 0 })
  {
    "love": true,
    "war": false,
    "no-no": "ok"
  }

Example

If your app receives the arguments ./app --foo bar -t now -xzy:

Parsec.parse(process.argv)

will return the following object:

{
  "foo": "bar",
  "t": "now",
  "x": true,
  "z": true,
  "y": true
}

This object also has an options method that you can use to customize the parsed options:

Parsec.parse(process.argv)
  .options("foo", { default: "hoge" })
  .options("time", { default: 24 })
  .options("xoxo")
  .options("yoyo")
  .options("zorg")

returns the following object:

{
   "f": "bar",
   "foo": "bar",
   "t": "now",
   "time": "now",
   "x": true,
   "xoxo": true,
   "z": true,
   "zorg": true,
   "y": true,
   "yoyo": true
 }

Note the first letter of the option string is used as the short option flag by default. You can opt out of this by specifying an array with the mappings you prefer:

.options(["foo", "F"])

About

Why another options CLI parser?. There are several options out there. There is yargs and commander (_> 1000 LOC_) which are fun to use, but end up doing too much.

There is also minimist and nopt, which are leaner and offer a more limited feature set, but I wasn't comfortable with their traditional design and large code base. I also found both slightly too verbose for my taste.

I decided to write my own solution (though it wasn't the first time) using ES6.

The end result is ~150 LOC and a readable code base.

Development

 
git clone https://github.com/bucaran/parsec
cd parsec
npm install
npm run build

Roadmap ✈

  • Type support.
  • Invalid option checks.

License

MIT © Jorge Bucaran