diff --git a/README.md b/README.md index 7efea89..7e65048 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ changes: using `tokens` in input `config` and returned properties. --> -> Stability: 1 - Experimental +> Stability: 2 - Stable * `config` {Object} Used to provide arguments for parsing and to configure the parser. `config` supports the following properties: @@ -40,6 +40,9 @@ changes: * `allowPositionals` {boolean} Whether this command accepts positional arguments. **Default:** `false` if `strict` is `true`, otherwise `true`. + * `allowNegative` {boolean} If `true`, allows explicitly setting boolean + options to `false` by prefixing the option name with `--no-`. + **Default:** `false`. * `tokens` {boolean} Return the parsed tokens. This is useful for extending the built-in behavior, from adding additional checks through to reprocessing the tokens in different ways. @@ -125,9 +128,9 @@ that appear more than once in args produce a token for each use. Short option groups like `-xy` expand to a token for each option. So `-xxx` produces three tokens. -For example to use the returned tokens to add support for a negated option -like `--no-color`, the tokens can be reprocessed to change the value stored -for the negated option. +For example, to add support for a negated option like `--no-color` (which +`allowNegative` supports when the option is of `boolean` type), the returned +tokens can be reprocessed to change the value stored for the negated option. ```mjs import { parseArgs } from 'node:util'; diff --git a/index.js b/index.js index b1004c7..612e66f 100644 --- a/index.js +++ b/index.js @@ -1,5 +1,7 @@ 'use strict'; +/* eslint max-len: ["error", {"code": 120}], */ + const { ArrayPrototypeForEach, ArrayPrototypeIncludes, @@ -95,14 +97,24 @@ To specify an option argument starting with a dash use ${example}.`; * @param {object} token - from tokens as available from parseArgs */ function checkOptionUsage(config, token) { - if (!ObjectHasOwn(config.options, token.name)) { - throw new ERR_PARSE_ARGS_UNKNOWN_OPTION( - token.rawName, config.allowPositionals); + let tokenName = token.name; + if (!ObjectHasOwn(config.options, tokenName)) { + // Check for negated boolean option. + if (config.allowNegative && StringPrototypeStartsWith(tokenName, 'no-')) { + tokenName = StringPrototypeSlice(tokenName, 3); + if (!ObjectHasOwn(config.options, tokenName) || optionsGetOwn(config.options, tokenName, 'type') !== 'boolean') { + throw new ERR_PARSE_ARGS_UNKNOWN_OPTION( + token.rawName, config.allowPositionals); + } + } else { + throw new ERR_PARSE_ARGS_UNKNOWN_OPTION( + token.rawName, config.allowPositionals); + } } - const short = optionsGetOwn(config.options, token.name, 'short'); - const shortAndLong = `${short ? `-${short}, ` : ''}--${token.name}`; - const type = optionsGetOwn(config.options, token.name, 'type'); + const short = optionsGetOwn(config.options, tokenName, 'short'); + const shortAndLong = `${short ? `-${short}, ` : ''}--${tokenName}`; + const type = optionsGetOwn(config.options, tokenName, 'type'); if (type === 'string' && typeof token.value !== 'string') { throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(`Option '${shortAndLong} ' argument missing`); } @@ -115,17 +127,25 @@ function checkOptionUsage(config, token) { /** * Store the option value in `values`. - * - * @param {string} longOption - long option name e.g. 'foo' - * @param {string|undefined} optionValue - value from user args + * @param {object} token - from tokens as available from parseArgs * @param {object} options - option configs, from parseArgs({ options }) * @param {object} values - option values returned in `values` by parseArgs + * @param {boolean} allowNegative - allow negative optinons if true */ -function storeOption(longOption, optionValue, options, values) { +function storeOption(token, options, values, allowNegative) { + let longOption = token.name; + let optionValue = token.value; if (longOption === '__proto__') { return; // No. Just no. } + if (allowNegative && StringPrototypeStartsWith(longOption, 'no-') && optionValue === undefined) { + // Boolean option negation: --no-foo + longOption = StringPrototypeSlice(longOption, 3); + token.name = longOption; + optionValue = false; + } + // We store based on the option value rather than option type, // preserving the users intent for author to deal with. const newValue = optionValue ?? true; @@ -295,15 +315,17 @@ const parseArgs = (config = kEmptyObject) => { const strict = objectGetOwn(config, 'strict') ?? true; const allowPositionals = objectGetOwn(config, 'allowPositionals') ?? !strict; const returnTokens = objectGetOwn(config, 'tokens') ?? false; + const allowNegative = objectGetOwn(config, 'allowNegative') ?? false; const options = objectGetOwn(config, 'options') ?? { __proto__: null }; // Bundle these up for passing to strict-mode checks. - const parseConfig = { args, strict, options, allowPositionals }; + const parseConfig = { args, strict, options, allowPositionals, allowNegative }; // Validate input configuration. validateArray(args, 'args'); validateBoolean(strict, 'strict'); validateBoolean(allowPositionals, 'allowPositionals'); validateBoolean(returnTokens, 'tokens'); + validateBoolean(allowNegative, 'allowNegative'); validateObject(options, 'options'); ArrayPrototypeForEach( ObjectEntries(options), @@ -365,7 +387,7 @@ const parseArgs = (config = kEmptyObject) => { checkOptionUsage(parseConfig, token); checkOptionLikeValue(token); } - storeOption(token.name, token.value, options, result.values); + storeOption(token, options, result.values, parseConfig.allowNegative); } else if (token.kind === 'positional') { if (!allowPositionals) { throw new ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL(token.value); diff --git a/test/allow-negative.js b/test/allow-negative.js new file mode 100644 index 0000000..a560f12 --- /dev/null +++ b/test/allow-negative.js @@ -0,0 +1,75 @@ +/* global assert */ +/* eslint max-len: 0 */ +'use strict'; + +const { test } = require('./utils'); +const { parseArgs } = require('../index'); + +test('disable negative options and args are started with "--no-" prefix', () => { + const args = ['--no-alpha']; + const options = { alpha: { type: 'boolean' } }; + assert.throws(() => { + parseArgs({ args, options }); + }, { + code: 'ERR_PARSE_ARGS_UNKNOWN_OPTION' + }); +}); + +test('args are passed `type: "string"` and allow negative options', () => { + const args = ['--no-alpha', 'value']; + const options = { alpha: { type: 'string' } }; + assert.throws(() => { + parseArgs({ args, options, allowNegative: true }); + }, { + code: 'ERR_PARSE_ARGS_UNKNOWN_OPTION' + }); +}); + +test('args are passed `type: "boolean"` and allow negative options', () => { + const args = ['--no-alpha']; + const options = { alpha: { type: 'boolean' } }; + const expected = { values: { __proto__: null, alpha: false }, positionals: [] }; + assert.deepStrictEqual(parseArgs({ args, options, allowNegative: true }), expected); +}); + +test('args are passed `default: "true"` and allow negative options', () => { + const args = ['--no-alpha']; + const options = { alpha: { type: 'boolean', default: true } }; + const expected = { values: { __proto__: null, alpha: false }, positionals: [] }; + assert.deepStrictEqual(parseArgs({ args, options, allowNegative: true }), expected); +}); + +test('args are passed `default: "false" and allow negative options', () => { + const args = ['--no-alpha']; + const options = { alpha: { type: 'boolean', default: false } }; + const expected = { values: { __proto__: null, alpha: false }, positionals: [] }; + assert.deepStrictEqual(parseArgs({ args, options, allowNegative: true }), expected); +}); + +test('allow negative options and multiple as true', () => { + const args = ['--no-alpha', '--alpha', '--no-alpha']; + const options = { alpha: { type: 'boolean', multiple: true } }; + const expected = { values: { __proto__: null, alpha: [false, true, false] }, positionals: [] }; + assert.deepStrictEqual(parseArgs({ args, options, allowNegative: true }), expected); +}); + +test('allow negative options and passed multiple arguments', () => { + const args = ['--no-alpha', '--alpha']; + const options = { alpha: { type: 'boolean' } }; + const expected = { values: { __proto__: null, alpha: true }, positionals: [] }; + assert.deepStrictEqual(parseArgs({ args, options, allowNegative: true }), expected); +}); + +test('auto-detect --no-foo as negated when strict:false and allowNegative', () => { + const holdArgv = process.argv; + process.argv = [process.argv0, 'script.js', '--no-foo']; + const holdExecArgv = process.execArgv; + process.execArgv = []; + const result = parseArgs({ strict: false, allowNegative: true }); + + const expected = { values: { __proto__: null, foo: false }, + positionals: [] }; + assert.deepStrictEqual(result, expected); + process.argv = holdArgv; + process.execArgv = holdExecArgv; +});