diff options
author | Benjamin E. Coe <bencoe@google.com> | 2022-05-24 20:07:26 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-05-24 20:07:26 +0300 |
commit | 4a3ba87eabd7bbceb95f0e902fa37a76c0aff223 (patch) | |
tree | 4f49a6bdfd1469874cd8fbaae657f980047f0dc1 /doc/api/util.md | |
parent | 304e06ada42e81075f93cea9b82400d210669875 (diff) |
util: add parseArgs module
Adds util.parseArgs helper for higher level command-line argument
parsing.
PR-URL: https://github.com/nodejs/node/pull/42675
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Ruy Adorno <ruyadorno@github.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Joe Sepi <sepi@joesepi.com>
Reviewed-By: Ian Sutherland <ian@iansutherland.ca>
Diffstat (limited to 'doc/api/util.md')
-rw-r--r-- | doc/api/util.md | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/doc/api/util.md b/doc/api/util.md index 8cafd120503..e2f7ac9e0ae 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1020,6 +1020,86 @@ Otherwise, returns `false`. See [`assert.deepStrictEqual()`][] for more information about deep strict equality. +## `util.parseArgs([config])` + +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* `config` {Object} Used to provide arguments for parsing and to configure + the parser. `config` supports the following properties: + * `args` {string\[]} array of argument strings. **Default:** `process.argv` + with `execPath` and `filename` removed. + * `options` {Object} Used to describe arguments known to the parser. + Keys of `options` are the long names of options and values are an + {Object} accepting the following properties: + * `type` {string} Type of argument, which must be either `boolean` or `string`. + * `multiple` {boolean} Whether this option can be provided multiple + times. If `true`, all values will be collected in an array. If + `false`, values for the option are last-wins. **Default:** `false`. + * `short` {string} A single character alias for the option. + * `strict`: {boolean} Should an error be thrown when unknown arguments + are encountered, or when arguments are passed that do not match the + `type` configured in `options`. + **Default:** `true`. + * `allowPositionals`: {boolean} Whether this command accepts positional + arguments. + **Default:** `false` if `strict` is `true`, otherwise `true`. + +* Returns: {Object} The parsed command line arguments: + * `values` {Object} A mapping of parsed option names with their {string} + or {boolean} values. + * `positionals` {string\[]} Positional arguments. + +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. + +```mjs +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' } [] +``` + +```cjs +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. + ## `util.promisify(original)` <!-- YAML @@ -2693,5 +2773,6 @@ util.log('Timestamped message.'); [default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort [global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for [list of deprecated APIS]: deprecations.md#list-of-deprecated-apis +[pkgjs/parseargs]: https://github.com/pkgjs/parseargs [semantically incompatible]: https://github.com/nodejs/node/issues/4179 [util.inspect.custom]: #utilinspectcustom |