GitHub - pkgjs/parseargs at v0.9.1 (original) (raw)

parseArgs

Coverage

Polyfill of proposal for util.parseArgs()

util.parseArgs([config])

Stability: 1 - Experimental

Provides a higher level API for command-line argument parsing than interacting with process.argv directly. Takes a specification for the expected arguments and returns a structured object with the parsed options and positionals.

import { parseArgs } from 'node:util'; const args = ['-f', '--bar', 'b']; const options = { foo: { type: 'boolean', short: 'f' }, bar: { type: 'string' } }; const { values, positionals } = parseArgs({ args, options }); console.log(values, positionals); // Prints: [Object: null prototype] { foo: true, bar: 'b' } []

const { parseArgs } = require('node:util'); const args = ['-f', '--bar', 'b']; const options = { foo: { type: 'boolean', short: 'f' }, bar: { type: 'string' } }; const { values, positionals } = parseArgs({ args, options }); console.log(values, positionals); // Prints: [Object: null prototype] { foo: true, bar: 'b' } []ss

util.parseArgs is experimental and behavior may change. Join the conversation in pkgjs/parseargs to contribute to the design.

Table of Contents

Scope

It is already possible to build great arg parsing modules on top of what Node.js provides; the prickly API is abstracted away by these modules. Thus, process.parseArgs() is not necessarily intended for library authors; it is intended for developers of simple CLI tools, ad-hoc scripts, deployed Node.js applications, and learning materials.

It is exceedingly difficult to provide an API which would both be friendly to these Node.js users while being extensible enough for libraries to build upon. We chose to prioritize these use cases because these are currently not well-served by Node.js' API.

🚀 Getting Started

  1. Install dependencies.
  2. Open the index.js file and start editing!
  3. Test your code by calling parseArgs through our test file

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

This package was implemented using tape as its test harness.

💡 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([config]) Proposal

📃 Examples

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

const { parseArgs } = require('@pkgjs/parseargs'); // specify the options that may be used const options = { foo: { type: 'string'}, bar: { type: 'boolean' }, }; const args = ['--foo=a', '--bar']; const { values, positionals } = parseArgs({ args, options }); // values = { foo: 'a', bar: true } // positionals = []

const { parseArgs } = require('@pkgjs/parseargs'); // type:string & multiple const options = { foo: { type: 'string', multiple: true, }, }; const args = ['--foo=a', '--foo', 'b']; const { values, positionals } = parseArgs({ args, options }); // values = { foo: [ 'a', 'b' ] } // positionals = []

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

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

F.A.Qs

Links & Resources