Page MenuHomec4science
Files F101884632

usage.js
No OneTemporary
Actions

File Metadata

Created
Fri, Feb 14, 18:04

usage.js
View Options

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;
}

Event Timeline

c4science · Help