490 lines
13 KiB
JavaScript
490 lines
13 KiB
JavaScript
|
// this file handles outputting usage instructions,
|
||
|
|
// failures, etc. keeps logging in one place.
|
||
|
|
const stringWidth = require('string-width')
|
||
|
|
const objFilter = require('./obj-filter')
|
||
|
|
const setBlocking = require('set-blocking')
|
||
|
|
const YError = require('./yerror')
|
||
|
|
|
||
|
|
module.exports = function (yargs, y18n) {
|
||
|
|
const __ = y18n.__
|
||
|
|
const self = {}
|
||
|
|
|
||
|
|
// methods for ouputting/building failure message.
|
||
|
|
var fails = []
|
||
|
|
self.failFn = function (f) {
|
||
|
|
fails.push(f)
|
||
|
|
}
|
||
|
|
|
||
|
|
var failMessage = null
|
||
|
|
var showHelpOnFail = true
|
||
|
|
self.showHelpOnFail = function (enabled, message) {
|
||
|
|
if (typeof enabled === 'string') {
|
||
|
|
message = enabled
|
||
|
|
enabled = true
|
||
|
|
} else if (typeof enabled === 'undefined') {
|
||
|
|
enabled = true
|
||
|
|
}
|
||
|
|
failMessage = message
|
||
|
|
showHelpOnFail = enabled
|
||
|
|
return self
|
||
|
|
}
|
||
|
|
|
||
|
|
var failureOutput = false
|
||
|
|
self.fail = function (msg, err) {
|
||
|
|
const logger = yargs._getLoggerInstance()
|
||
|
|
|
||
|
|
if (fails.length) {
|
||
|
|
for (var i = fails.length - 1; i >= 0; --i) {
|
||
|
|
fails[i](msg, err, self)
|
||
|
|
}
|
||
|
|
} else {
|
||
|
|
if (yargs.getExitProcess()) setBlocking(true)
|
||
|
|
|
||
|
|
// don't output failure message more than once
|
||
|
|
if (!failureOutput) {
|
||
|
|
failureOutput = true
|
||
|
|
if (showHelpOnFail) yargs.showHelp('error')
|
||
|
|
if (msg) logger.error(msg)
|
||
|
|
if (failMessage) {
|
||
|
|
if (msg) 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
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
// methods for ouputting/building help (usage) message.
|
||
|
|
var usage
|
||
|
|
self.usage = function (msg) {
|
||
|
|
usage = msg
|
||
|
|
}
|
||
|
|
self.getUsage = function () {
|
||
|
|
return usage
|
||
|
|
}
|
||
|
|
|
||
|
|
var examples = []
|
||
|
|
self.example = function (cmd, description) {
|
||
|
|
examples.push([cmd, description || ''])
|
||
|
|
}
|
||
|
|
|
||
|
|
var commands = []
|
||
|
|
self.command = function (cmd, description, isDefault, aliases) {
|
||
|
|
// the last default wins, so cancel out any previously set default
|
||
|
|
if (isDefault) {
|
||
|
|
commands = commands.map(function (cmdArray) {
|
||
|
|
cmdArray[2] = false
|
||
|
|
return cmdArray
|
||
|
|
})
|
||
|
|
}
|
||
|
|
commands.push([cmd, description || '', isDefault, aliases])
|
||
|
|
}
|
||
|
|
self.getCommands = function () {
|
||
|
|
return commands
|
||
|
|
}
|
||
|
|
|
||
|
|
var descriptions = {}
|
||
|
|
self.describe = function (key, desc) {
|
||
|
|
if (typeof key === 'object') {
|
||
|
|
Object.keys(key).forEach(function (k) {
|
||
|
|
self.describe(k, key[k])
|
||
|
|
})
|
||
|
|
} else {
|
||
|
|
descriptions[key] = desc
|
||
|
|
}
|
||
|
|
}
|
||
|
|
self.getDescriptions = function () {
|
||
|
|
return descriptions
|
||
|
|
}
|
||
|
|
|
||
|
|
var epilog
|
||
|
|
self.epilog = function (msg) {
|
||
|
|
epilog = msg
|
||
|
|
}
|
||
|
|
|
||
|
|
var wrapSet = false
|
||
|
|
var wrap
|
||
|
|
self.wrap = function (cols) {
|
||
|
|
wrapSet = true
|
||
|
|
wrap = cols
|
||
|
|
}
|
||
|
|
|
||
|
|
function getWrap () {
|
||
|
|
if (!wrapSet) {
|
||
|
|
wrap = windowWidth()
|
||
|
|
wrapSet = true
|
||
|
|
}
|
||
|
|
|
||
|
|
return wrap
|
||
|
|
}
|
||
|
|
|
||
|
|
var deferY18nLookupPrefix = '__yargsString__:'
|
||
|
|
self.deferY18nLookup = function (str) {
|
||
|
|
return deferY18nLookupPrefix + str
|
||
|
|
}
|
||
|
|
|
||
|
|
var defaultGroup = 'Options:'
|
||
|
|
self.help = function () {
|
||
|
|
normalizeAliases()
|
||
|
|
|
||
|
|
// handle old demanded API
|
||
|
|
var demandedOptions = yargs.getDemandedOptions()
|
||
|
|
var demandedCommands = yargs.getDemandedCommands()
|
||
|
|
var groups = yargs.getGroups()
|
||
|
|
var options = yargs.getOptions()
|
||
|
|
var keys = Object.keys(
|
||
|
|
Object.keys(descriptions)
|
||
|
|
.concat(Object.keys(demandedOptions))
|
||
|
|
.concat(Object.keys(demandedCommands))
|
||
|
|
.concat(Object.keys(options.default))
|
||
|
|
.reduce(function (acc, key) {
|
||
|
|
if (key !== '_') acc[key] = true
|
||
|
|
return acc
|
||
|
|
}, {})
|
||
|
|
)
|
||
|
|
|
||
|
|
var theWrap = getWrap()
|
||
|
|
var ui = require('cliui')({
|
||
|
|
width: theWrap,
|
||
|
|
wrap: !!theWrap
|
||
|
|
})
|
||
|
|
|
||
|
|
// the usage string.
|
||
|
|
if (usage) {
|
||
|
|
var u = usage.replace(/\$0/g, yargs.$0)
|
||
|
|
ui.div(u + '\n')
|
||
|
|
}
|
||
|
|
|
||
|
|
// your application's commands, i.e., non-option
|
||
|
|
// arguments populated in '_'.
|
||
|
|
if (commands.length) {
|
||
|
|
ui.div(__('Commands:'))
|
||
|
|
|
||
|
|
commands.forEach(function (command) {
|
||
|
|
ui.span(
|
||
|
|
{text: command[0], padding: [0, 2, 0, 2], width: maxWidth(commands, theWrap) + 4},
|
||
|
|
{text: command[1]}
|
||
|
|
)
|
||
|
|
var hints = []
|
||
|
|
if (command[2]) hints.push('[' + __('default:').slice(0, -1) + ']') // TODO hacking around i18n here
|
||
|
|
if (command[3] && command[3].length) {
|
||
|
|
hints.push('[' + __('aliases:') + ' ' + command[3].join(', ') + ']')
|
||
|
|
}
|
||
|
|
if (hints.length) {
|
||
|
|
ui.div({text: hints.join(' '), padding: [0, 0, 0, 2], align: 'right'})
|
||
|
|
} else {
|
||
|
|
ui.div()
|
||
|
|
}
|
||
|
|
})
|
||
|
|
|
||
|
|
ui.div()
|
||
|
|
}
|
||
|
|
|
||
|
|
// perform some cleanup on the keys array, making it
|
||
|
|
// only include top-level keys not their aliases.
|
||
|
|
var aliasKeys = (Object.keys(options.alias) || [])
|
||
|
|
.concat(Object.keys(yargs.parsed.newAliases) || [])
|
||
|
|
|
||
|
|
keys = keys.filter(function (key) {
|
||
|
|
return !yargs.parsed.newAliases[key] && aliasKeys.every(function (alias) {
|
||
|
|
return (options.alias[alias] || []).indexOf(key) === -1
|
||
|
|
})
|
||
|
|
})
|
||
|
|
|
||
|
|
// populate 'Options:' group with any keys that have not
|
||
|
|
// explicitly had a group set.
|
||
|
|
if (!groups[defaultGroup]) groups[defaultGroup] = []
|
||
|
|
addUngroupedKeys(keys, options.alias, groups)
|
||
|
|
|
||
|
|
// display 'Options:' table along with any custom tables:
|
||
|
|
Object.keys(groups).forEach(function (groupName) {
|
||
|
|
if (!groups[groupName].length) return
|
||
|
|
|
||
|
|
ui.div(__(groupName))
|
||
|
|
|
||
|
|
// if we've grouped the key 'f', but 'f' aliases 'foobar',
|
||
|
|
// normalizedKeys should contain only 'foobar'.
|
||
|
|
var normalizedKeys = groups[groupName].map(function (key) {
|
||
|
|
if (~aliasKeys.indexOf(key)) return key
|
||
|
|
for (var i = 0, aliasKey; (aliasKey = aliasKeys[i]) !== undefined; i++) {
|
||
|
|
if (~(options.alias[aliasKey] || []).indexOf(key)) return aliasKey
|
||
|
|
}
|
||
|
|
return key
|
||
|
|
})
|
||
|
|
|
||
|
|
// actually generate the switches string --foo, -f, --bar.
|
||
|
|
var switches = normalizedKeys.reduce(function (acc, key) {
|
||
|
|
acc[key] = [ key ].concat(options.alias[key] || [])
|
||
|
|
.map(function (sw) {
|
||
|
|
return (sw.length > 1 ? '--' : '-') + sw
|
||
|
|
})
|
||
|
|
.join(', ')
|
||
|
|
|
||
|
|
return acc
|
||
|
|
}, {})
|
||
|
|
|
||
|
|
normalizedKeys.forEach(function (key) {
|
||
|
|
var kswitch = switches[key]
|
||
|
|
var desc = descriptions[key] || ''
|
||
|
|
var 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') + ']'
|
||
|
|
|
||
|
|
var extra = [
|
||
|
|
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: kswitch, padding: [0, 2, 0, 2], width: maxWidth(switches, theWrap) + 4},
|
||
|
|
desc
|
||
|
|
)
|
||
|
|
|
||
|
|
if (extra) ui.div({text: extra, padding: [0, 0, 0, 2], align: 'right'})
|
||
|
|
else ui.div()
|
||
|
|
})
|
||
|
|
|
||
|
|
ui.div()
|
||
|
|
})
|
||
|
|
|
||
|
|
// describe some common use-cases for your application.
|
||
|
|
if (examples.length) {
|
||
|
|
ui.div(__('Examples:'))
|
||
|
|
|
||
|
|
examples.forEach(function (example) {
|
||
|
|
example[0] = example[0].replace(/\$0/g, yargs.$0)
|
||
|
|
})
|
||
|
|
|
||
|
|
examples.forEach(function (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()
|
||
|
|
}
|
||
|
|
|
||
|
|
// the usage string.
|
||
|
|
if (epilog) {
|
||
|
|
var e = epilog.replace(/\$0/g, yargs.$0)
|
||
|
|
ui.div(e + '\n')
|
||
|
|
}
|
||
|
|
|
||
|
|
return ui.toString()
|
||
|
|
}
|
||
|
|
|
||
|
|
// return the maximum width of a string
|
||
|
|
// in the left-hand column of a table.
|
||
|
|
function maxWidth (table, theWrap) {
|
||
|
|
var width = 0
|
||
|
|
|
||
|
|
// table might be of the form [leftColumn],
|
||
|
|
// or {key: leftColumn}
|
||
|
|
if (!Array.isArray(table)) {
|
||
|
|
table = Object.keys(table).map(function (key) {
|
||
|
|
return [table[key]]
|
||
|
|
})
|
||
|
|
}
|
||
|
|
|
||
|
|
table.forEach(function (v) {
|
||
|
|
width = Math.max(stringWidth(v[0]), width)
|
||
|
|
})
|
||
|
|
|
||
|
|
// if we've enabled 'wrap' we should limit
|
||
|
|
// the max-width of the left-column.
|
||
|
|
if (theWrap) width = Math.min(width, parseInt(theWrap * 0.5, 10))
|
||
|
|
|
||
|
|
return width
|
||
|
|
}
|
||
|
|
|
||
|
|
// make sure any options set for aliases,
|
||
|
|
// are copied to the keys being aliased.
|
||
|
|
function normalizeAliases () {
|
||
|
|
// handle old demanded API
|
||
|
|
var demandedOptions = yargs.getDemandedOptions()
|
||
|
|
var options = yargs.getOptions()
|
||
|
|
|
||
|
|
;(Object.keys(options.alias) || []).forEach(function (key) {
|
||
|
|
options.alias[key].forEach(function (alias) {
|
||
|
|
// copy descriptions.
|
||
|
|
if (descriptions[alias]) self.describe(key, descriptions[alias])
|
||
|
|
// copy demanded.
|
||
|
|
if (alias in demandedOptions) yargs.demandOption(key, demandedOptions[alias])
|
||
|
|
// type messages.
|
||
|
|
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)
|
||
|
|
})
|
||
|
|
})
|
||
|
|
}
|
||
|
|
|
||
|
|
// given a set of keys, place any keys that are
|
||
|
|
// ungrouped under the 'Options:' grouping.
|
||
|
|
function addUngroupedKeys (keys, aliases, groups) {
|
||
|
|
var groupedKeys = []
|
||
|
|
var toCheck = null
|
||
|
|
Object.keys(groups).forEach(function (group) {
|
||
|
|
groupedKeys = groupedKeys.concat(groups[group])
|
||
|
|
})
|
||
|
|
|
||
|
|
keys.forEach(function (key) {
|
||
|
|
toCheck = [key].concat(aliases[key])
|
||
|
|
if (!toCheck.some(function (k) {
|
||
|
|
return groupedKeys.indexOf(k) !== -1
|
||
|
|
})) {
|
||
|
|
groups[defaultGroup].push(key)
|
||
|
|
}
|
||
|
|
})
|
||
|
|
return groupedKeys
|
||
|
|
}
|
||
|
|
|
||
|
|
self.showHelp = function (level) {
|
||
|
|
const logger = yargs._getLoggerInstance()
|
||
|
|
if (!level) level = 'error'
|
||
|
|
var emit = typeof level === 'function' ? level : logger[level]
|
||
|
|
emit(self.help())
|
||
|
|
}
|
||
|
|
|
||
|
|
self.functionDescription = function (fn) {
|
||
|
|
var description = fn.name ? require('decamelize')(fn.name, '-') : __('generated-value')
|
||
|
|
return ['(', description, ')'].join('')
|
||
|
|
}
|
||
|
|
|
||
|
|
self.stringifiedValues = function (values, separator) {
|
||
|
|
var string = ''
|
||
|
|
var sep = separator || ', '
|
||
|
|
var array = [].concat(values)
|
||
|
|
|
||
|
|
if (!values || !array.length) return string
|
||
|
|
|
||
|
|
array.forEach(function (value) {
|
||
|
|
if (string.length) string += sep
|
||
|
|
string += JSON.stringify(value)
|
||
|
|
})
|
||
|
|
|
||
|
|
return string
|
||
|
|
}
|
||
|
|
|
||
|
|
// format the default-value-string displayed in
|
||
|
|
// the right-hand column.
|
||
|
|
function defaultString (value, defaultDescription) {
|
||
|
|
var string = '[' + __('default:') + ' '
|
||
|
|
|
||
|
|
if (value === undefined && !defaultDescription) return null
|
||
|
|
|
||
|
|
if (defaultDescription) {
|
||
|
|
string += defaultDescription
|
||
|
|
} else {
|
||
|
|
switch (typeof value) {
|
||
|
|
case 'string':
|
||
|
|
string += JSON.stringify(value)
|
||
|
|
break
|
||
|
|
case 'object':
|
||
|
|
string += JSON.stringify(value)
|
||
|
|
break
|
||
|
|
default:
|
||
|
|
string += value
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
return string + ']'
|
||
|
|
}
|
||
|
|
|
||
|
|
// guess the width of the console window, max-width 80.
|
||
|
|
function windowWidth () {
|
||
|
|
var maxWidth = 80
|
||
|
|
if (typeof process === 'object' && process.stdout && process.stdout.columns) {
|
||
|
|
return Math.min(maxWidth, process.stdout.columns)
|
||
|
|
} else {
|
||
|
|
return maxWidth
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
// logic for displaying application version.
|
||
|
|
var version = null
|
||
|
|
self.version = function (ver) {
|
||
|
|
version = ver
|
||
|
|
}
|
||
|
|
|
||
|
|
self.showVersion = function () {
|
||
|
|
const logger = yargs._getLoggerInstance()
|
||
|
|
if (typeof version === 'function') logger.log(version())
|
||
|
|
else logger.log(version)
|
||
|
|
}
|
||
|
|
|
||
|
|
self.reset = function (localLookup) {
|
||
|
|
// do not reset wrap here
|
||
|
|
// do not reset fails here
|
||
|
|
failMessage = null
|
||
|
|
failureOutput = false
|
||
|
|
usage = undefined
|
||
|
|
epilog = undefined
|
||
|
|
examples = []
|
||
|
|
commands = []
|
||
|
|
descriptions = objFilter(descriptions, function (k, v) {
|
||
|
|
return !localLookup[k]
|
||
|
|
})
|
||
|
|
return self
|
||
|
|
}
|
||
|
|
|
||
|
|
var frozen
|
||
|
|
self.freeze = function () {
|
||
|
|
frozen = {}
|
||
|
|
frozen.failMessage = failMessage
|
||
|
|
frozen.failureOutput = failureOutput
|
||
|
|
frozen.usage = usage
|
||
|
|
frozen.epilog = epilog
|
||
|
|
frozen.examples = examples
|
||
|
|
frozen.commands = commands
|
||
|
|
frozen.descriptions = descriptions
|
||
|
|
}
|
||
|
|
self.unfreeze = function () {
|
||
|
|
failMessage = frozen.failMessage
|
||
|
|
failureOutput = frozen.failureOutput
|
||
|
|
usage = frozen.usage
|
||
|
|
epilog = frozen.epilog
|
||
|
|
examples = frozen.examples
|
||
|
|
commands = frozen.commands
|
||
|
|
descriptions = frozen.descriptions
|
||
|
|
frozen = undefined
|
||
|
|
}
|
||
|
|
|
||
|
|
return self
|
||
|
|
}
|