rminimist

Parse argument options

> args = ['--debug', '-o', 'doc.html', 'doc.md']
> rminimist(args, { alias: { o: 'output' } })
{ _: ['doc.md'], debug: true, output: 'doc.html' }

This works exactly like minimist, with a few exceptions (see difference with minimist).

Usage

npm install --save rminimist

var argv = require('rminimist')(process.argv.slice(2))

API

rminimist

rminimist(args, [options], [previous])

Return an argument object argv populated with the array arguments from args.

argv._ contains all the arguments that didn't have an option associated with them.

Any arguments after -- will not be parsed and will end up in argv._.

If previous is given, results will be amended into it.

Options can be:

• opts.string - an array of strings argument names to always treat as strings
• opts.boolean - an array of strings to always treat as booleans.
• opts.array - an array of strings to treat as arrays. (only in rminimist)
• opts.number - an array of strings to treat as numbers. (only in rminimist)
• opts.alias - an object mapping string names to strings or arrays of string argument names to use as aliases
• opts.default - an object mapping string argument names to default values
• opts.stopEarly - when true, populate argv._ with everything after the first non-option
• opts['--'] - when true, populate argv._ with everything before the -- and argv['--'] with everything after the --.

See minimist for more details and examples.

Amending

You can add to a previous rminimist() result by passing it as the third parameter.

> result = rminimist(['-f']);
> result = rminimist(['-d'], {}, result);
> result
{ _: [], f: true, d: true }

Difference with minimist

rminimist tries to be less "smart" than minimist. While minimist is often usable with minimal options, rminimist prefers you to be explicit.

• Aliases are not duplicated. They will always resolve to the canonical version.

  minimist(['-f', 'document.txt'], { alias: { f: 'file' } })
  
  // minimist
  { _: [], f: 'document.txt', file: 'document.txt' }
  
  // rminimist
  { _: [], file: 'document.txt' }

• The syntax -n4 (short flag + number) is not supported. This improves compatibility with number flags (eg, -1).

  minimist(['-n4'])
  
  // minimist
  { _: [], n: 4 }
  
  // rminimist
  { '4': true, _: [], n: true }

• Booleans don't default to false. They're simply not defined if not present.

  minimist(['--debug'], { boolean: [ 'debug', 'verbose' ] })
  
  // minimist
  { _: [], debug: true, verbose: false }
  
  // rminimist
  { _: [], debug: true }

• Values are overridden, not appended as an array. Use the array option to explicitly enable the array behavior.

  minimist(['--watch=lib', '--watch=test'])
  
  // minimist
  { _: [], watch: ['lib', 'test'] }
  
  // rminimist
  { _: [], watch: 'test' }

• A new option array is introduced to make values into an array.

  minimist(['--watch=lib', '--watch=test'], { array: ['watch'] })
  
  // rminimist
  { _: [], watch: ['lib', 'test'] }

• Order is always preserved (except for numeric keys).

  minimist(['-a', '--file=doc.txt'], { default: { file: 'default.txt' } })
  
  // minimist
  { _: [], file: 'doc.txt', a: true }
  
  // rminimist
  { _: [], a: true, file: 'doc.txt' }

• Number-like values are never auto-cast to numbers. Use the number option instead.

  // minimist
  minimist(['--port', '4000'])
  { _: [], port: 4000 }
  
  // rminimist
  rminimist(['--port', '4000'])
  { _: [], port: '4000' }
  
  rminimist(['--port', '4000'], { number: ['port'] })
  { _: [], port: 4000 }

• boolean: true and string: true are not supported. Use the array syntax instead.

  // minimist
  minimist(['-a', 'hello'], { boolean: true })
  
  // rminimist
  rminimist(['-a', 'hello'], { boolean: ['a'] })

• The unknown option is not supported.

• You can add to a previous rminimist() result by passing it as the third parameter.

  > result = rminimist(['-f']);
  > result = rminimist(['-d'], {}, result);
  > result
  { _: [], f: true, d: true }

Thanks

rminimist © 2016+, Rico Sta. Cruz. Released under the MIT License. Authored and maintained by Rico Sta. Cruz with help from contributors (list).

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz