parseArgs

🚨 THIS REPO IS AN EARLY WIP -- DO NOT USE ... yet 🚨

Polyfill of future proposal to the nodejs/tooling repo for util.parseArgs()

This package was implemented using tape as its test harness.

Links & Resources

• Initial Tooling Issue
• Initial Proposal

Table of Contents

• 🚀 Getting Started
• 🙌 Contributing
• 💡 process.mainArgs Proposal
  • Implementation:
• 💡 util.parseArgs(argv) Proposal
• 📃 Examples
  • F.A.Qs

🚀 Getting Started

1. Install dependencies.

   npm install

2. Open the index.js file and start editing!

3. Test your code by calling parseArgs through our test file

   npm test

🙌 Contributing

Any person who wants to contribute to the initiative is welcome! Please first read the Contributing Guide

Additionally, reading the Examples w/ Output section of this document will be the best way to familiarize yourself with the target expected behavior for parseArgs() once it is fully implemented.

💡 process.mainArgs Proposal

Note: This can be moved forward independently of the util.parseArgs() proposal/work.

Implementation:

process.mainArgs = process.argv.slice(process._exec ? 1 : 2)

💡 util.parseArgs([argv][, options]) Proposal

• argv {string[]} (Optional) Array of argument strings; defaults to process.mainArgs
• options {Object} (Optional) The options parameter is an object supporting the following properties:
  • withValue {string[]} (Optional) An Array of argument strings which expect a value to be defined in argv (see [Options][] for details)
  • multiples {string[]} (Optional) An Array of argument strings which, when appearing multiple times in argv, will be concatenated into an Array
  • short {Object} (Optional) An Object of key, value pairs of strings which map a "short" alias to an argument; When appearing multiples times in argv; Respects withValue & multiples
  • strict {Boolean} (Optional) A Boolean on wheather or not to throw an error when unknown args are encountered
• Returns: {Object} An object having properties:
  • flags {Object}, having properties and Boolean values corresponding to parsed options passed
  • values {Object}, have properties and String values corresponding to parsed options passed
  • positionals {string[]}, containing [Positionals][]

📃 Examples

const { parseArgs } = require('@pkgjs/parseargs');

// unconfigured
const { parseArgs } = require('@pkgjs/parseargs');
const argv = ['-f', '--foo=a', '--bar', 'b'];
const options = {};
const { flags, values, positionals } = parseArgs(argv, options);
// flags = { f: true, bar: true }
// values = { foo: 'a' }
// positionals = ['b']

const { parseArgs } = require('@pkgjs/parseargs');
// withValue
const argv = ['-f', '--foo=a', '--bar', 'b'];
const options = {
  withValue: ['bar']
};
const { flags, values, positionals } = parseArgs(argv, options);
// flags = { f: true }
// values = { foo: 'a', bar: 'b' }
// positionals = []

const { parseArgs } = require('@pkgjs/parseargs');
// withValue & multiples
const argv = ['-f', '--foo=a', '--foo', 'b'];
const options = {
  withValue: ['foo'],
  multiples: ['foo']
};
const { flags, values, positionals } = parseArgs(argv, options);
// flags = { f: true }
// values = { foo: ['a', 'b'] }
// positionals = []

const { parseArgs } = require('@pkgjs/parseargs');
// shorts
const argv = ['-f', 'b'];
const options = {
  short: { f: 'foo' }
};
const { flags, values, positionals } = parseArgs(argv, options);
// flags = { foo: true }
// values = {}
// positionals = ['b']

F.A.Qs

• Is cmd --foo=bar baz the same as cmd baz --foo=bar?
  • Yes, if withValue: ['foo'], otherwise no
• Does the parser execute a function?
  • no
• Does the parser execute one of several functions, depending on input?
  • no
• Can subcommands take options that are distinct from the main command?
  • no
• Does it output generated help when no options match?
  • no
• Does it generated short usage? Like: usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]
  • no (no usage/help at all)
• Does the user provide the long usage text? For each option? For the whole command?
  • no
• Do subcommands (if implemented) have their own usage output?
  • no
• Does usage print if the user runs cmd --help?
  • no
• Does it set process.exitCode?
  • no
• Does usage print to stderr or stdout?
  • N/A
• Does it check types? (Say, specify that an option is a boolean, number, etc.)
  • no
• Can an option have more than one type? (string or false, for example)
  • no
• Can the user define a type? (Say, type: path to call path.resolve() on the argument.)
  • no
• Does a --foo=0o22 mean 0, 22, 18, or "0o22"?
  • "0o22"
• Does it coerce types?
  • no
• Does --no-foo coerce to --foo=false? For all flags? Only boolean flags?
  • no, it sets {args:{'no-foo': true}}
• Is --foo the same as --foo=true? Only for known booleans? Only at the end?
  • no, --foo is the same as --foo=
• Does it read environment variables? Ie, is FOO=1 cmd the same as cmd --foo=1?
  • no
• Do unknown arguments raise an error? Are they parsed? Are they treated as positional arguments?
  • no, they are parsed, not treated as positionals
• Does -- signal the end of flags/options?
  • open question
  • If -- signals the end, is -- included as a positional? is program -- foo the same as program foo? Are both {positionals:['foo']}, or is the first one {positionals:['--', 'foo']}?
• Does the API specify whether a -- was present/relevant?
  • no
• Is -bar the same as --bar?
  • no, -bar is a short option or options, with expansion logic that follows the Utility Syntax Guidelines in POSIX.1-2017. -bar expands to -b, -a, -r.
• Is ---foo the same as --foo?
  • no
  • the first flag would be parsed as '-foo'
  • the second flag would be parsed as 'foo'
• Is - a positional? ie, bash some-test.sh | tap -
  • yes