parsec

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.

Syntax

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
}

API

Parsec.parse(args, opts)

The only one method you will probably deal with.

opts

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

Parsec.prototype.tuples

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

Parsec.prototype.map

Maps CLI arguments to custom Token objects.

• Short Options

{ isShort, tokens }

• Long Options

{ isLong, key, value, token }

• Operands

{ token, isBare }

Parsec.prototype.shorts

Token sub-iterator for short options.

Parsec.prototype.tokens

Token iterator for options:

{ curr, next, value }

Parsec.prototype.entries

Iterator for entries:

{ key, value }

Properties

operandsKey = "_"

Use a different key name for the operands list.

noFlags = true

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 et al :heart: