rminimist

Parse argument options

Usage no npm install needed!

<script type="module">
  import rminimist from 'https://cdn.skypack.dev/rminimist';
</script>

README

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).

Status

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