| import { assertNotStrictEqual, } from './typings/common-types.js'; |
| import { objFilter } from './utils/obj-filter.js'; |
| import { YError } from './yerror.js'; |
| import setBlocking from './utils/set-blocking.js'; |
| export function usage(yargs, y18n, shim) { |
| const __ = y18n.__; |
| const self = {}; |
| const fails = []; |
| self.failFn = function failFn(f) { |
| fails.push(f); |
| }; |
| let failMessage = null; |
| let showHelpOnFail = true; |
| self.showHelpOnFail = function showHelpOnFailFn(arg1 = true, arg2) { |
| function parseFunctionArgs() { |
| return typeof arg1 === 'string' ? [true, arg1] : [arg1, arg2]; |
| } |
| const [enabled, message] = parseFunctionArgs(); |
| failMessage = message; |
| showHelpOnFail = enabled; |
| return self; |
| }; |
| let failureOutput = false; |
| self.fail = function fail(msg, err) { |
| const logger = yargs._getLoggerInstance(); |
| if (fails.length) { |
| for (let i = fails.length - 1; i >= 0; --i) { |
| fails[i](msg, err, self); |
| } |
| } |
| else { |
| if (yargs.getExitProcess()) |
| setBlocking(true); |
| if (!failureOutput) { |
| failureOutput = true; |
| if (showHelpOnFail) { |
| yargs.showHelp('error'); |
| logger.error(); |
| } |
| if (msg || err) |
| logger.error(msg || err); |
| if (failMessage) { |
| if (msg || err) |
| logger.error(''); |
| logger.error(failMessage); |
| } |
| } |
| err = err || new YError(msg); |
| if (yargs.getExitProcess()) { |
| return yargs.exit(1); |
| } |
| else if (yargs._hasParseCallback()) { |
| return yargs.exit(1, err); |
| } |
| else { |
| throw err; |
| } |
| } |
| }; |
| let usages = []; |
| let usageDisabled = false; |
| self.usage = (msg, description) => { |
| if (msg === null) { |
| usageDisabled = true; |
| usages = []; |
| return self; |
| } |
| usageDisabled = false; |
| usages.push([msg, description || '']); |
| return self; |
| }; |
| self.getUsage = () => { |
| return usages; |
| }; |
| self.getUsageDisabled = () => { |
| return usageDisabled; |
| }; |
| self.getPositionalGroupName = () => { |
| return __('Positionals:'); |
| }; |
| let examples = []; |
| self.example = (cmd, description) => { |
| examples.push([cmd, description || '']); |
| }; |
| let commands = []; |
| self.command = function command(cmd, description, isDefault, aliases, deprecated = false) { |
| if (isDefault) { |
| commands = commands.map(cmdArray => { |
| cmdArray[2] = false; |
| return cmdArray; |
| }); |
| } |
| commands.push([cmd, description || '', isDefault, aliases, deprecated]); |
| }; |
| self.getCommands = () => commands; |
| let descriptions = {}; |
| self.describe = function describe(keyOrKeys, desc) { |
| if (Array.isArray(keyOrKeys)) { |
| keyOrKeys.forEach(k => { |
| self.describe(k, desc); |
| }); |
| } |
| else if (typeof keyOrKeys === 'object') { |
| Object.keys(keyOrKeys).forEach(k => { |
| self.describe(k, keyOrKeys[k]); |
| }); |
| } |
| else { |
| descriptions[keyOrKeys] = desc; |
| } |
| }; |
| self.getDescriptions = () => descriptions; |
| let epilogs = []; |
| self.epilog = msg => { |
| epilogs.push(msg); |
| }; |
| let wrapSet = false; |
| let wrap; |
| self.wrap = cols => { |
| wrapSet = true; |
| wrap = cols; |
| }; |
| function getWrap() { |
| if (!wrapSet) { |
| wrap = windowWidth(); |
| wrapSet = true; |
| } |
| return wrap; |
| } |
| const deferY18nLookupPrefix = '__yargsString__:'; |
| self.deferY18nLookup = str => deferY18nLookupPrefix + str; |
| self.help = function help() { |
| if (cachedHelpMessage) |
| return cachedHelpMessage; |
| normalizeAliases(); |
| const base$0 = yargs.customScriptName |
| ? yargs.$0 |
| : shim.path.basename(yargs.$0); |
| const demandedOptions = yargs.getDemandedOptions(); |
| const demandedCommands = yargs.getDemandedCommands(); |
| const deprecatedOptions = yargs.getDeprecatedOptions(); |
| const groups = yargs.getGroups(); |
| const options = yargs.getOptions(); |
| let keys = []; |
| keys = keys.concat(Object.keys(descriptions)); |
| keys = keys.concat(Object.keys(demandedOptions)); |
| keys = keys.concat(Object.keys(demandedCommands)); |
| keys = keys.concat(Object.keys(options.default)); |
| keys = keys.filter(filterHiddenOptions); |
| keys = Object.keys(keys.reduce((acc, key) => { |
| if (key !== '_') |
| acc[key] = true; |
| return acc; |
| }, {})); |
| const theWrap = getWrap(); |
| const ui = shim.cliui({ |
| width: theWrap, |
| wrap: !!theWrap, |
| }); |
| if (!usageDisabled) { |
| if (usages.length) { |
| usages.forEach(usage => { |
| ui.div(`${usage[0].replace(/\$0/g, base$0)}`); |
| if (usage[1]) { |
| ui.div({ text: `${usage[1]}`, padding: [1, 0, 0, 0] }); |
| } |
| }); |
| ui.div(); |
| } |
| else if (commands.length) { |
| let u = null; |
| if (demandedCommands._) { |
| u = `${base$0} <${__('command')}>\n`; |
| } |
| else { |
| u = `${base$0} [${__('command')}]\n`; |
| } |
| ui.div(`${u}`); |
| } |
| } |
| if (commands.length) { |
| ui.div(__('Commands:')); |
| const context = yargs.getContext(); |
| const parentCommands = context.commands.length |
| ? `${context.commands.join(' ')} ` |
| : ''; |
| if (yargs.getParserConfiguration()['sort-commands'] === true) { |
| commands = commands.sort((a, b) => a[0].localeCompare(b[0])); |
| } |
| commands.forEach(command => { |
| const commandString = `${base$0} ${parentCommands}${command[0].replace(/^\$0 ?/, '')}`; |
| ui.span({ |
| text: commandString, |
| padding: [0, 2, 0, 2], |
| width: maxWidth(commands, theWrap, `${base$0}${parentCommands}`) + 4, |
| }, { text: command[1] }); |
| const hints = []; |
| if (command[2]) |
| hints.push(`[${__('default')}]`); |
| if (command[3] && command[3].length) { |
| hints.push(`[${__('aliases:')} ${command[3].join(', ')}]`); |
| } |
| if (command[4]) { |
| if (typeof command[4] === 'string') { |
| hints.push(`[${__('deprecated: %s', command[4])}]`); |
| } |
| else { |
| hints.push(`[${__('deprecated')}]`); |
| } |
| } |
| if (hints.length) { |
| ui.div({ |
| text: hints.join(' '), |
| padding: [0, 0, 0, 2], |
| align: 'right', |
| }); |
| } |
| else { |
| ui.div(); |
| } |
| }); |
| ui.div(); |
| } |
| const aliasKeys = (Object.keys(options.alias) || []).concat(Object.keys(yargs.parsed.newAliases) || []); |
| keys = keys.filter(key => !yargs.parsed.newAliases[key] && |
| aliasKeys.every(alias => (options.alias[alias] || []).indexOf(key) === -1)); |
| const defaultGroup = __('Options:'); |
| if (!groups[defaultGroup]) |
| groups[defaultGroup] = []; |
| addUngroupedKeys(keys, options.alias, groups, defaultGroup); |
| const isLongSwitch = (sw) => /^--/.test(getText(sw)); |
| const displayedGroups = Object.keys(groups) |
| .filter(groupName => groups[groupName].length > 0) |
| .map(groupName => { |
| const normalizedKeys = groups[groupName] |
| .filter(filterHiddenOptions) |
| .map(key => { |
| if (~aliasKeys.indexOf(key)) |
| return key; |
| for (let i = 0, aliasKey; (aliasKey = aliasKeys[i]) !== undefined; i++) { |
| if (~(options.alias[aliasKey] || []).indexOf(key)) |
| return aliasKey; |
| } |
| return key; |
| }); |
| return { groupName, normalizedKeys }; |
| }) |
| .filter(({ normalizedKeys }) => normalizedKeys.length > 0) |
| .map(({ groupName, normalizedKeys }) => { |
| const switches = normalizedKeys.reduce((acc, key) => { |
| acc[key] = [key] |
| .concat(options.alias[key] || []) |
| .map(sw => { |
| if (groupName === self.getPositionalGroupName()) |
| return sw; |
| else { |
| return ((/^[0-9]$/.test(sw) |
| ? ~options.boolean.indexOf(key) |
| ? '-' |
| : '--' |
| : sw.length > 1 |
| ? '--' |
| : '-') + sw); |
| } |
| }) |
| .sort((sw1, sw2) => isLongSwitch(sw1) === isLongSwitch(sw2) |
| ? 0 |
| : isLongSwitch(sw1) |
| ? 1 |
| : -1) |
| .join(', '); |
| return acc; |
| }, {}); |
| return { groupName, normalizedKeys, switches }; |
| }); |
| const shortSwitchesUsed = displayedGroups |
| .filter(({ groupName }) => groupName !== self.getPositionalGroupName()) |
| .some(({ normalizedKeys, switches }) => !normalizedKeys.every(key => isLongSwitch(switches[key]))); |
| if (shortSwitchesUsed) { |
| displayedGroups |
| .filter(({ groupName }) => groupName !== self.getPositionalGroupName()) |
| .forEach(({ normalizedKeys, switches }) => { |
| normalizedKeys.forEach(key => { |
| if (isLongSwitch(switches[key])) { |
| switches[key] = addIndentation(switches[key], '-x, '.length); |
| } |
| }); |
| }); |
| } |
| displayedGroups.forEach(({ groupName, normalizedKeys, switches }) => { |
| ui.div(groupName); |
| normalizedKeys.forEach(key => { |
| const kswitch = switches[key]; |
| let desc = descriptions[key] || ''; |
| let type = null; |
| if (~desc.lastIndexOf(deferY18nLookupPrefix)) |
| desc = __(desc.substring(deferY18nLookupPrefix.length)); |
| if (~options.boolean.indexOf(key)) |
| type = `[${__('boolean')}]`; |
| if (~options.count.indexOf(key)) |
| type = `[${__('count')}]`; |
| if (~options.string.indexOf(key)) |
| type = `[${__('string')}]`; |
| if (~options.normalize.indexOf(key)) |
| type = `[${__('string')}]`; |
| if (~options.array.indexOf(key)) |
| type = `[${__('array')}]`; |
| if (~options.number.indexOf(key)) |
| type = `[${__('number')}]`; |
| const deprecatedExtra = (deprecated) => typeof deprecated === 'string' |
| ? `[${__('deprecated: %s', deprecated)}]` |
| : `[${__('deprecated')}]`; |
| const extra = [ |
| key in deprecatedOptions |
| ? deprecatedExtra(deprecatedOptions[key]) |
| : null, |
| type, |
| key in demandedOptions ? `[${__('required')}]` : null, |
| options.choices && options.choices[key] |
| ? `[${__('choices:')} ${self.stringifiedValues(options.choices[key])}]` |
| : null, |
| defaultString(options.default[key], options.defaultDescription[key]), |
| ] |
| .filter(Boolean) |
| .join(' '); |
| ui.span({ |
| text: getText(kswitch), |
| padding: [0, 2, 0, 2 + getIndentation(kswitch)], |
| width: maxWidth(switches, theWrap) + 4, |
| }, desc); |
| if (extra) |
| ui.div({ text: extra, padding: [0, 0, 0, 2], align: 'right' }); |
| else |
| ui.div(); |
| }); |
| ui.div(); |
| }); |
| if (examples.length) { |
| ui.div(__('Examples:')); |
| examples.forEach(example => { |
| example[0] = example[0].replace(/\$0/g, base$0); |
| }); |
| examples.forEach(example => { |
| if (example[1] === '') { |
| ui.div({ |
| text: example[0], |
| padding: [0, 2, 0, 2], |
| }); |
| } |
| else { |
| ui.div({ |
| text: example[0], |
| padding: [0, 2, 0, 2], |
| width: maxWidth(examples, theWrap) + 4, |
| }, { |
| text: example[1], |
| }); |
| } |
| }); |
| ui.div(); |
| } |
| if (epilogs.length > 0) { |
| const e = epilogs |
| .map(epilog => epilog.replace(/\$0/g, base$0)) |
| .join('\n'); |
| ui.div(`${e}\n`); |
| } |
| return ui.toString().replace(/\s*$/, ''); |
| }; |
| function maxWidth(table, theWrap, modifier) { |
| let width = 0; |
| if (!Array.isArray(table)) { |
| table = Object.values(table).map(v => [v]); |
| } |
| table.forEach(v => { |
| width = Math.max(shim.stringWidth(modifier ? `${modifier} ${getText(v[0])}` : getText(v[0])) + getIndentation(v[0]), width); |
| }); |
| if (theWrap) |
| width = Math.min(width, parseInt((theWrap * 0.5).toString(), 10)); |
| return width; |
| } |
| function normalizeAliases() { |
| const demandedOptions = yargs.getDemandedOptions(); |
| const options = yargs.getOptions(); |
| (Object.keys(options.alias) || []).forEach(key => { |
| options.alias[key].forEach(alias => { |
| if (descriptions[alias]) |
| self.describe(key, descriptions[alias]); |
| if (alias in demandedOptions) |
| yargs.demandOption(key, demandedOptions[alias]); |
| if (~options.boolean.indexOf(alias)) |
| yargs.boolean(key); |
| if (~options.count.indexOf(alias)) |
| yargs.count(key); |
| if (~options.string.indexOf(alias)) |
| yargs.string(key); |
| if (~options.normalize.indexOf(alias)) |
| yargs.normalize(key); |
| if (~options.array.indexOf(alias)) |
| yargs.array(key); |
| if (~options.number.indexOf(alias)) |
| yargs.number(key); |
| }); |
| }); |
| } |
| let cachedHelpMessage; |
| self.cacheHelpMessage = function () { |
| cachedHelpMessage = this.help(); |
| }; |
| self.clearCachedHelpMessage = function () { |
| cachedHelpMessage = undefined; |
| }; |
| function addUngroupedKeys(keys, aliases, groups, defaultGroup) { |
| let groupedKeys = []; |
| let toCheck = null; |
| Object.keys(groups).forEach(group => { |
| groupedKeys = groupedKeys.concat(groups[group]); |
| }); |
| keys.forEach(key => { |
| toCheck = [key].concat(aliases[key]); |
| if (!toCheck.some(k => groupedKeys.indexOf(k) !== -1)) { |
| groups[defaultGroup].push(key); |
| } |
| }); |
| return groupedKeys; |
| } |
| function filterHiddenOptions(key) { |
| return (yargs.getOptions().hiddenOptions.indexOf(key) < 0 || |
| yargs.parsed.argv[yargs.getOptions().showHiddenOpt]); |
| } |
| self.showHelp = (level) => { |
| const logger = yargs._getLoggerInstance(); |
| if (!level) |
| level = 'error'; |
| const emit = typeof level === 'function' ? level : logger[level]; |
| emit(self.help()); |
| }; |
| self.functionDescription = fn => { |
| const description = fn.name |
| ? shim.Parser.decamelize(fn.name, '-') |
| : __('generated-value'); |
| return ['(', description, ')'].join(''); |
| }; |
| self.stringifiedValues = function stringifiedValues(values, separator) { |
| let string = ''; |
| const sep = separator || ', '; |
| const array = [].concat(values); |
| if (!values || !array.length) |
| return string; |
| array.forEach(value => { |
| if (string.length) |
| string += sep; |
| string += JSON.stringify(value); |
| }); |
| return string; |
| }; |
| function defaultString(value, defaultDescription) { |
| let string = `[${__('default:')} `; |
| if (value === undefined && !defaultDescription) |
| return null; |
| if (defaultDescription) { |
| string += defaultDescription; |
| } |
| else { |
| switch (typeof value) { |
| case 'string': |
| string += `"${value}"`; |
| break; |
| case 'object': |
| string += JSON.stringify(value); |
| break; |
| default: |
| string += value; |
| } |
| } |
| return `${string}]`; |
| } |
| function windowWidth() { |
| const maxWidth = 80; |
| if (shim.process.stdColumns) { |
| return Math.min(maxWidth, shim.process.stdColumns); |
| } |
| else { |
| return maxWidth; |
| } |
| } |
| let version = null; |
| self.version = ver => { |
| version = ver; |
| }; |
| self.showVersion = () => { |
| const logger = yargs._getLoggerInstance(); |
| logger.log(version); |
| }; |
| self.reset = function reset(localLookup) { |
| failMessage = null; |
| failureOutput = false; |
| usages = []; |
| usageDisabled = false; |
| epilogs = []; |
| examples = []; |
| commands = []; |
| descriptions = objFilter(descriptions, k => !localLookup[k]); |
| return self; |
| }; |
| const frozens = []; |
| self.freeze = function freeze() { |
| frozens.push({ |
| failMessage, |
| failureOutput, |
| usages, |
| usageDisabled, |
| epilogs, |
| examples, |
| commands, |
| descriptions, |
| }); |
| }; |
| self.unfreeze = function unfreeze() { |
| const frozen = frozens.pop(); |
| assertNotStrictEqual(frozen, undefined, shim); |
| ({ |
| failMessage, |
| failureOutput, |
| usages, |
| usageDisabled, |
| epilogs, |
| examples, |
| commands, |
| descriptions, |
| } = frozen); |
| }; |
| return self; |
| } |
| function isIndentedText(text) { |
| return typeof text === 'object'; |
| } |
| function addIndentation(text, indent) { |
| return isIndentedText(text) |
| ? { text: text.text, indentation: text.indentation + indent } |
| : { text, indentation: indent }; |
| } |
| function getIndentation(text) { |
| return isIndentedText(text) ? text.indentation : 0; |
| } |
| function getText(text) { |
| return isIndentedText(text) ? text.text : text; |
| } |
