Skip to content

Latest commit

 

History

History
159 lines (114 loc) · 4.77 KB

readme.md

File metadata and controls

159 lines (114 loc) · 4.77 KB
Raw

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.

Install

$ npm install --save mri

Usage

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

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

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

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

mri(argv, {
  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)

Return: Object

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 Strings or Array<String> 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, making '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 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 40x 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

# Node v10.13.0

minimist      x   324,469 ops/sec ±1.20% (96 runs sampled)
mri           x 1,611,167 ops/sec ±0.22% (96 runs sampled)
nopt          x   920,029 ops/sec ±1.13% (97 runs sampled)
yargs-parser  x    39,542 ops/sec ±1.14% (95 runs sampled)

License

MIT © Luke Edwards