From 596184f95bf334a880a237a0bc3c37f95a8eff7e Mon Sep 17 00:00:00 2001 From: QmarkC Date: Sat, 18 Jul 2020 17:08:21 -0500 Subject: [PATCH] refactor(ts): initial conversion to TypeScript (#285) --- index.js | 1033 +--------------------------------- lib/common-types.ts | 18 + lib/index.ts | 1114 +++++++++++++++++++++++++++++++++++++ lib/yargs-parser-types.ts | 159 ++++++ test/yargs-parser.js | 55 ++ 5 files changed, 1348 insertions(+), 1031 deletions(-) create mode 100644 lib/common-types.ts create mode 100644 lib/index.ts create mode 100644 lib/yargs-parser-types.ts diff --git a/index.js b/index.js index 4522fcc1..d6e1bb04 100644 --- a/index.js +++ b/index.js @@ -1,8 +1,4 @@ -const camelCase = require('camelcase') -const decamelize = require('decamelize') -const path = require('path') -const { tokenizeArgString } = require('./build/lib/tokenize-arg-string') -const util = require('util') +const { yargsParser } = require('./build/lib') // See https://github.com/yargs/yargs-parser#supported-nodejs-versions for our // version support policy. The YARGS_MIN_NODE_VERSION is used for testing only. @@ -15,1029 +11,4 @@ if (process && process.version) { } } -function parse (args, opts) { - opts = Object.assign(Object.create(null), opts) - // allow a string argument to be passed in rather - // than an argv array. - args = tokenizeArgString(args) - - // aliases might have transitive relationships, normalize this. - const aliases = combineAliases(Object.assign(Object.create(null), opts.alias)) - const configuration = Object.assign({ - 'boolean-negation': true, - 'camel-case-expansion': true, - 'combine-arrays': false, - 'dot-notation': true, - 'duplicate-arguments-array': true, - 'flatten-duplicate-arrays': true, - 'greedy-arrays': true, - 'halt-at-non-option': false, - 'nargs-eats-options': false, - 'negation-prefix': 'no-', - 'parse-numbers': true, - 'populate--': false, - 'set-placeholder-key': false, - 'short-option-groups': true, - 'strip-aliased': false, - 'strip-dashed': false, - 'unknown-options-as-args': false - }, opts.configuration) - const defaults = Object.assign(Object.create(null), opts.default) - const configObjects = opts.configObjects || [] - const envPrefix = opts.envPrefix - const notFlagsOption = configuration['populate--'] - const notFlagsArgv = notFlagsOption ? '--' : '_' - const newAliases = Object.create(null) - const defaulted = Object.create(null) - // allow a i18n handler to be passed in, default to a fake one (util.format). - const __ = opts.__ || util.format - const flags = { - aliases: Object.create(null), - arrays: Object.create(null), - bools: Object.create(null), - strings: Object.create(null), - numbers: Object.create(null), - counts: Object.create(null), - normalize: Object.create(null), - configs: Object.create(null), - nargs: Object.create(null), - coercions: Object.create(null), - keys: [] - } - const negative = /^-([0-9]+(\.[0-9]+)?|\.[0-9]+)$/ - const negatedBoolean = new RegExp('^--' + configuration['negation-prefix'] + '(.+)') - - ;[].concat(opts.array).filter(Boolean).forEach(function (opt) { - const key = opt.key || opt - - // assign to flags[bools|strings|numbers] - const assignment = Object.keys(opt).map(function (key) { - return ({ - boolean: 'bools', - string: 'strings', - number: 'numbers' - })[key] - }).filter(Boolean).pop() - - // assign key to be coerced - if (assignment) { - flags[assignment][key] = true - } - - flags.arrays[key] = true - flags.keys.push(key) - }) - - ;[].concat(opts.boolean).filter(Boolean).forEach(function (key) { - flags.bools[key] = true - flags.keys.push(key) - }) - - ;[].concat(opts.string).filter(Boolean).forEach(function (key) { - flags.strings[key] = true - flags.keys.push(key) - }) - - ;[].concat(opts.number).filter(Boolean).forEach(function (key) { - flags.numbers[key] = true - flags.keys.push(key) - }) - - ;[].concat(opts.count).filter(Boolean).forEach(function (key) { - flags.counts[key] = true - flags.keys.push(key) - }) - - ;[].concat(opts.normalize).filter(Boolean).forEach(function (key) { - flags.normalize[key] = true - flags.keys.push(key) - }) - - Object.keys(opts.narg || {}).forEach(function (k) { - flags.nargs[k] = opts.narg[k] - flags.keys.push(k) - }) - - Object.keys(opts.coerce || {}).forEach(function (k) { - flags.coercions[k] = opts.coerce[k] - flags.keys.push(k) - }) - - if (Array.isArray(opts.config) || typeof opts.config === 'string') { - ;[].concat(opts.config).filter(Boolean).forEach(function (key) { - flags.configs[key] = true - }) - } else { - Object.keys(opts.config || {}).forEach(function (k) { - flags.configs[k] = opts.config[k] - }) - } - - // create a lookup table that takes into account all - // combinations of aliases: {f: ['foo'], foo: ['f']} - extendAliases(opts.key, aliases, opts.default, flags.arrays) - - // apply default values to all aliases. - Object.keys(defaults).forEach(function (key) { - (flags.aliases[key] || []).forEach(function (alias) { - defaults[alias] = defaults[key] - }) - }) - - let error = null - checkConfiguration() - - let notFlags = [] - - const argv = Object.assign(Object.create(null), { _: [] }) - // TODO(bcoe): for the first pass at removing object prototype we didn't - // remove all prototypes from objects returned by this API, we might want - // to gradually move towards doing so. - const argvReturn = {} - - for (let i = 0; i < args.length; i++) { - const arg = args[i] - let broken - let key - let letters - let m - let next - let value - - // any unknown option (except for end-of-options, "--") - if (arg !== '--' && isUnknownOptionAsArg(arg)) { - argv._.push(arg) - // -- separated by = - } else if (arg.match(/^--.+=/) || ( - !configuration['short-option-groups'] && arg.match(/^-.+=/) - )) { - // Using [\s\S] instead of . because js doesn't support the - // 'dotall' regex modifier. See: - // http://stackoverflow.com/a/1068308/13216 - m = arg.match(/^--?([^=]+)=([\s\S]*)$/) - - // arrays format = '--f=a b c' - if (checkAllAliases(m[1], flags.arrays)) { - i = eatArray(i, m[1], args, m[2]) - } else if (checkAllAliases(m[1], flags.nargs) !== false) { - // nargs format = '--f=monkey washing cat' - i = eatNargs(i, m[1], args, m[2]) - } else { - setArg(m[1], m[2]) - } - } else if (arg.match(negatedBoolean) && configuration['boolean-negation']) { - key = arg.match(negatedBoolean)[1] - setArg(key, checkAllAliases(key, flags.arrays) ? [false] : false) - - // -- separated by space. - } else if (arg.match(/^--.+/) || ( - !configuration['short-option-groups'] && arg.match(/^-[^-]+/) - )) { - key = arg.match(/^--?(.+)/)[1] - - if (checkAllAliases(key, flags.arrays)) { - // array format = '--foo a b c' - i = eatArray(i, key, args) - } else if (checkAllAliases(key, flags.nargs) !== false) { - // nargs format = '--foo a b c' - // should be truthy even if: flags.nargs[key] === 0 - i = eatNargs(i, key, args) - } else { - next = args[i + 1] - - if (next !== undefined && (!next.match(/^-/) || - next.match(negative)) && - !checkAllAliases(key, flags.bools) && - !checkAllAliases(key, flags.counts)) { - setArg(key, next) - i++ - } else if (/^(true|false)$/.test(next)) { - setArg(key, next) - i++ - } else { - setArg(key, defaultValue(key)) - } - } - - // dot-notation flag separated by '='. - } else if (arg.match(/^-.\..+=/)) { - m = arg.match(/^-([^=]+)=([\s\S]*)$/) - setArg(m[1], m[2]) - - // dot-notation flag separated by space. - } else if (arg.match(/^-.\..+/) && !arg.match(negative)) { - next = args[i + 1] - key = arg.match(/^-(.\..+)/)[1] - - if (next !== undefined && !next.match(/^-/) && - !checkAllAliases(key, flags.bools) && - !checkAllAliases(key, flags.counts)) { - setArg(key, next) - i++ - } else { - setArg(key, defaultValue(key)) - } - } else if (arg.match(/^-[^-]+/) && !arg.match(negative)) { - letters = arg.slice(1, -1).split('') - broken = false - - for (let j = 0; j < letters.length; j++) { - next = arg.slice(j + 2) - - if (letters[j + 1] && letters[j + 1] === '=') { - value = arg.slice(j + 3) - key = letters[j] - - if (checkAllAliases(key, flags.arrays)) { - // array format = '-f=a b c' - i = eatArray(i, key, args, value) - } else if (checkAllAliases(key, flags.nargs) !== false) { - // nargs format = '-f=monkey washing cat' - i = eatNargs(i, key, args, value) - } else { - setArg(key, value) - } - - broken = true - break - } - - if (next === '-') { - setArg(letters[j], next) - continue - } - - // current letter is an alphabetic character and next value is a number - if (/[A-Za-z]/.test(letters[j]) && - /^-?\d+(\.\d*)?(e-?\d+)?$/.test(next)) { - setArg(letters[j], next) - broken = true - break - } - - if (letters[j + 1] && letters[j + 1].match(/\W/)) { - setArg(letters[j], next) - broken = true - break - } else { - setArg(letters[j], defaultValue(letters[j])) - } - } - - key = arg.slice(-1)[0] - - if (!broken && key !== '-') { - if (checkAllAliases(key, flags.arrays)) { - // array format = '-f a b c' - i = eatArray(i, key, args) - } else if (checkAllAliases(key, flags.nargs) !== false) { - // nargs format = '-f a b c' - // should be truthy even if: flags.nargs[key] === 0 - i = eatNargs(i, key, args) - } else { - next = args[i + 1] - - if (next !== undefined && (!/^(-|--)[^-]/.test(next) || - next.match(negative)) && - !checkAllAliases(key, flags.bools) && - !checkAllAliases(key, flags.counts)) { - setArg(key, next) - i++ - } else if (/^(true|false)$/.test(next)) { - setArg(key, next) - i++ - } else { - setArg(key, defaultValue(key)) - } - } - } - } else if (arg.match(/^-[0-9]$/) && - arg.match(negative) && - checkAllAliases(arg.slice(1), flags.bools)) { - // single-digit boolean alias, e.g: xargs -0 - key = arg.slice(1) - setArg(key, defaultValue(key)) - } else if (arg === '--') { - notFlags = args.slice(i + 1) - break - } else if (configuration['halt-at-non-option']) { - notFlags = args.slice(i) - break - } else { - argv._.push(maybeCoerceNumber('_', arg)) - } - } - - // order of precedence: - // 1. command line arg - // 2. value from env var - // 3. value from config file - // 4. value from config objects - // 5. configured default value - applyEnvVars(argv, true) // special case: check env vars that point to config file - applyEnvVars(argv, false) - setConfig(argv) - setConfigObjects() - applyDefaultsAndAliases(argv, flags.aliases, defaults, true) - applyCoercions(argv) - if (configuration['set-placeholder-key']) setPlaceholderKeys(argv) - - // for any counts either not in args or without an explicit default, set to 0 - Object.keys(flags.counts).forEach(function (key) { - if (!hasKey(argv, key.split('.'))) setArg(key, 0) - }) - - // '--' defaults to undefined. - if (notFlagsOption && notFlags.length) argv[notFlagsArgv] = [] - notFlags.forEach(function (key) { - argv[notFlagsArgv].push(key) - }) - - if (configuration['camel-case-expansion'] && configuration['strip-dashed']) { - Object.keys(argv).filter(key => key !== '--' && key.includes('-')).forEach(key => { - delete argv[key] - }) - } - - if (configuration['strip-aliased']) { - ;[].concat(...Object.keys(aliases).map(k => aliases[k])).forEach(alias => { - if (configuration['camel-case-expansion']) { - delete argv[alias.split('.').map(prop => camelCase(prop)).join('.')] - } - - delete argv[alias] - }) - } - - // how many arguments should we consume, based - // on the nargs option? - function eatNargs (i, key, args, argAfterEqualSign) { - let ii - let toEat = checkAllAliases(key, flags.nargs) - // NaN has a special meaning for the array type, indicating that one or - // more values are expected. - toEat = isNaN(toEat) ? 1 : toEat - - if (toEat === 0) { - if (!isUndefined(argAfterEqualSign)) { - error = Error(__('Argument unexpected for: %s', key)) - } - setArg(key, defaultValue(key)) - return i - } - - let available = isUndefined(argAfterEqualSign) ? 0 : 1 - if (configuration['nargs-eats-options']) { - // classic behavior, yargs eats positional and dash arguments. - if (args.length - (i + 1) + available < toEat) { - error = Error(__('Not enough arguments following: %s', key)) - } - available = toEat - } else { - // nargs will not consume flag arguments, e.g., -abc, --foo, - // and terminates when one is observed. - for (ii = i + 1; ii < args.length; ii++) { - if (!args[ii].match(/^-[^0-9]/) || args[ii].match(negative) || isUnknownOptionAsArg(args[ii])) available++ - else break - } - if (available < toEat) error = Error(__('Not enough arguments following: %s', key)) - } - - let consumed = Math.min(available, toEat) - if (!isUndefined(argAfterEqualSign) && consumed > 0) { - setArg(key, argAfterEqualSign) - consumed-- - } - for (ii = i + 1; ii < (consumed + i + 1); ii++) { - setArg(key, args[ii]) - } - - return (i + consumed) - } - - // if an option is an array, eat all non-hyphenated arguments - // following it... YUM! - // e.g., --foo apple banana cat becomes ["apple", "banana", "cat"] - function eatArray (i, key, args, argAfterEqualSign) { - let argsToSet = [] - let next = argAfterEqualSign || args[i + 1] - // If both array and nargs are configured, enforce the nargs count: - const nargsCount = checkAllAliases(key, flags.nargs) - - if (checkAllAliases(key, flags.bools) && !(/^(true|false)$/.test(next))) { - argsToSet.push(true) - } else if (isUndefined(next) || - (isUndefined(argAfterEqualSign) && /^-/.test(next) && !negative.test(next) && !isUnknownOptionAsArg(next))) { - // for keys without value ==> argsToSet remains an empty [] - // set user default value, if available - if (defaults[key] !== undefined) { - const defVal = defaults[key] - argsToSet = Array.isArray(defVal) ? defVal : [defVal] - } - } else { - // value in --option=value is eaten as is - if (!isUndefined(argAfterEqualSign)) { - argsToSet.push(processValue(key, argAfterEqualSign)) - } - for (let ii = i + 1; ii < args.length; ii++) { - if ((!configuration['greedy-arrays'] && argsToSet.length > 0) || - (nargsCount && argsToSet.length >= nargsCount)) break - next = args[ii] - if (/^-/.test(next) && !negative.test(next) && !isUnknownOptionAsArg(next)) break - i = ii - argsToSet.push(processValue(key, next)) - } - } - - // If both array and nargs are configured, create an error if less than - // nargs positionals were found. NaN has special meaning, indicating - // that at least one value is required (more are okay). - if ((nargsCount && argsToSet.length < nargsCount) || - (isNaN(nargsCount) && argsToSet.length === 0)) { - error = Error(__('Not enough arguments following: %s', key)) - } - - setArg(key, argsToSet) - return i - } - - function setArg (key, val) { - if (/-/.test(key) && configuration['camel-case-expansion']) { - const alias = key.split('.').map(function (prop) { - return camelCase(prop) - }).join('.') - addNewAlias(key, alias) - } - - const value = processValue(key, val) - const splitKey = key.split('.') - setKey(argv, splitKey, value) - - // handle populating aliases of the full key - if (flags.aliases[key]) { - flags.aliases[key].forEach(function (x) { - x = x.split('.') - setKey(argv, x, value) - }) - } - - // handle populating aliases of the first element of the dot-notation key - if (splitKey.length > 1 && configuration['dot-notation']) { - ;(flags.aliases[splitKey[0]] || []).forEach(function (x) { - x = x.split('.') - - // expand alias with nested objects in key - const a = [].concat(splitKey) - a.shift() // nuke the old key. - x = x.concat(a) - - // populate alias only if is not already an alias of the full key - // (already populated above) - if (!(flags.aliases[key] || []).includes(x.join('.'))) { - setKey(argv, x, value) - } - }) - } - - // Set normalize getter and setter when key is in 'normalize' but isn't an array - if (checkAllAliases(key, flags.normalize) && !checkAllAliases(key, flags.arrays)) { - const keys = [key].concat(flags.aliases[key] || []) - keys.forEach(function (key) { - Object.defineProperty(argvReturn, key, { - enumerable: true, - get () { - return val - }, - set (value) { - val = typeof value === 'string' ? path.normalize(value) : value - } - }) - }) - } - } - - function addNewAlias (key, alias) { - if (!(flags.aliases[key] && flags.aliases[key].length)) { - flags.aliases[key] = [alias] - newAliases[alias] = true - } - if (!(flags.aliases[alias] && flags.aliases[alias].length)) { - addNewAlias(alias, key) - } - } - - function processValue (key, val) { - // strings may be quoted, clean this up as we assign values. - if (typeof val === 'string' && - (val[0] === "'" || val[0] === '"') && - val[val.length - 1] === val[0] - ) { - val = val.substring(1, val.length - 1) - } - - // handle parsing boolean arguments --foo=true --bar false. - if (checkAllAliases(key, flags.bools) || checkAllAliases(key, flags.counts)) { - if (typeof val === 'string') val = val === 'true' - } - - let value = Array.isArray(val) - ? val.map(function (v) { return maybeCoerceNumber(key, v) }) - : maybeCoerceNumber(key, val) - - // increment a count given as arg (either no value or value parsed as boolean) - if (checkAllAliases(key, flags.counts) && (isUndefined(value) || typeof value === 'boolean')) { - value = increment - } - - // Set normalized value when key is in 'normalize' and in 'arrays' - if (checkAllAliases(key, flags.normalize) && checkAllAliases(key, flags.arrays)) { - if (Array.isArray(val)) value = val.map(path.normalize) - else value = path.normalize(val) - } - return value - } - - function maybeCoerceNumber (key, value) { - if (!checkAllAliases(key, flags.strings) && !checkAllAliases(key, flags.bools) && !Array.isArray(value)) { - const shouldCoerceNumber = isNumber(value) && configuration['parse-numbers'] && ( - Number.isSafeInteger(Math.floor(value)) - ) - if (shouldCoerceNumber || (!isUndefined(value) && checkAllAliases(key, flags.numbers))) value = Number(value) - } - return value - } - - // set args from config.json file, this should be - // applied last so that defaults can be applied. - function setConfig (argv) { - const configLookup = Object.create(null) - - // expand defaults/aliases, in-case any happen to reference - // the config.json file. - applyDefaultsAndAliases(configLookup, flags.aliases, defaults) - - Object.keys(flags.configs).forEach(function (configKey) { - const configPath = argv[configKey] || configLookup[configKey] - if (configPath) { - try { - let config = null - const resolvedConfigPath = path.resolve(process.cwd(), configPath) - - if (typeof flags.configs[configKey] === 'function') { - try { - config = flags.configs[configKey](resolvedConfigPath) - } catch (e) { - config = e - } - if (config instanceof Error) { - error = config - return - } - } else { - config = require(resolvedConfigPath) - } - - setConfigObject(config) - } catch (ex) { - if (argv[configKey]) error = Error(__('Invalid JSON config file: %s', configPath)) - } - } - }) - } - - // set args from config object. - // it recursively checks nested objects. - function setConfigObject (config, prev) { - Object.keys(config).forEach(function (key) { - const value = config[key] - const fullKey = prev ? prev + '.' + key : key - - // if the value is an inner object and we have dot-notation - // enabled, treat inner objects in config the same as - // heavily nested dot notations (foo.bar.apple). - if (typeof value === 'object' && value !== null && !Array.isArray(value) && configuration['dot-notation']) { - // if the value is an object but not an array, check nested object - setConfigObject(value, fullKey) - } else { - // setting arguments via CLI takes precedence over - // values within the config file. - if (!hasKey(argv, fullKey.split('.')) || (checkAllAliases(fullKey, flags.arrays) && configuration['combine-arrays'])) { - setArg(fullKey, value) - } - } - }) - } - - // set all config objects passed in opts - function setConfigObjects () { - if (typeof configObjects === 'undefined') return - configObjects.forEach(function (configObject) { - setConfigObject(configObject) - }) - } - - function applyEnvVars (argv, configOnly) { - if (!process) return - if (typeof envPrefix === 'undefined') return - const prefix = typeof envPrefix === 'string' ? envPrefix : '' - Object.keys(process.env).forEach(function (envVar) { - if (prefix === '' || envVar.lastIndexOf(prefix, 0) === 0) { - // get array of nested keys and convert them to camel case - const keys = envVar.split('__').map(function (key, i) { - if (i === 0) { - key = key.substring(prefix.length) - } - return camelCase(key) - }) - - if (((configOnly && flags.configs[keys.join('.')]) || !configOnly) && !hasKey(argv, keys)) { - setArg(keys.join('.'), process.env[envVar]) - } - } - }) - } - - function applyCoercions (argv) { - let coerce - const applied = new Set() - Object.keys(argv).forEach(function (key) { - if (!applied.has(key)) { // If we haven't already coerced this option via one of its aliases - coerce = checkAllAliases(key, flags.coercions) - if (typeof coerce === 'function') { - try { - const value = maybeCoerceNumber(key, coerce(argv[key])) - ;([].concat(flags.aliases[key] || [], key)).forEach(ali => { - applied.add(ali) - argv[ali] = value - }) - } catch (err) { - error = err - } - } - } - }) - } - - function setPlaceholderKeys (argv) { - flags.keys.forEach((key) => { - // don't set placeholder keys for dot notation options 'foo.bar'. - if (~key.indexOf('.')) return - if (typeof argv[key] === 'undefined') argv[key] = undefined - }) - return argv - } - - function applyDefaultsAndAliases (obj, aliases, defaults, canLog = false) { - Object.keys(defaults).forEach(function (key) { - if (!hasKey(obj, key.split('.'))) { - setKey(obj, key.split('.'), defaults[key]) - if (canLog) defaulted[key] = true - - ;(aliases[key] || []).forEach(function (x) { - if (hasKey(obj, x.split('.'))) return - setKey(obj, x.split('.'), defaults[key]) - }) - } - }) - } - - function hasKey (obj, keys) { - let o = obj - - if (!configuration['dot-notation']) keys = [keys.join('.')] - - keys.slice(0, -1).forEach(function (key) { - o = (o[key] || {}) - }) - - const key = keys[keys.length - 1] - - if (typeof o !== 'object') return false - else return key in o - } - - function setKey (obj, keys, value) { - let o = obj - - if (!configuration['dot-notation']) keys = [keys.join('.')] - - keys.slice(0, -1).forEach(function (key, index) { - // TODO(bcoe): in the next major version of yargs, switch to - // Object.create(null) for dot notation: - key = sanitizeKey(key) - - if (typeof o === 'object' && o[key] === undefined) { - o[key] = {} - } - - if (typeof o[key] !== 'object' || Array.isArray(o[key])) { - // ensure that o[key] is an array, and that the last item is an empty object. - if (Array.isArray(o[key])) { - o[key].push({}) - } else { - o[key] = [o[key], {}] - } - - // we want to update the empty object at the end of the o[key] array, so set o to that object - o = o[key][o[key].length - 1] - } else { - o = o[key] - } - }) - - // TODO(bcoe): in the next major version of yargs, switch to - // Object.create(null) for dot notation: - const key = sanitizeKey(keys[keys.length - 1]) - - const isTypeArray = checkAllAliases(keys.join('.'), flags.arrays) - const isValueArray = Array.isArray(value) - let duplicate = configuration['duplicate-arguments-array'] - - // nargs has higher priority than duplicate - if (!duplicate && checkAllAliases(key, flags.nargs)) { - duplicate = true - if ((!isUndefined(o[key]) && flags.nargs[key] === 1) || (Array.isArray(o[key]) && o[key].length === flags.nargs[key])) { - o[key] = undefined - } - } - - if (value === increment) { - o[key] = increment(o[key]) - } else if (Array.isArray(o[key])) { - if (duplicate && isTypeArray && isValueArray) { - o[key] = configuration['flatten-duplicate-arrays'] ? o[key].concat(value) : (Array.isArray(o[key][0]) ? o[key] : [o[key]]).concat([value]) - } else if (!duplicate && Boolean(isTypeArray) === Boolean(isValueArray)) { - o[key] = value - } else { - o[key] = o[key].concat([value]) - } - } else if (o[key] === undefined && isTypeArray) { - o[key] = isValueArray ? value : [value] - } else if (duplicate && !( - o[key] === undefined || - checkAllAliases(key, flags.counts) || - checkAllAliases(key, flags.bools) - )) { - o[key] = [o[key], value] - } else { - o[key] = value - } - } - - // extend the aliases list with inferred aliases. - function extendAliases (...args) { - args.forEach(function (obj) { - Object.keys(obj || {}).forEach(function (key) { - // short-circuit if we've already added a key - // to the aliases array, for example it might - // exist in both 'opts.default' and 'opts.key'. - if (flags.aliases[key]) return - - flags.aliases[key] = [].concat(aliases[key] || []) - // For "--option-name", also set argv.optionName - flags.aliases[key].concat(key).forEach(function (x) { - if (/-/.test(x) && configuration['camel-case-expansion']) { - const c = camelCase(x) - if (c !== key && flags.aliases[key].indexOf(c) === -1) { - flags.aliases[key].push(c) - newAliases[c] = true - } - } - }) - // For "--optionName", also set argv['option-name'] - flags.aliases[key].concat(key).forEach(function (x) { - if (x.length > 1 && /[A-Z]/.test(x) && configuration['camel-case-expansion']) { - const c = decamelize(x, '-') - if (c !== key && flags.aliases[key].indexOf(c) === -1) { - flags.aliases[key].push(c) - newAliases[c] = true - } - } - }) - flags.aliases[key].forEach(function (x) { - flags.aliases[x] = [key].concat(flags.aliases[key].filter(function (y) { - return x !== y - })) - }) - }) - }) - } - - // return the 1st set flag for any of a key's aliases (or false if no flag set) - function checkAllAliases (key, flag) { - const toCheck = [].concat(flags.aliases[key] || [], key) - const keys = Object.keys(flag) - const setAlias = toCheck.find(key => keys.includes(key)) - return setAlias ? flag[setAlias] : false - } - - function hasAnyFlag (key) { - const toCheck = [].concat(Object.keys(flags).map(k => flags[k])) - return toCheck.some(function (flag) { - return Array.isArray(flag) ? flag.includes(key) : flag[key] - }) - } - - function hasFlagsMatching (arg, ...patterns) { - const toCheck = [].concat(...patterns) - return toCheck.some(function (pattern) { - const match = arg.match(pattern) - return match && hasAnyFlag(match[1]) - }) - } - - // based on a simplified version of the short flag group parsing logic - function hasAllShortFlags (arg) { - // if this is a negative number, or doesn't start with a single hyphen, it's not a short flag group - if (arg.match(negative) || !arg.match(/^-[^-]+/)) { return false } - let hasAllFlags = true - let next - const letters = arg.slice(1).split('') - for (let j = 0; j < letters.length; j++) { - next = arg.slice(j + 2) - - if (!hasAnyFlag(letters[j])) { - hasAllFlags = false - break - } - - if ((letters[j + 1] && letters[j + 1] === '=') || - next === '-' || - (/[A-Za-z]/.test(letters[j]) && /^-?\d+(\.\d*)?(e-?\d+)?$/.test(next)) || - (letters[j + 1] && letters[j + 1].match(/\W/))) { - break - } - } - return hasAllFlags - } - - function isUnknownOptionAsArg (arg) { - return configuration['unknown-options-as-args'] && isUnknownOption(arg) - } - - function isUnknownOption (arg) { - // ignore negative numbers - if (arg.match(negative)) { return false } - // if this is a short option group and all of them are configured, it isn't unknown - if (hasAllShortFlags(arg)) { return false } - // e.g. '--count=2' - const flagWithEquals = /^-+([^=]+?)=[\s\S]*$/ - // e.g. '-a' or '--arg' - const normalFlag = /^-+([^=]+?)$/ - // e.g. '-a-' - const flagEndingInHyphen = /^-+([^=]+?)-$/ - // e.g. '-abc123' - const flagEndingInDigits = /^-+([^=]+?\d+)$/ - // e.g. '-a/usr/local' - const flagEndingInNonWordCharacters = /^-+([^=]+?)\W+.*$/ - // check the different types of flag styles, including negatedBoolean, a pattern defined near the start of the parse method - return !hasFlagsMatching(arg, flagWithEquals, negatedBoolean, normalFlag, flagEndingInHyphen, flagEndingInDigits, flagEndingInNonWordCharacters) - } - - // make a best effor to pick a default value - // for an option based on name and type. - function defaultValue (key) { - if (!checkAllAliases(key, flags.bools) && - !checkAllAliases(key, flags.counts) && - `${key}` in defaults) { - return defaults[key] - } else { - return defaultForType(guessType(key)) - } - } - - // return a default value, given the type of a flag., - // e.g., key of type 'string' will default to '', rather than 'true'. - function defaultForType (type) { - const def = { - boolean: true, - string: '', - number: undefined, - array: [] - } - - return def[type] - } - - // given a flag, enforce a default type. - function guessType (key) { - let type = 'boolean' - if (checkAllAliases(key, flags.strings)) type = 'string' - else if (checkAllAliases(key, flags.numbers)) type = 'number' - else if (checkAllAliases(key, flags.bools)) type = 'boolean' - else if (checkAllAliases(key, flags.arrays)) type = 'array' - return type - } - - function isNumber (x) { - if (x === null || x === undefined) return false - // if loaded from config, may already be a number. - if (typeof x === 'number') return true - // hexadecimal. - if (/^0x[0-9a-f]+$/i.test(x)) return true - // don't treat 0123 as a number; as it drops the leading '0'. - if (x.length > 1 && x[0] === '0') return false - return /^[-]?(?:\d+(?:\.\d*)?|\.\d+)(e[-+]?\d+)?$/.test(x) - } - - function isUndefined (num) { - return num === undefined - } - - // check user configuration settings for inconsistencies - function checkConfiguration () { - // count keys should not be set as array/narg - Object.keys(flags.counts).find(key => { - if (checkAllAliases(key, flags.arrays)) { - error = Error(__('Invalid configuration: %s, opts.count excludes opts.array.', key)) - return true - } else if (checkAllAliases(key, flags.nargs)) { - error = Error(__('Invalid configuration: %s, opts.count excludes opts.narg.', key)) - return true - } - }) - } - - return { - argv: Object.assign(argvReturn, argv), - error: error, - aliases: Object.assign({}, flags.aliases), - newAliases: Object.assign({}, newAliases), - defaulted: Object.assign({}, defaulted), - configuration: configuration - } -} - -// if any aliases reference each other, we should -// merge them together. -function combineAliases (aliases) { - const aliasArrays = [] - const combined = Object.create(null) - let change = true - - // turn alias lookup hash {key: ['alias1', 'alias2']} into - // a simple array ['key', 'alias1', 'alias2'] - Object.keys(aliases).forEach(function (key) { - aliasArrays.push( - [].concat(aliases[key], key) - ) - }) - - // combine arrays until zero changes are - // made in an iteration. - while (change) { - change = false - for (let i = 0; i < aliasArrays.length; i++) { - for (let ii = i + 1; ii < aliasArrays.length; ii++) { - const intersect = aliasArrays[i].filter(function (v) { - return aliasArrays[ii].indexOf(v) !== -1 - }) - - if (intersect.length) { - aliasArrays[i] = aliasArrays[i].concat(aliasArrays[ii]) - aliasArrays.splice(ii, 1) - change = true - break - } - } - } - } - - // map arrays back to the hash-lookup (de-dupe while - // we're at it). - aliasArrays.forEach(function (aliasArray) { - aliasArray = aliasArray.filter(function (v, i, self) { - return self.indexOf(v) === i - }) - combined[aliasArray.pop()] = aliasArray - }) - - return combined -} - -// this function should only be called when a count is given as an arg -// it is NOT called to set a default value -// thus we can start the count at 1 instead of 0 -function increment (orig) { - return orig !== undefined ? orig + 1 : 1 -} - -function Parser (args, opts) { - const result = parse(args.slice(), opts) - return result.argv -} - -// parse arguments and return detailed -// meta information, aliases, etc. -Parser.detailed = function (args, opts) { - return parse(args.slice(), opts) -} - -// TODO(bcoe): in the next major version of yargs, switch to -// Object.create(null) for dot notation: -function sanitizeKey (key) { - if (key === '__proto__') return '___proto___' - return key -} - -module.exports = Parser +module.exports = yargsParser diff --git a/lib/common-types.ts b/lib/common-types.ts new file mode 100644 index 00000000..8b02498d --- /dev/null +++ b/lib/common-types.ts @@ -0,0 +1,18 @@ +/** + * An object whose all properties have the same type, where each key is a string. + */ +export interface Dictionary { + [key: string]: T; +} + +/** + * Returns the keys of T. + */ +export type KeyOf = { + [K in keyof T]: string extends K ? never : number extends K ? never : K +} extends { [_ in keyof T]: infer U } ? U : never; + +/** + * Returns the type of a Dictionary or array values. + */ +export type ValueOf = T extends (infer U)[] ? U : T[keyof T]; diff --git a/lib/index.ts b/lib/index.ts new file mode 100644 index 00000000..4166b3b2 --- /dev/null +++ b/lib/index.ts @@ -0,0 +1,1114 @@ +import * as path from 'path' +import * as util from 'util' +import { tokenizeArgString } from './tokenize-arg-string' +import type { + ArgsInput, + Arguments, + ArrayFlagsKey, + ArrayOption, + CoerceCallback, + Configuration, + DefaultValuesForType, + DefaultValuesForTypeKey, + DetailedArguments, + Flag, + Flags, + FlagsKey, + StringFlag, + BooleanFlag, + NumberFlag, + ConfigsFlag, + CoercionsFlag, + Options, + OptionsDefault, + Parser +} from './yargs-parser-types' +import type { Dictionary, ValueOf } from './common-types' +import camelCase = require('camelcase') +import decamelize = require('decamelize') + +export type { Arguments, DetailedArguments, Configuration, Options, Parser } + +function parse (argsInput: ArgsInput, options?: Partial): DetailedArguments { + const opts: Partial = Object.assign({ + alias: undefined, + array: undefined, + boolean: undefined, + config: undefined, + configObjects: undefined, + configuration: undefined, + coerce: undefined, + count: undefined, + default: undefined, + envPrefix: undefined, + narg: undefined, + normalize: undefined, + string: undefined, + number: undefined, + __: undefined, + key: undefined + }, options) + // allow a string argument to be passed in rather + // than an argv array. + const args = tokenizeArgString(argsInput) + + // aliases might have transitive relationships, normalize this. + const aliases = combineAliases(Object.assign(Object.create(null), opts.alias)) + const configuration: Configuration = Object.assign({ + 'boolean-negation': true, + 'camel-case-expansion': true, + 'combine-arrays': false, + 'dot-notation': true, + 'duplicate-arguments-array': true, + 'flatten-duplicate-arrays': true, + 'greedy-arrays': true, + 'halt-at-non-option': false, + 'nargs-eats-options': false, + 'negation-prefix': 'no-', + 'parse-numbers': true, + 'populate--': false, + 'set-placeholder-key': false, + 'short-option-groups': true, + 'strip-aliased': false, + 'strip-dashed': false, + 'unknown-options-as-args': false + }, opts.configuration) + const defaults: OptionsDefault = Object.assign(Object.create(null), opts.default) + const configObjects = opts.configObjects || [] + const envPrefix = opts.envPrefix + const notFlagsOption = configuration['populate--'] + const notFlagsArgv: string = notFlagsOption ? '--' : '_' + const newAliases: Dictionary = Object.create(null) + const defaulted: Dictionary = Object.create(null) + // allow a i18n handler to be passed in, default to a fake one (util.format). + const __ = opts.__ || util.format + const flags: Flags = { + aliases: Object.create(null), + arrays: Object.create(null), + bools: Object.create(null), + strings: Object.create(null), + numbers: Object.create(null), + counts: Object.create(null), + normalize: Object.create(null), + configs: Object.create(null), + nargs: Object.create(null), + coercions: Object.create(null), + keys: [] + } + const negative = /^-([0-9]+(\.[0-9]+)?|\.[0-9]+)$/ + const negatedBoolean = new RegExp('^--' + configuration['negation-prefix'] + '(.+)') + + ;([] as ArrayOption[]).concat(opts.array || []).filter(Boolean).forEach(function (opt) { + const key = typeof opt === 'object' ? opt.key : opt + + // assign to flags[bools|strings|numbers] + const assignment: ArrayFlagsKey | undefined = Object.keys(opt).map(function (key) { + const arrayFlagKeys: Record = { + boolean: 'bools', + string: 'strings', + number: 'numbers' + } + return arrayFlagKeys[key] + }).filter(Boolean).pop() + + // assign key to be coerced + if (assignment) { + flags[assignment][key] = true + } + + flags.arrays[key] = true + flags.keys.push(key) + }) + + ;([] as string[]).concat(opts.boolean || []).filter(Boolean).forEach(function (key) { + flags.bools[key] = true + flags.keys.push(key) + }) + + ;([] as string[]).concat(opts.string || []).filter(Boolean).forEach(function (key) { + flags.strings[key] = true + flags.keys.push(key) + }) + + ;([] as string[]).concat(opts.number || []).filter(Boolean).forEach(function (key) { + flags.numbers[key] = true + flags.keys.push(key) + }) + + ;([] as string[]).concat(opts.count || []).filter(Boolean).forEach(function (key) { + flags.counts[key] = true + flags.keys.push(key) + }) + + ;([] as string[]).concat(opts.normalize || []).filter(Boolean).forEach(function (key) { + flags.normalize[key] = true + flags.keys.push(key) + }) + + if (typeof opts.narg === 'object') { + Object.entries(opts.narg).forEach(([key, value]) => { + if (typeof value === 'number') { + flags.nargs[key] = value + flags.keys.push(key) + } + }) + } + + if (typeof opts.coerce === 'object') { + Object.entries(opts.coerce).forEach(([key, value]) => { + if (typeof value === 'function') { + flags.coercions[key] = value + flags.keys.push(key) + } + }) + } + + if (typeof opts.config !== 'undefined') { + if (Array.isArray(opts.config) || typeof opts.config === 'string') { + ;([] as string[]).concat(opts.config).filter(Boolean).forEach(function (key) { + flags.configs[key] = true + }) + } else if (typeof opts.config === 'object') { + Object.entries(opts.config).forEach(([key, value]) => { + if (typeof value === 'boolean' || typeof value === 'function') { + flags.configs[key] = value + } + }) + } + } + + // create a lookup table that takes into account all + // combinations of aliases: {f: ['foo'], foo: ['f']} + extendAliases(opts.key, aliases, opts.default, flags.arrays) + + // apply default values to all aliases. + Object.keys(defaults).forEach(function (key) { + (flags.aliases[key] || []).forEach(function (alias) { + defaults[alias] = defaults[key] + }) + }) + + let error: Error | null = null + checkConfiguration() + + let notFlags: string[] = [] + + const argv: Arguments = Object.assign(Object.create(null), { _: [] }) + // TODO(bcoe): for the first pass at removing object prototype we didn't + // remove all prototypes from objects returned by this API, we might want + // to gradually move towards doing so. + const argvReturn: { [argName: string]: any } = {} + + for (let i = 0; i < args.length; i++) { + const arg = args[i] + let broken: boolean + let key: string | undefined + let letters: string[] + let m: RegExpMatchArray | null + let next: string + let value: string + + // any unknown option (except for end-of-options, "--") + if (arg !== '--' && isUnknownOptionAsArg(arg)) { + argv._.push(arg) + // -- separated by = + } else if (arg.match(/^--.+=/) || ( + !configuration['short-option-groups'] && arg.match(/^-.+=/) + )) { + // Using [\s\S] instead of . because js doesn't support the + // 'dotall' regex modifier. See: + // http://stackoverflow.com/a/1068308/13216 + m = arg.match(/^--?([^=]+)=([\s\S]*)$/) + + // arrays format = '--f=a b c' + if (m !== null && Array.isArray(m) && m.length >= 3) { + if (checkAllAliases(m[1], flags.arrays)) { + i = eatArray(i, m[1], args, m[2]) + } else if (checkAllAliases(m[1], flags.nargs) !== false) { + // nargs format = '--f=monkey washing cat' + i = eatNargs(i, m[1], args, m[2]) + } else { + setArg(m[1], m[2]) + } + } + } else if (arg.match(negatedBoolean) && configuration['boolean-negation']) { + m = arg.match(negatedBoolean) + if (m !== null && Array.isArray(m) && m.length >= 2) { + key = m[1] + setArg(key, checkAllAliases(key, flags.arrays) ? [false] : false) + } + + // -- separated by space. + } else if (arg.match(/^--.+/) || ( + !configuration['short-option-groups'] && arg.match(/^-[^-]+/) + )) { + m = arg.match(/^--?(.+)/) + if (m !== null && Array.isArray(m) && m.length >= 2) { + key = m[1] + if (checkAllAliases(key, flags.arrays)) { + // array format = '--foo a b c' + i = eatArray(i, key, args) + } else if (checkAllAliases(key, flags.nargs) !== false) { + // nargs format = '--foo a b c' + // should be truthy even if: flags.nargs[key] === 0 + i = eatNargs(i, key, args) + } else { + next = args[i + 1] + + if (next !== undefined && (!next.match(/^-/) || + next.match(negative)) && + !checkAllAliases(key, flags.bools) && + !checkAllAliases(key, flags.counts)) { + setArg(key, next) + i++ + } else if (/^(true|false)$/.test(next)) { + setArg(key, next) + i++ + } else { + setArg(key, defaultValue(key)) + } + } + } + + // dot-notation flag separated by '='. + } else if (arg.match(/^-.\..+=/)) { + m = arg.match(/^-([^=]+)=([\s\S]*)$/) + if (m !== null && Array.isArray(m) && m.length >= 3) { + setArg(m[1], m[2]) + } + + // dot-notation flag separated by space. + } else if (arg.match(/^-.\..+/) && !arg.match(negative)) { + next = args[i + 1] + m = arg.match(/^-(.\..+)/) + if (m !== null && Array.isArray(m) && m.length >= 2) { + key = m[1] + if (next !== undefined && !next.match(/^-/) && + !checkAllAliases(key, flags.bools) && + !checkAllAliases(key, flags.counts)) { + setArg(key, next) + i++ + } else { + setArg(key, defaultValue(key)) + } + } + } else if (arg.match(/^-[^-]+/) && !arg.match(negative)) { + letters = arg.slice(1, -1).split('') + broken = false + + for (let j = 0; j < letters.length; j++) { + next = arg.slice(j + 2) + + if (letters[j + 1] && letters[j + 1] === '=') { + value = arg.slice(j + 3) + key = letters[j] + + if (checkAllAliases(key, flags.arrays)) { + // array format = '-f=a b c' + i = eatArray(i, key, args, value) + } else if (checkAllAliases(key, flags.nargs) !== false) { + // nargs format = '-f=monkey washing cat' + i = eatNargs(i, key, args, value) + } else { + setArg(key, value) + } + + broken = true + break + } + + if (next === '-') { + setArg(letters[j], next) + continue + } + + // current letter is an alphabetic character and next value is a number + if (/[A-Za-z]/.test(letters[j]) && + /^-?\d+(\.\d*)?(e-?\d+)?$/.test(next)) { + setArg(letters[j], next) + broken = true + break + } + + if (letters[j + 1] && letters[j + 1].match(/\W/)) { + setArg(letters[j], next) + broken = true + break + } else { + setArg(letters[j], defaultValue(letters[j])) + } + } + + key = arg.slice(-1)[0] + + if (!broken && key !== '-') { + if (checkAllAliases(key, flags.arrays)) { + // array format = '-f a b c' + i = eatArray(i, key, args) + } else if (checkAllAliases(key, flags.nargs) !== false) { + // nargs format = '-f a b c' + // should be truthy even if: flags.nargs[key] === 0 + i = eatNargs(i, key, args) + } else { + next = args[i + 1] + + if (next !== undefined && (!/^(-|--)[^-]/.test(next) || + next.match(negative)) && + !checkAllAliases(key, flags.bools) && + !checkAllAliases(key, flags.counts)) { + setArg(key, next) + i++ + } else if (/^(true|false)$/.test(next)) { + setArg(key, next) + i++ + } else { + setArg(key, defaultValue(key)) + } + } + } + } else if (arg.match(/^-[0-9]$/) && + arg.match(negative) && + checkAllAliases(arg.slice(1), flags.bools)) { + // single-digit boolean alias, e.g: xargs -0 + key = arg.slice(1) + setArg(key, defaultValue(key)) + } else if (arg === '--') { + notFlags = args.slice(i + 1) + break + } else if (configuration['halt-at-non-option']) { + notFlags = args.slice(i) + break + } else { + const maybeCoercedNumber = maybeCoerceNumber('_', arg) + if (typeof maybeCoercedNumber === 'string' || typeof maybeCoercedNumber === 'number') { + argv._.push(maybeCoercedNumber) + } + } + } + + // order of precedence: + // 1. command line arg + // 2. value from env var + // 3. value from config file + // 4. value from config objects + // 5. configured default value + applyEnvVars(argv, true) // special case: check env vars that point to config file + applyEnvVars(argv, false) + setConfig(argv) + setConfigObjects() + applyDefaultsAndAliases(argv, flags.aliases, defaults, true) + applyCoercions(argv) + if (configuration['set-placeholder-key']) setPlaceholderKeys(argv) + + // for any counts either not in args or without an explicit default, set to 0 + Object.keys(flags.counts).forEach(function (key) { + if (!hasKey(argv, key.split('.'))) setArg(key, 0) + }) + + // '--' defaults to undefined. + if (notFlagsOption && notFlags.length) argv[notFlagsArgv] = [] + notFlags.forEach(function (key) { + argv[notFlagsArgv].push(key) + }) + + if (configuration['camel-case-expansion'] && configuration['strip-dashed']) { + Object.keys(argv).filter(key => key !== '--' && key.includes('-')).forEach(key => { + delete argv[key] + }) + } + + if (configuration['strip-aliased']) { + ;([] as string[]).concat(...Object.keys(aliases).map(k => aliases[k])).forEach(alias => { + if (configuration['camel-case-expansion']) { + delete argv[alias.split('.').map(prop => camelCase(prop)).join('.')] + } + + delete argv[alias] + }) + } + + // how many arguments should we consume, based + // on the nargs option? + function eatNargs (i: number, key: string, args: string[], argAfterEqualSign?: string): number { + let ii + let toEat = checkAllAliases(key, flags.nargs) + // NaN has a special meaning for the array type, indicating that one or + // more values are expected. + toEat = typeof toEat !== 'number' || isNaN(toEat) ? 1 : toEat + + if (toEat === 0) { + if (!isUndefined(argAfterEqualSign)) { + error = Error(__('Argument unexpected for: %s', key)) + } + setArg(key, defaultValue(key)) + return i + } + + let available = isUndefined(argAfterEqualSign) ? 0 : 1 + if (configuration['nargs-eats-options']) { + // classic behavior, yargs eats positional and dash arguments. + if (args.length - (i + 1) + available < toEat) { + error = Error(__('Not enough arguments following: %s', key)) + } + available = toEat + } else { + // nargs will not consume flag arguments, e.g., -abc, --foo, + // and terminates when one is observed. + for (ii = i + 1; ii < args.length; ii++) { + if (!args[ii].match(/^-[^0-9]/) || args[ii].match(negative) || isUnknownOptionAsArg(args[ii])) available++ + else break + } + if (available < toEat) error = Error(__('Not enough arguments following: %s', key)) + } + + let consumed = Math.min(available, toEat) + if (!isUndefined(argAfterEqualSign) && consumed > 0) { + setArg(key, argAfterEqualSign) + consumed-- + } + for (ii = i + 1; ii < (consumed + i + 1); ii++) { + setArg(key, args[ii]) + } + + return (i + consumed) + } + + // if an option is an array, eat all non-hyphenated arguments + // following it... YUM! + // e.g., --foo apple banana cat becomes ["apple", "banana", "cat"] + function eatArray (i: number, key: string, args: string[], argAfterEqualSign?: string): number { + let argsToSet = [] + let next = argAfterEqualSign || args[i + 1] + // If both array and nargs are configured, enforce the nargs count: + const nargsCount = checkAllAliases(key, flags.nargs) + + if (checkAllAliases(key, flags.bools) && !(/^(true|false)$/.test(next))) { + argsToSet.push(true) + } else if (isUndefined(next) || + (isUndefined(argAfterEqualSign) && /^-/.test(next) && !negative.test(next) && !isUnknownOptionAsArg(next))) { + // for keys without value ==> argsToSet remains an empty [] + // set user default value, if available + if (defaults[key] !== undefined) { + const defVal = defaults[key] + argsToSet = Array.isArray(defVal) ? defVal : [defVal] + } + } else { + // value in --option=value is eaten as is + if (!isUndefined(argAfterEqualSign)) { + argsToSet.push(processValue(key, argAfterEqualSign)) + } + for (let ii = i + 1; ii < args.length; ii++) { + if ((!configuration['greedy-arrays'] && argsToSet.length > 0) || + (nargsCount && typeof nargsCount === 'number' && argsToSet.length >= nargsCount)) break + next = args[ii] + if (/^-/.test(next) && !negative.test(next) && !isUnknownOptionAsArg(next)) break + i = ii + argsToSet.push(processValue(key, next)) + } + } + + // If both array and nargs are configured, create an error if less than + // nargs positionals were found. NaN has special meaning, indicating + // that at least one value is required (more are okay). + if (typeof nargsCount === 'number' && ((nargsCount && argsToSet.length < nargsCount) || + (isNaN(nargsCount) && argsToSet.length === 0))) { + error = Error(__('Not enough arguments following: %s', key)) + } + + setArg(key, argsToSet) + return i + } + + function setArg (key: string, val: any): void { + if (/-/.test(key) && configuration['camel-case-expansion']) { + const alias = key.split('.').map(function (prop) { + return camelCase(prop) + }).join('.') + addNewAlias(key, alias) + } + + const value = processValue(key, val) + const splitKey = key.split('.') + setKey(argv, splitKey, value) + + // handle populating aliases of the full key + if (flags.aliases[key]) { + flags.aliases[key].forEach(function (x) { + const keyProperties = x.split('.') + setKey(argv, keyProperties, value) + }) + } + + // handle populating aliases of the first element of the dot-notation key + if (splitKey.length > 1 && configuration['dot-notation']) { + ;(flags.aliases[splitKey[0]] || []).forEach(function (x) { + let keyProperties = x.split('.') + + // expand alias with nested objects in key + const a = ([] as string[]).concat(splitKey) + a.shift() // nuke the old key. + keyProperties = keyProperties.concat(a) + + // populate alias only if is not already an alias of the full key + // (already populated above) + if (!(flags.aliases[key] || []).includes(keyProperties.join('.'))) { + setKey(argv, keyProperties, value) + } + }) + } + + // Set normalize getter and setter when key is in 'normalize' but isn't an array + if (checkAllAliases(key, flags.normalize) && !checkAllAliases(key, flags.arrays)) { + const keys = [key].concat(flags.aliases[key] || []) + keys.forEach(function (key) { + Object.defineProperty(argvReturn, key, { + enumerable: true, + get () { + return val + }, + set (value) { + val = typeof value === 'string' ? path.normalize(value) : value + } + }) + }) + } + } + + function addNewAlias (key: string, alias: string): void { + if (!(flags.aliases[key] && flags.aliases[key].length)) { + flags.aliases[key] = [alias] + newAliases[alias] = true + } + if (!(flags.aliases[alias] && flags.aliases[alias].length)) { + addNewAlias(alias, key) + } + } + + function processValue (key: string, val: any) { + // strings may be quoted, clean this up as we assign values. + if (typeof val === 'string' && + (val[0] === "'" || val[0] === '"') && + val[val.length - 1] === val[0] + ) { + val = val.substring(1, val.length - 1) + } + + // handle parsing boolean arguments --foo=true --bar false. + if (checkAllAliases(key, flags.bools) || checkAllAliases(key, flags.counts)) { + if (typeof val === 'string') val = val === 'true' + } + + let value = Array.isArray(val) + ? val.map(function (v) { return maybeCoerceNumber(key, v) }) + : maybeCoerceNumber(key, val) + + // increment a count given as arg (either no value or value parsed as boolean) + if (checkAllAliases(key, flags.counts) && (isUndefined(value) || typeof value === 'boolean')) { + value = increment() + } + + // Set normalized value when key is in 'normalize' and in 'arrays' + if (checkAllAliases(key, flags.normalize) && checkAllAliases(key, flags.arrays)) { + if (Array.isArray(val)) value = val.map(path.normalize) + else value = path.normalize(val) + } + return value + } + + function maybeCoerceNumber (key: string, value: string | number | null | undefined) { + if (!checkAllAliases(key, flags.strings) && !checkAllAliases(key, flags.bools) && !Array.isArray(value)) { + const shouldCoerceNumber = isNumber(value) && configuration['parse-numbers'] && ( + Number.isSafeInteger(Math.floor(parseFloat(`${value}`))) + ) + if (shouldCoerceNumber || (!isUndefined(value) && checkAllAliases(key, flags.numbers))) value = Number(value) + } + return value + } + + // set args from config.json file, this should be + // applied last so that defaults can be applied. + function setConfig (argv: Arguments): void { + const configLookup = Object.create(null) + + // expand defaults/aliases, in-case any happen to reference + // the config.json file. + applyDefaultsAndAliases(configLookup, flags.aliases, defaults) + + Object.keys(flags.configs).forEach(function (configKey) { + const configPath = argv[configKey] || configLookup[configKey] + if (configPath) { + try { + let config = null + const resolvedConfigPath = path.resolve(process.cwd(), configPath) + const resolveConfig = flags.configs[configKey] + + if (typeof resolveConfig === 'function') { + try { + config = resolveConfig(resolvedConfigPath) + } catch (e) { + config = e + } + if (config instanceof Error) { + error = config + return + } + } else { + config = require(resolvedConfigPath) + } + + setConfigObject(config) + } catch (ex) { + if (argv[configKey]) error = Error(__('Invalid JSON config file: %s', configPath)) + } + } + }) + } + + // set args from config object. + // it recursively checks nested objects. + function setConfigObject (config: { [key: string]: any }, prev?: string): void { + Object.keys(config).forEach(function (key) { + const value = config[key] + const fullKey = prev ? prev + '.' + key : key + + // if the value is an inner object and we have dot-notation + // enabled, treat inner objects in config the same as + // heavily nested dot notations (foo.bar.apple). + if (typeof value === 'object' && value !== null && !Array.isArray(value) && configuration['dot-notation']) { + // if the value is an object but not an array, check nested object + setConfigObject(value, fullKey) + } else { + // setting arguments via CLI takes precedence over + // values within the config file. + if (!hasKey(argv, fullKey.split('.')) || (checkAllAliases(fullKey, flags.arrays) && configuration['combine-arrays'])) { + setArg(fullKey, value) + } + } + }) + } + + // set all config objects passed in opts + function setConfigObjects (): void { + if (typeof configObjects !== 'undefined') { + configObjects.forEach(function (configObject) { + setConfigObject(configObject) + }) + } + } + + function applyEnvVars (argv: Arguments, configOnly: boolean): void { + if (process) { + if (typeof envPrefix === 'undefined') return + + const prefix = typeof envPrefix === 'string' ? envPrefix : '' + Object.keys(process.env).forEach(function (envVar) { + if (prefix === '' || envVar.lastIndexOf(prefix, 0) === 0) { + // get array of nested keys and convert them to camel case + const keys = envVar.split('__').map(function (key, i) { + if (i === 0) { + key = key.substring(prefix.length) + } + return camelCase(key) + }) + + if (((configOnly && flags.configs[keys.join('.')]) || !configOnly) && !hasKey(argv, keys)) { + setArg(keys.join('.'), process.env[envVar]) + } + } + }) + } + } + + function applyCoercions (argv: Arguments): void { + let coerce: false | CoerceCallback + const applied: Set = new Set() + Object.keys(argv).forEach(function (key) { + if (!applied.has(key)) { // If we haven't already coerced this option via one of its aliases + coerce = checkAllAliases(key, flags.coercions) + if (typeof coerce === 'function') { + try { + const value = maybeCoerceNumber(key, coerce(argv[key])) + ;(([] as string[]).concat(flags.aliases[key] || [], key)).forEach(ali => { + applied.add(ali) + argv[ali] = value + }) + } catch (err) { + error = err + } + } + } + }) + } + + function setPlaceholderKeys (argv: Arguments): Arguments { + flags.keys.forEach((key) => { + // don't set placeholder keys for dot notation options 'foo.bar'. + if (~key.indexOf('.')) return + if (typeof argv[key] === 'undefined') argv[key] = undefined + }) + return argv + } + + function applyDefaultsAndAliases (obj: { [key: string]: any }, aliases: { [key: string]: string[] }, defaults: { [key: string]: any }, canLog: boolean = false): void { + Object.keys(defaults).forEach(function (key) { + if (!hasKey(obj, key.split('.'))) { + setKey(obj, key.split('.'), defaults[key]) + if (canLog) defaulted[key] = true + + ;(aliases[key] || []).forEach(function (x) { + if (hasKey(obj, x.split('.'))) return + setKey(obj, x.split('.'), defaults[key]) + }) + } + }) + } + + function hasKey (obj: { [key: string]: any }, keys: string[]): boolean { + let o = obj + + if (!configuration['dot-notation']) keys = [keys.join('.')] + + keys.slice(0, -1).forEach(function (key) { + o = (o[key] || {}) + }) + + const key = keys[keys.length - 1] + + if (typeof o !== 'object') return false + else return key in o + } + + function setKey (obj: { [key: string]: any }, keys: string[], value: any): void { + let o = obj + + if (!configuration['dot-notation']) keys = [keys.join('.')] + + keys.slice(0, -1).forEach(function (key) { + // TODO(bcoe): in the next major version of yargs, switch to + // Object.create(null) for dot notation: + key = sanitizeKey(key) + + if (typeof o === 'object' && o[key] === undefined) { + o[key] = {} + } + + if (typeof o[key] !== 'object' || Array.isArray(o[key])) { + // ensure that o[key] is an array, and that the last item is an empty object. + if (Array.isArray(o[key])) { + o[key].push({}) + } else { + o[key] = [o[key], {}] + } + + // we want to update the empty object at the end of the o[key] array, so set o to that object + o = o[key][o[key].length - 1] + } else { + o = o[key] + } + }) + + // TODO(bcoe): in the next major version of yargs, switch to + // Object.create(null) for dot notation: + const key = sanitizeKey(keys[keys.length - 1]) + + const isTypeArray = checkAllAliases(keys.join('.'), flags.arrays) + const isValueArray = Array.isArray(value) + let duplicate = configuration['duplicate-arguments-array'] + + // nargs has higher priority than duplicate + if (!duplicate && checkAllAliases(key, flags.nargs)) { + duplicate = true + if ((!isUndefined(o[key]) && flags.nargs[key] === 1) || (Array.isArray(o[key]) && o[key].length === flags.nargs[key])) { + o[key] = undefined + } + } + + if (value === increment()) { + o[key] = increment(o[key]) + } else if (Array.isArray(o[key])) { + if (duplicate && isTypeArray && isValueArray) { + o[key] = configuration['flatten-duplicate-arrays'] ? o[key].concat(value) : (Array.isArray(o[key][0]) ? o[key] : [o[key]]).concat([value]) + } else if (!duplicate && Boolean(isTypeArray) === Boolean(isValueArray)) { + o[key] = value + } else { + o[key] = o[key].concat([value]) + } + } else if (o[key] === undefined && isTypeArray) { + o[key] = isValueArray ? value : [value] + } else if (duplicate && !( + o[key] === undefined || + checkAllAliases(key, flags.counts) || + checkAllAliases(key, flags.bools) + )) { + o[key] = [o[key], value] + } else { + o[key] = value + } + } + + // extend the aliases list with inferred aliases. + function extendAliases (...args: Array<{ [key: string]: any } | undefined>) { + args.forEach(function (obj) { + Object.keys(obj || {}).forEach(function (key) { + // short-circuit if we've already added a key + // to the aliases array, for example it might + // exist in both 'opts.default' and 'opts.key'. + if (flags.aliases[key]) return + + flags.aliases[key] = ([] as string[]).concat(aliases[key] || []) + // For "--option-name", also set argv.optionName + flags.aliases[key].concat(key).forEach(function (x) { + if (/-/.test(x) && configuration['camel-case-expansion']) { + const c = camelCase(x) + if (c !== key && flags.aliases[key].indexOf(c) === -1) { + flags.aliases[key].push(c) + newAliases[c] = true + } + } + }) + // For "--optionName", also set argv['option-name'] + flags.aliases[key].concat(key).forEach(function (x) { + if (x.length > 1 && /[A-Z]/.test(x) && configuration['camel-case-expansion']) { + const c = decamelize(x, '-') + if (c !== key && flags.aliases[key].indexOf(c) === -1) { + flags.aliases[key].push(c) + newAliases[c] = true + } + } + }) + flags.aliases[key].forEach(function (x) { + flags.aliases[x] = [key].concat(flags.aliases[key].filter(function (y) { + return x !== y + })) + }) + }) + }) + } + + // return the 1st set flag for any of a key's aliases (or false if no flag set) + function checkAllAliases (key: string, flag: StringFlag): ValueOf | false + function checkAllAliases (key: string, flag: BooleanFlag): ValueOf | false + function checkAllAliases (key: string, flag: NumberFlag): ValueOf | false + function checkAllAliases (key: string, flag: ConfigsFlag): ValueOf | false + function checkAllAliases (key: string, flag: CoercionsFlag): ValueOf | false + function checkAllAliases (key: string, flag: Flag): ValueOf | false { + const toCheck = ([] as string[]).concat(flags.aliases[key] || [], key) + const keys = Object.keys(flag) + const setAlias = toCheck.find(key => keys.includes(key)) + return setAlias ? flag[setAlias] : false + } + + function hasAnyFlag (key: string): boolean { + const flagsKeys = Object.keys(flags) as FlagsKey[] + const toCheck = ([] as Array<{ [key: string]: any } | string[]>).concat(flagsKeys.map(k => flags[k])) + return toCheck.some(function (flag) { + return Array.isArray(flag) ? flag.includes(key) : flag[key] + }) + } + + function hasFlagsMatching (arg: string, ...patterns: RegExp[]): boolean { + const toCheck = ([] as RegExp[]).concat(...patterns) + return toCheck.some(function (pattern) { + const match = arg.match(pattern) + return match && hasAnyFlag(match[1]) + }) + } + + // based on a simplified version of the short flag group parsing logic + function hasAllShortFlags (arg: string): boolean { + // if this is a negative number, or doesn't start with a single hyphen, it's not a short flag group + if (arg.match(negative) || !arg.match(/^-[^-]+/)) { return false } + let hasAllFlags = true + let next: string + const letters = arg.slice(1).split('') + for (let j = 0; j < letters.length; j++) { + next = arg.slice(j + 2) + + if (!hasAnyFlag(letters[j])) { + hasAllFlags = false + break + } + + if ((letters[j + 1] && letters[j + 1] === '=') || + next === '-' || + (/[A-Za-z]/.test(letters[j]) && /^-?\d+(\.\d*)?(e-?\d+)?$/.test(next)) || + (letters[j + 1] && letters[j + 1].match(/\W/))) { + break + } + } + return hasAllFlags + } + + function isUnknownOptionAsArg (arg: string): boolean { + return configuration['unknown-options-as-args'] && isUnknownOption(arg) + } + + function isUnknownOption (arg: string): boolean { + // ignore negative numbers + if (arg.match(negative)) { return false } + // if this is a short option group and all of them are configured, it isn't unknown + if (hasAllShortFlags(arg)) { return false } + // e.g. '--count=2' + const flagWithEquals = /^-+([^=]+?)=[\s\S]*$/ + // e.g. '-a' or '--arg' + const normalFlag = /^-+([^=]+?)$/ + // e.g. '-a-' + const flagEndingInHyphen = /^-+([^=]+?)-$/ + // e.g. '-abc123' + const flagEndingInDigits = /^-+([^=]+?\d+)$/ + // e.g. '-a/usr/local' + const flagEndingInNonWordCharacters = /^-+([^=]+?)\W+.*$/ + // check the different types of flag styles, including negatedBoolean, a pattern defined near the start of the parse method + return !hasFlagsMatching(arg, flagWithEquals, negatedBoolean, normalFlag, flagEndingInHyphen, flagEndingInDigits, flagEndingInNonWordCharacters) + } + + // make a best effort to pick a default value + // for an option based on name and type. + function defaultValue (key: string) { + if (!checkAllAliases(key, flags.bools) && + !checkAllAliases(key, flags.counts) && + `${key}` in defaults) { + return defaults[key] + } else { + return defaultForType(guessType(key)) + } + } + + // return a default value, given the type of a flag., + function defaultForType (type: K): DefaultValuesForType[K] { + const def: DefaultValuesForType = { + boolean: true, + string: '', + number: undefined, + array: [] + } + + return def[type] + } + + // given a flag, enforce a default type. + function guessType (key: string): DefaultValuesForTypeKey { + let type: DefaultValuesForTypeKey = 'boolean' + if (checkAllAliases(key, flags.strings)) type = 'string' + else if (checkAllAliases(key, flags.numbers)) type = 'number' + else if (checkAllAliases(key, flags.bools)) type = 'boolean' + else if (checkAllAliases(key, flags.arrays)) type = 'array' + return type + } + + function isNumber (x: null | undefined | number | string): boolean { + if (x === null || x === undefined) return false + // if loaded from config, may already be a number. + if (typeof x === 'number') return true + // hexadecimal. + if (/^0x[0-9a-f]+$/i.test(x)) return true + // don't treat 0123 as a number; as it drops the leading '0'. + if (x.length > 1 && x[0] === '0') return false + return /^[-]?(?:\d+(?:\.\d*)?|\.\d+)(e[-+]?\d+)?$/.test(x) + } + + function isUndefined (num: any): num is undefined { + return num === undefined + } + + // check user configuration settings for inconsistencies + function checkConfiguration (): void { + // count keys should not be set as array/narg + Object.keys(flags.counts).find(key => { + if (checkAllAliases(key, flags.arrays)) { + error = Error(__('Invalid configuration: %s, opts.count excludes opts.array.', key)) + return true + } else if (checkAllAliases(key, flags.nargs)) { + error = Error(__('Invalid configuration: %s, opts.count excludes opts.narg.', key)) + return true + } + return false + }) + } + + return { + argv: Object.assign(argvReturn, argv), + error: error, + aliases: Object.assign({}, flags.aliases), + newAliases: Object.assign({}, newAliases), + defaulted: Object.assign({}, defaulted), + configuration: configuration + } +} + +// if any aliases reference each other, we should +// merge them together. +function combineAliases (aliases: Dictionary): Dictionary { + const aliasArrays: Array = [] + const combined: Dictionary = Object.create(null) + let change = true + + // turn alias lookup hash {key: ['alias1', 'alias2']} into + // a simple array ['key', 'alias1', 'alias2'] + Object.keys(aliases).forEach(function (key) { + aliasArrays.push( + ([] as string[]).concat(aliases[key], key) + ) + }) + + // combine arrays until zero changes are + // made in an iteration. + while (change) { + change = false + for (let i = 0; i < aliasArrays.length; i++) { + for (let ii = i + 1; ii < aliasArrays.length; ii++) { + const intersect = aliasArrays[i].filter(function (v) { + return aliasArrays[ii].indexOf(v) !== -1 + }) + + if (intersect.length) { + aliasArrays[i] = aliasArrays[i].concat(aliasArrays[ii]) + aliasArrays.splice(ii, 1) + change = true + break + } + } + } + } + + // map arrays back to the hash-lookup (de-dupe while + // we're at it). + aliasArrays.forEach(function (aliasArray) { + aliasArray = aliasArray.filter(function (v, i, self) { + return self.indexOf(v) === i + }) + const lastAlias = aliasArray.pop() + if (lastAlias !== undefined && typeof lastAlias === 'string') { + combined[lastAlias] = aliasArray + } + }) + + return combined +} + +// this function should only be called when a count is given as an arg +// it is NOT called to set a default value +// thus we can start the count at 1 instead of 0 +function increment (orig?: number | undefined): number { + return orig !== undefined ? orig + 1 : 1 +} + +// TODO(bcoe): in the next major version of yargs, switch to +// Object.create(null) for dot notation: +function sanitizeKey (key: string): string { + if (key === '__proto__') return '___proto___' + return key +} + +const yargsParser: Parser = function Parser (args: ArgsInput, opts?: Partial): Arguments { + const result = parse(args.slice(), opts) + return result.argv +} + +// parse arguments and return detailed +// meta information, aliases, etc. +yargsParser.detailed = function (args: ArgsInput, opts?: Partial): DetailedArguments { + return parse(args.slice(), opts) +} + +export { yargsParser } diff --git a/lib/yargs-parser-types.ts b/lib/yargs-parser-types.ts new file mode 100644 index 00000000..6e218948 --- /dev/null +++ b/lib/yargs-parser-types.ts @@ -0,0 +1,159 @@ +import type { Dictionary, KeyOf, ValueOf } from './common-types' + +export type ArgsInput = string | any[]; + +export type ArgsOutput = (string | number)[]; + +export interface Arguments { + /** Non-option arguments */ + _: ArgsOutput; + /** Arguments after the end-of-options flag `--` */ + '--'?: ArgsOutput; + /** All remaining options */ + [argName: string]: any; +} + +export interface DetailedArguments { + /** An object representing the parsed value of `args` */ + argv: Arguments; + /** Populated with an error object if an exception occurred during parsing. */ + error: Error | null; + /** The inferred list of aliases built by combining lists in opts.alias. */ + aliases: Dictionary; + /** Any new aliases added via camel-case expansion. */ + newAliases: Dictionary; + /** Any new argument created by opts.default, no aliases included. */ + defaulted: Dictionary; + /** The configuration loaded from the yargs stanza in package.json. */ + configuration: Configuration; +} + +export interface Configuration { + /** Should variables prefixed with --no be treated as negations? Default is `true` */ + 'boolean-negation': boolean; + /** Should hyphenated arguments be expanded into camel-case aliases? Default is `true` */ + 'camel-case-expansion': boolean; + /** Should arrays be combined when provided by both command line arguments and a configuration file? Default is `false` */ + 'combine-arrays': boolean; + /** Should keys that contain `.` be treated as objects? Default is `true` */ + 'dot-notation': boolean; + /** Should arguments be coerced into an array when duplicated? Default is `true` */ + 'duplicate-arguments-array': boolean; + /** Should array arguments be coerced into a single array when duplicated? Default is `true` */ + 'flatten-duplicate-arrays': boolean; + /** Should arrays consume more than one positional argument following their flag? Default is `true` */ + 'greedy-arrays': boolean; + /** Should parsing stop at the first text argument? This is similar to how e.g. ssh parses its command line. Default is `false` */ + 'halt-at-non-option': boolean; + /** Should nargs consume dash options as well as positional arguments? Default is `false` */ + 'nargs-eats-options': boolean; + /** The prefix to use for negated boolean variables. Default is `'no-'` */ + 'negation-prefix': string; + /** Should keys that look like numbers be treated as such? Default is `true` */ + 'parse-numbers': boolean; + /** Should unparsed flags be stored in -- or _? Default is `false` */ + 'populate--': boolean; + /** Should a placeholder be added for keys not set via the corresponding CLI argument? Default is `false` */ + 'set-placeholder-key': boolean; + /** Should a group of short-options be treated as boolean flags? Default is `true` */ + 'short-option-groups': boolean; + /** Should aliases be removed before returning results? Default is `false` */ + 'strip-aliased': boolean; + /** Should dashed keys be removed before returning results? This option has no effect if camel-case-expansion is disabled. Default is `false` */ + 'strip-dashed': boolean; + /** Should unknown options be treated like regular arguments? An unknown option is one that is not configured in opts. Default is `false` */ + 'unknown-options-as-args': boolean; +} + +export type ArrayOption = string | { key: string; boolean?: boolean, string?: boolean, number?: boolean, integer?: boolean }; + +export type CoerceCallback = (arg: any) => any; + +export type ConfigCallback = (configPath: string) => { [key: string]: any } | Error; + +export interface Options { + /** An object representing the set of aliases for a key: `{ alias: { foo: ['f']} }`. */ + alias: Dictionary; + /** + * Indicate that keys should be parsed as an array: `{ array: ['foo', 'bar'] }`. + * Indicate that keys should be parsed as an array and coerced to booleans / numbers: + * { array: [ { key: 'foo', boolean: true }, {key: 'bar', number: true} ] }`. + */ + array: ArrayOption | ArrayOption[]; + /** Arguments should be parsed as booleans: `{ boolean: ['x', 'y'] }`. */ + boolean: string | string[]; + /** Indicate a key that represents a path to a configuration file (this file will be loaded and parsed). */ + config: string | string[] | Dictionary; + /** configuration objects to parse, their properties will be set as arguments */ + configObjects: Dictionary[]; + /** Provide configuration options to the yargs-parser. */ + configuration: Partial; + /** + * Provide a custom synchronous function that returns a coerced value from the argument provided (or throws an error), e.g. + * `{ coerce: { foo: function (arg) { return modifiedArg } } }`. + */ + coerce: Dictionary; + /** Indicate a key that should be used as a counter, e.g., `-vvv = {v: 3}`. */ + count: string | string[]; + /** Provide default values for keys: `{ default: { x: 33, y: 'hello world!' } }`. */ + default: Dictionary; + /** Environment variables (`process.env`) with the prefix provided should be parsed. */ + envPrefix: string; + /** Specify that a key requires n arguments: `{ narg: {x: 2} }`. */ + narg: Dictionary; + /** `path.normalize()` will be applied to values set to this key. */ + normalize: string | string[]; + /** Keys should be treated as strings (even if they resemble a number `-x 33`). */ + string: string | string[]; + /** Keys should be treated as numbers. */ + number: string | string[]; + /** i18n handler, defaults to util.format */ + __: (format: any, ...param: any[]) => string; + /** alias lookup table defaults */ + key: Dictionary; +} + +export type OptionsDefault = ValueOf, 'default'>>; + +export interface Parser { + (args: ArgsInput, opts?: Options): Arguments; + detailed(args: ArgsInput, opts?: Options): DetailedArguments; +} + +export type StringFlag = Dictionary; +export type BooleanFlag = Dictionary; +export type NumberFlag = Dictionary; +export type ConfigsFlag = Dictionary; +export type CoercionsFlag = Dictionary; +export type KeysFlag = string[]; + +export interface Flags { + aliases: StringFlag; + arrays: BooleanFlag; + bools: BooleanFlag; + strings: BooleanFlag; + numbers: BooleanFlag; + counts: BooleanFlag; + normalize: BooleanFlag; + configs: ConfigsFlag; + nargs: NumberFlag; + coercions: CoercionsFlag; + keys: KeysFlag; +} + +export type Flag = ValueOf>; + +export type FlagValue = ValueOf; + +export type FlagsKey = KeyOf>; + +export type ArrayFlagsKey = Extract; + +export interface DefaultValuesForType { + boolean: boolean; + string: string; + number: undefined; + array: any[]; +} + +export type DefaultValuesForTypeKey = KeyOf; diff --git a/test/yargs-parser.js b/test/yargs-parser.js index e017a08b..0705a389 100644 --- a/test/yargs-parser.js +++ b/test/yargs-parser.js @@ -2067,6 +2067,26 @@ describe('yargs-parser', function () { result.foo.should.eql('a') }) + + it('should ignore undefined configured nargs', function () { + var result = parser(['--foo', 'a', 'b'], { + narg: { + foo: undefined + } + }) + + result.foo.should.eql('a') + }) + + it('should default to 1 if configured narg is NaN', function () { + var result = parser(['--foo', 'a', 'b'], { + narg: { + foo: NaN + } + }) + + result.foo.should.eql('a') + }) }) describe('env vars', function () { @@ -2081,6 +2101,29 @@ describe('yargs-parser', function () { result.redFish.should.equal('bluefish') }) + // envPrefix falls back to empty string if not a string + it('should apply all env vars if prefix is not a string', function () { + process.env.ONE_FISH = 'twofish' + process.env.RED_FISH = 'bluefish' + var result = parser([], { + envPrefix: null + }) + + result.oneFish.should.equal('twofish') + result.redFish.should.equal('bluefish') + }) + + it('should not apply all env vars if prefix is undefined', function () { + process.env.ONE_FISH = 'twofish' + process.env.RED_FISH = 'bluefish' + var result = parser([], { + envPrefix: undefined + }) + + expect(result).to.not.have.property('oneFish') + expect(result).to.not.have.property('redFish') + }) + it('should apply only env vars matching prefix if prefix is valid string', function () { process.env.ONE_FISH = 'twofish' process.env.RED_FISH = 'bluefish' @@ -2883,6 +2926,18 @@ describe('yargs-parser', function () { parsed.should.not.have.property('b') parsed.should.not.have.property('a.b') }) + + it('should not set placeholder key with dot notation when `set-placeholder-key` is `true`', function () { + var parsed = parser([], { + string: ['a.b'], + configuration: { + 'set-placeholder-key': true + } + }) + parsed.should.not.have.property('a') + parsed.should.not.have.property('b') + parsed.should.not.have.property('a.b') + }) }) describe('halt-at-non-option', function () {