diff --git a/doc/api/errors.md b/doc/api/errors.md index 801f22727f3305..ac35c8e9f07f34 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -2355,6 +2355,40 @@ The `package.json` [`"exports"`][] field does not export the requested subpath. Because exports are encapsulated, private internal modules that are not exported cannot be imported through the package resolution, unless using an absolute URL. + + +### `ERR_PARSE_ARGS_INVALID_OPTION_VALUE` + + + +When `strict` set to `true`, thrown by [`util.parseArgs()`][] if a {boolean} +value is provided for an option of type {string}, or if a {string} +value is provided for an option of type {boolean}. + + + +### `ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL` + + + +Thrown by [`util.parseArgs()`][], when a postional argument is provided and +`allowPositionals` is set to `false`. + + + +### `ERR_PARSE_ARGS_UNKNOWN_OPTION` + + + +When `strict` set to `true`, thrown by [`util.parseArgs()`][] if an argument +is not configured in `options`. + ### `ERR_PERFORMANCE_INVALID_TIMESTAMP` @@ -3466,6 +3500,7 @@ The native call from `process.cpuUsage` could not be processed. [`subprocess.send()`]: child_process.md#subprocesssendmessage-sendhandle-options-callback [`url.parse()`]: url.md#urlparseurlstring-parsequerystring-slashesdenotehost [`util.getSystemErrorName(error.errno)`]: util.md#utilgetsystemerrornameerr +[`util.parseArgs()`]: util.md#utilparseargsconfig [`zlib`]: zlib.md [crypto digest algorithm]: crypto.md#cryptogethashes [debugger]: debugger.md diff --git a/doc/api/util.md b/doc/api/util.md index 8cafd120503764..e2f7ac9e0ae586 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])` + + + +> 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)`