Quickly scan for CLI flags and arguments
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bench
lib
test
.editorconfig
.gitignore
.travis.yml
license.md Minor improvements for codebase (#1) Jul 24, 2017
package.json 1.1.1 May 7, 2018
readme.md

readme.md

mri Build Status

Quickly scan for CLI flags and arguments

This is a fast and lightweight alternative to minimist and yargs-parser.

It only exists because I find that I usually don't need most of what minimist and yargs-parser have to offer. However, mri is similar enough that it might function as a "drop-in replacement" for you, too!

See Comparisons for more info.

Usage

Firstly, install the package:

npm install --save mri

Then start using it:

$ demo-cli --foo --bar=baz -mtv -- hello world
const mri = require('mri');

const args = process.argv.slice(2);

mri(args);
//=> { _: ['hello', 'world'], foo:true, bar:'baz', m:true, t:true, v:true }

mri(args, { boolean:['bar'] });
//=> { _: ['baz', 'hello', 'world'], foo:true, bar:true, m:true, t:true, v:true }

mri(args, {
  alias: {
    b: 'bar',
    foo: ['f', 'fuz']
  }
});
//=> { _: ['hello', 'world'], foo:true, f:true, fuz:true, b:'baz', bar:'baz', m:true, t:true, v:true }

API

mri(args, options)

args

Type: array
Default: []

An array of arguments to parse. For CLI usage, send process.argv.slice(2). See process.argv for info.

options.alias

Type: object
Default: {}

An object of keys whose values are a string or array of aliases. These will be added to the parsed output with matching values.

options.boolean

Type: array|string
Default: []

A single key (or array of keys) that should be parsed as Booleans.

options.default

Type: object
Default: {}

An key:value object of defaults. If a default is provided for a key, its type (typeof) will be used to cast parsed arguments.

mri(['--foo', 'bar']);
//=> { _:[], foo:'bar' }

mri(['--foo', 'bar'], {
  default:{ foo:true, baz:'hello', bat:42 }
});
//=> { _:['bar'], foo:true, baz:'hello', bat:42 }

Note: Because --foo has a default of true, its output is cast to a boolean. This means that foo:true, which makes 'bar' an extra argument (_ key).

options.string

Type: array|string
Default: []

A single key (or array of keys) that should be parsed as Strings.

options.unknown

Type: function
Default: undefined

Callback that is run when a parsed flag has not been defined as a known key or alias. Its only parameter is the unknown flag itself; eg --foobar or -f.

Once an unknown flag is encountered, parsing will terminate, regardless of your return value.

Note: mri only checks for unknown flags if options.unknown and options.alias are populated. Otherwise, everything will be accepted.

Comparisons

minimist

  • mri is 2.5x faster (see benchmarks)
  • Numerical values are cast as Numbers when possible
    • A key (and its aliases) will always honor opts.boolean or opts.string
  • Short flag groups are treated as Booleans by default:
    minimist(['-abc', 'hello']);
    //=> { _:[], a:'', b:'', c:'hello' }
    
    mri(['-abc', 'hello']);
    //=> { _:[], a:true, b:true, c:'hello' }
  • The opts.unknown behaves differently:
    • Unlike minimist, mri will not continue continue parsing after encountering an unknown flag
  • Missing options:
    • opts.stopEarly
    • opts['--']
  • Ignores newlines (\n) within args (see test)
  • Ignores slashBreaks within args (see test)
  • Ignores dot-nested flags (see test)

yargs-parser

  • mri is 20x faster (see benchmarks)
  • Numerical values are cast as Numbers when possible
    • A key (and its aliases) will always honor opts.boolean or opts.string
  • Missing options:
    • opts.array
    • opts.config
    • opts.coerce
    • opts.count
    • opts.envPrefix
    • opts.narg
    • opts.normalize
    • opts.configuration
    • opts.number
    • opts['--']
  • Missing parser.detailed() method
  • No additional configuration object
  • Added options.unknown feature

Benchmarks

mri
  --> 329,310 ops/sec ±0.27% (88 runs sampled)
yargs
  --> 16,100 ops/sec ±0.57% (91 runs sampled)
minimist
  --> 129,670 ops/sec ±0.72% (93 runs sampled)

License

MIT © Luke Edwards