1023 lines
34 KiB
JavaScript
1023 lines
34 KiB
JavaScript
|
/**
|
||
|
|
* dashdash - A light, featureful and explicit option parsing library for
|
||
|
|
* node.js.
|
||
|
|
*/
|
||
|
|
// vim: set ts=4 sts=4 sw=4 et:
|
||
|
|
|
||
|
|
var assert = require('assert-plus');
|
||
|
|
var format = require('util').format;
|
||
|
|
var fs = require('fs');
|
||
|
|
var path = require('path');
|
||
|
|
|
||
|
|
|
||
|
|
var DEBUG = true;
|
||
|
|
if (DEBUG) {
|
||
|
|
var debug = console.warn;
|
||
|
|
} else {
|
||
|
|
var debug = function () {};
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
// ---- internal support stuff
|
||
|
|
|
||
|
|
// Replace {{variable}} in `s` with the template data in `d`.
|
||
|
|
function renderTemplate(s, d) {
|
||
|
|
return s.replace(/{{([a-zA-Z]+)}}/g, function (match, key) {
|
||
|
|
return d.hasOwnProperty(key) ? d[key] : match;
|
||
|
|
});
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return a shallow copy of the given object;
|
||
|
|
*/
|
||
|
|
function shallowCopy(obj) {
|
||
|
|
if (!obj) {
|
||
|
|
return (obj);
|
||
|
|
}
|
||
|
|
var copy = {};
|
||
|
|
Object.keys(obj).forEach(function (k) {
|
||
|
|
copy[k] = obj[k];
|
||
|
|
});
|
||
|
|
return (copy);
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
function space(n) {
|
||
|
|
var s = '';
|
||
|
|
for (var i = 0; i < n; i++) {
|
||
|
|
s += ' ';
|
||
|
|
}
|
||
|
|
return s;
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
function makeIndent(arg, deflen, name) {
|
||
|
|
if (arg === null || arg === undefined)
|
||
|
|
return space(deflen);
|
||
|
|
else if (typeof (arg) === 'number')
|
||
|
|
return space(arg);
|
||
|
|
else if (typeof (arg) === 'string')
|
||
|
|
return arg;
|
||
|
|
else
|
||
|
|
assert.fail('invalid "' + name + '": not a string or number: ' + arg);
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return an array of lines wrapping the given text to the given width.
|
||
|
|
* This splits on whitespace. Single tokens longer than `width` are not
|
||
|
|
* broken up.
|
||
|
|
*/
|
||
|
|
function textwrap(s, width) {
|
||
|
|
var words = s.trim().split(/\s+/);
|
||
|
|
var lines = [];
|
||
|
|
var line = '';
|
||
|
|
words.forEach(function (w) {
|
||
|
|
var newLength = line.length + w.length;
|
||
|
|
if (line.length > 0)
|
||
|
|
newLength += 1;
|
||
|
|
if (newLength > width) {
|
||
|
|
lines.push(line);
|
||
|
|
line = '';
|
||
|
|
}
|
||
|
|
if (line.length > 0)
|
||
|
|
line += ' ';
|
||
|
|
line += w;
|
||
|
|
});
|
||
|
|
lines.push(line);
|
||
|
|
return lines;
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Transform an option name to a "key" that is used as the field
|
||
|
|
* on the `opts` object returned from `<parser>.parse()`.
|
||
|
|
*
|
||
|
|
* Transformations:
|
||
|
|
* - '-' -> '_': This allow one to use hyphen in option names (common)
|
||
|
|
* but not have to do silly things like `opt["dry-run"]` to access the
|
||
|
|
* parsed results.
|
||
|
|
*/
|
||
|
|
function optionKeyFromName(name) {
|
||
|
|
return name.replace(/-/g, '_');
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
// ---- Option types
|
||
|
|
|
||
|
|
function parseBool(option, optstr, arg) {
|
||
|
|
return Boolean(arg);
|
||
|
|
}
|
||
|
|
|
||
|
|
function parseString(option, optstr, arg) {
|
||
|
|
assert.string(arg, 'arg');
|
||
|
|
return arg;
|
||
|
|
}
|
||
|
|
|
||
|
|
function parseNumber(option, optstr, arg) {
|
||
|
|
assert.string(arg, 'arg');
|
||
|
|
var num = Number(arg);
|
||
|
|
if (isNaN(num)) {
|
||
|
|
throw new Error(format('arg for "%s" is not a number: "%s"',
|
||
|
|
optstr, arg));
|
||
|
|
}
|
||
|
|
return num;
|
||
|
|
}
|
||
|
|
|
||
|
|
function parseInteger(option, optstr, arg) {
|
||
|
|
assert.string(arg, 'arg');
|
||
|
|
var num = Number(arg);
|
||
|
|
if (!/^[0-9-]+$/.test(arg) || isNaN(num)) {
|
||
|
|
throw new Error(format('arg for "%s" is not an integer: "%s"',
|
||
|
|
optstr, arg));
|
||
|
|
}
|
||
|
|
return num;
|
||
|
|
}
|
||
|
|
|
||
|
|
function parsePositiveInteger(option, optstr, arg) {
|
||
|
|
assert.string(arg, 'arg');
|
||
|
|
var num = Number(arg);
|
||
|
|
if (!/^[0-9]+$/.test(arg) || isNaN(num) || num === 0) {
|
||
|
|
throw new Error(format('arg for "%s" is not a positive integer: "%s"',
|
||
|
|
optstr, arg));
|
||
|
|
}
|
||
|
|
return num;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Supported date args:
|
||
|
|
* - epoch second times (e.g. 1396031701)
|
||
|
|
* - ISO 8601 format: YYYY-MM-DD[THH:MM:SS[.sss][Z]]
|
||
|
|
* 2014-03-28T18:35:01.489Z
|
||
|
|
* 2014-03-28T18:35:01.489
|
||
|
|
* 2014-03-28T18:35:01Z
|
||
|
|
* 2014-03-28T18:35:01
|
||
|
|
* 2014-03-28
|
||
|
|
*/
|
||
|
|
function parseDate(option, optstr, arg) {
|
||
|
|
assert.string(arg, 'arg');
|
||
|
|
var date;
|
||
|
|
if (/^\d+$/.test(arg)) {
|
||
|
|
// epoch seconds
|
||
|
|
date = new Date(Number(arg) * 1000);
|
||
|
|
/* JSSTYLED */
|
||
|
|
} else if (/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?Z?)?$/i.test(arg)) {
|
||
|
|
// ISO 8601 format
|
||
|
|
date = new Date(arg);
|
||
|
|
} else {
|
||
|
|
throw new Error(format('arg for "%s" is not a valid date format: "%s"',
|
||
|
|
optstr, arg));
|
||
|
|
}
|
||
|
|
if (date.toString() === 'Invalid Date') {
|
||
|
|
throw new Error(format('arg for "%s" is an invalid date: "%s"',
|
||
|
|
optstr, arg));
|
||
|
|
}
|
||
|
|
return date;
|
||
|
|
}
|
||
|
|
|
||
|
|
var optionTypes = {
|
||
|
|
bool: {
|
||
|
|
takesArg: false,
|
||
|
|
parseArg: parseBool
|
||
|
|
},
|
||
|
|
string: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'ARG',
|
||
|
|
parseArg: parseString
|
||
|
|
},
|
||
|
|
number: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'NUM',
|
||
|
|
parseArg: parseNumber
|
||
|
|
},
|
||
|
|
integer: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'INT',
|
||
|
|
parseArg: parseInteger
|
||
|
|
},
|
||
|
|
positiveInteger: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'INT',
|
||
|
|
parseArg: parsePositiveInteger
|
||
|
|
},
|
||
|
|
date: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'DATE',
|
||
|
|
parseArg: parseDate
|
||
|
|
},
|
||
|
|
arrayOfBool: {
|
||
|
|
takesArg: false,
|
||
|
|
array: true,
|
||
|
|
parseArg: parseBool
|
||
|
|
},
|
||
|
|
arrayOfString: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'ARG',
|
||
|
|
array: true,
|
||
|
|
parseArg: parseString
|
||
|
|
},
|
||
|
|
arrayOfNumber: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'NUM',
|
||
|
|
array: true,
|
||
|
|
parseArg: parseNumber
|
||
|
|
},
|
||
|
|
arrayOfInteger: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'INT',
|
||
|
|
array: true,
|
||
|
|
parseArg: parseInteger
|
||
|
|
},
|
||
|
|
arrayOfPositiveInteger: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'INT',
|
||
|
|
array: true,
|
||
|
|
parseArg: parsePositiveInteger
|
||
|
|
},
|
||
|
|
arrayOfDate: {
|
||
|
|
takesArg: true,
|
||
|
|
helpArg: 'INT',
|
||
|
|
array: true,
|
||
|
|
parseArg: parseDate
|
||
|
|
},
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
// ---- Parser
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Parser constructor.
|
||
|
|
*
|
||
|
|
* @param config {Object} The parser configuration
|
||
|
|
* - options {Array} Array of option specs. See the README for how to
|
||
|
|
* specify each option spec.
|
||
|
|
* - allowUnknown {Boolean} Default false. Whether to throw on unknown
|
||
|
|
* options. If false, then unknown args are included in the _args array.
|
||
|
|
* - interspersed {Boolean} Default true. Whether to allow interspersed
|
||
|
|
* arguments (non-options) and options. E.g.:
|
||
|
|
* node tool.js arg1 arg2 -v
|
||
|
|
* '-v' is after some args here. If `interspersed: false` then '-v'
|
||
|
|
* would not be parsed out. Note that regardless of `interspersed`
|
||
|
|
* the presence of '--' will stop option parsing, as all good
|
||
|
|
* option parsers should.
|
||
|
|
*/
|
||
|
|
function Parser(config) {
|
||
|
|
assert.object(config, 'config');
|
||
|
|
assert.arrayOfObject(config.options, 'config.options');
|
||
|
|
assert.optionalBool(config.interspersed, 'config.interspersed');
|
||
|
|
var self = this;
|
||
|
|
|
||
|
|
// Allow interspersed arguments (true by default).
|
||
|
|
this.interspersed = (config.interspersed !== undefined
|
||
|
|
? config.interspersed : true);
|
||
|
|
|
||
|
|
// Don't allow unknown flags (true by default).
|
||
|
|
this.allowUnknown = (config.allowUnknown !== undefined
|
||
|
|
? config.allowUnknown : false);
|
||
|
|
|
||
|
|
this.options = config.options.map(function (o) { return shallowCopy(o); });
|
||
|
|
this.optionFromName = {};
|
||
|
|
this.optionFromEnv = {};
|
||
|
|
for (var i = 0; i < this.options.length; i++) {
|
||
|
|
var o = this.options[i];
|
||
|
|
if (o.group !== undefined && o.group !== null) {
|
||
|
|
assert.optionalString(o.group,
|
||
|
|
format('config.options.%d.group', i));
|
||
|
|
continue;
|
||
|
|
}
|
||
|
|
assert.ok(optionTypes[o.type],
|
||
|
|
format('invalid config.options.%d.type: "%s" in %j',
|
||
|
|
i, o.type, o));
|
||
|
|
assert.optionalString(o.name, format('config.options.%d.name', i));
|
||
|
|
assert.optionalArrayOfString(o.names,
|
||
|
|
format('config.options.%d.names', i));
|
||
|
|
assert.ok((o.name || o.names) && !(o.name && o.names),
|
||
|
|
format('exactly one of "name" or "names" required: %j', o));
|
||
|
|
assert.optionalString(o.help, format('config.options.%d.help', i));
|
||
|
|
var env = o.env || [];
|
||
|
|
if (typeof (env) === 'string') {
|
||
|
|
env = [env];
|
||
|
|
}
|
||
|
|
assert.optionalArrayOfString(env, format('config.options.%d.env', i));
|
||
|
|
assert.optionalString(o.helpGroup,
|
||
|
|
format('config.options.%d.helpGroup', i));
|
||
|
|
assert.optionalBool(o.helpWrap,
|
||
|
|
format('config.options.%d.helpWrap', i));
|
||
|
|
assert.optionalBool(o.hidden, format('config.options.%d.hidden', i));
|
||
|
|
|
||
|
|
if (o.name) {
|
||
|
|
o.names = [o.name];
|
||
|
|
} else {
|
||
|
|
assert.string(o.names[0],
|
||
|
|
format('config.options.%d.names is empty', i));
|
||
|
|
}
|
||
|
|
o.key = optionKeyFromName(o.names[0]);
|
||
|
|
o.names.forEach(function (n) {
|
||
|
|
if (self.optionFromName[n]) {
|
||
|
|
throw new Error(format(
|
||
|
|
'option name collision: "%s" used in %j and %j',
|
||
|
|
n, self.optionFromName[n], o));
|
||
|
|
}
|
||
|
|
self.optionFromName[n] = o;
|
||
|
|
});
|
||
|
|
env.forEach(function (n) {
|
||
|
|
if (self.optionFromEnv[n]) {
|
||
|
|
throw new Error(format(
|
||
|
|
'option env collision: "%s" used in %j and %j',
|
||
|
|
n, self.optionFromEnv[n], o));
|
||
|
|
}
|
||
|
|
self.optionFromEnv[n] = o;
|
||
|
|
});
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
Parser.prototype.optionTakesArg = function optionTakesArg(option) {
|
||
|
|
return optionTypes[option.type].takesArg;
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Parse options from the given argv.
|
||
|
|
*
|
||
|
|
* @param inputs {Object} Optional.
|
||
|
|
* - argv {Array} Optional. The argv to parse. Defaults to
|
||
|
|
* `process.argv`.
|
||
|
|
* - slice {Number} The index into argv at which options/args begin.
|
||
|
|
* Default is 2, as appropriate for `process.argv`.
|
||
|
|
* - env {Object} Optional. The env to use for 'env' entries in the
|
||
|
|
* option specs. Defaults to `process.env`.
|
||
|
|
* @returns {Object} Parsed `opts`. It has special keys `_args` (the
|
||
|
|
* remaining args from `argv`) and `_order` (gives the order that
|
||
|
|
* options were specified).
|
||
|
|
*/
|
||
|
|
Parser.prototype.parse = function parse(inputs) {
|
||
|
|
var self = this;
|
||
|
|
|
||
|
|
// Old API was `parse([argv, [slice]])`
|
||
|
|
if (Array.isArray(arguments[0])) {
|
||
|
|
inputs = {argv: arguments[0], slice: arguments[1]};
|
||
|
|
}
|
||
|
|
|
||
|
|
assert.optionalObject(inputs, 'inputs');
|
||
|
|
if (!inputs) {
|
||
|
|
inputs = {};
|
||
|
|
}
|
||
|
|
assert.optionalArrayOfString(inputs.argv, 'inputs.argv');
|
||
|
|
//assert.optionalNumber(slice, 'slice');
|
||
|
|
var argv = inputs.argv || process.argv;
|
||
|
|
var slice = inputs.slice !== undefined ? inputs.slice : 2;
|
||
|
|
var args = argv.slice(slice);
|
||
|
|
var env = inputs.env || process.env;
|
||
|
|
var opts = {};
|
||
|
|
var _order = [];
|
||
|
|
|
||
|
|
function addOpt(option, optstr, key, val, from) {
|
||
|
|
var type = optionTypes[option.type];
|
||
|
|
var parsedVal = type.parseArg(option, optstr, val);
|
||
|
|
if (type.array) {
|
||
|
|
if (!opts[key]) {
|
||
|
|
opts[key] = [];
|
||
|
|
}
|
||
|
|
if (type.arrayFlatten && Array.isArray(parsedVal)) {
|
||
|
|
for (var i = 0; i < parsedVal.length; i++) {
|
||
|
|
opts[key].push(parsedVal[i]);
|
||
|
|
}
|
||
|
|
} else {
|
||
|
|
opts[key].push(parsedVal);
|
||
|
|
}
|
||
|
|
} else {
|
||
|
|
opts[key] = parsedVal;
|
||
|
|
}
|
||
|
|
var item = { key: key, value: parsedVal, from: from };
|
||
|
|
_order.push(item);
|
||
|
|
}
|
||
|
|
|
||
|
|
// Parse args.
|
||
|
|
var _args = [];
|
||
|
|
var i = 0;
|
||
|
|
outer: while (i < args.length) {
|
||
|
|
var arg = args[i];
|
||
|
|
|
||
|
|
// End of options marker.
|
||
|
|
if (arg === '--') {
|
||
|
|
i++;
|
||
|
|
break;
|
||
|
|
|
||
|
|
// Long option
|
||
|
|
} else if (arg.slice(0, 2) === '--') {
|
||
|
|
var name = arg.slice(2);
|
||
|
|
var val = null;
|
||
|
|
var idx = name.indexOf('=');
|
||
|
|
if (idx !== -1) {
|
||
|
|
val = name.slice(idx + 1);
|
||
|
|
name = name.slice(0, idx);
|
||
|
|
}
|
||
|
|
var option = this.optionFromName[name];
|
||
|
|
if (!option) {
|
||
|
|
if (!this.allowUnknown)
|
||
|
|
throw new Error(format('unknown option: "--%s"', name));
|
||
|
|
else if (this.interspersed)
|
||
|
|
_args.push(arg);
|
||
|
|
else
|
||
|
|
break outer;
|
||
|
|
} else {
|
||
|
|
var takesArg = this.optionTakesArg(option);
|
||
|
|
if (val !== null && !takesArg) {
|
||
|
|
throw new Error(format('argument given to "--%s" option '
|
||
|
|
+ 'that does not take one: "%s"', name, arg));
|
||
|
|
}
|
||
|
|
if (!takesArg) {
|
||
|
|
addOpt(option, '--'+name, option.key, true, 'argv');
|
||
|
|
} else if (val !== null) {
|
||
|
|
addOpt(option, '--'+name, option.key, val, 'argv');
|
||
|
|
} else if (i + 1 >= args.length) {
|
||
|
|
throw new Error(format('do not have enough args for "--%s" '
|
||
|
|
+ 'option', name));
|
||
|
|
} else {
|
||
|
|
addOpt(option, '--'+name, option.key, args[i + 1], 'argv');
|
||
|
|
i++;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
// Short option
|
||
|
|
} else if (arg[0] === '-' && arg.length > 1) {
|
||
|
|
var j = 1;
|
||
|
|
var allFound = true;
|
||
|
|
while (j < arg.length) {
|
||
|
|
var name = arg[j];
|
||
|
|
var option = this.optionFromName[name];
|
||
|
|
if (!option) {
|
||
|
|
allFound = false;
|
||
|
|
if (this.allowUnknown) {
|
||
|
|
if (this.interspersed) {
|
||
|
|
_args.push(arg);
|
||
|
|
break;
|
||
|
|
} else
|
||
|
|
break outer;
|
||
|
|
} else if (arg.length > 2) {
|
||
|
|
throw new Error(format(
|
||
|
|
'unknown option: "-%s" in "%s" group',
|
||
|
|
name, arg));
|
||
|
|
} else {
|
||
|
|
throw new Error(format('unknown option: "-%s"', name));
|
||
|
|
}
|
||
|
|
} else if (this.optionTakesArg(option)) {
|
||
|
|
break;
|
||
|
|
}
|
||
|
|
j++;
|
||
|
|
}
|
||
|
|
|
||
|
|
j = 1;
|
||
|
|
while (allFound && j < arg.length) {
|
||
|
|
var name = arg[j];
|
||
|
|
var val = arg.slice(j + 1); // option val if it takes an arg
|
||
|
|
var option = this.optionFromName[name];
|
||
|
|
var takesArg = this.optionTakesArg(option);
|
||
|
|
if (!takesArg) {
|
||
|
|
addOpt(option, '-'+name, option.key, true, 'argv');
|
||
|
|
} else if (val) {
|
||
|
|
addOpt(option, '-'+name, option.key, val, 'argv');
|
||
|
|
break;
|
||
|
|
} else {
|
||
|
|
if (i + 1 >= args.length) {
|
||
|
|
throw new Error(format('do not have enough args '
|
||
|
|
+ 'for "-%s" option', name));
|
||
|
|
}
|
||
|
|
addOpt(option, '-'+name, option.key, args[i + 1], 'argv');
|
||
|
|
i++;
|
||
|
|
break;
|
||
|
|
}
|
||
|
|
j++;
|
||
|
|
}
|
||
|
|
|
||
|
|
// An interspersed arg
|
||
|
|
} else if (this.interspersed) {
|
||
|
|
_args.push(arg);
|
||
|
|
|
||
|
|
// An arg and interspersed args are not allowed, so done options.
|
||
|
|
} else {
|
||
|
|
break outer;
|
||
|
|
}
|
||
|
|
i++;
|
||
|
|
}
|
||
|
|
_args = _args.concat(args.slice(i));
|
||
|
|
|
||
|
|
// Parse environment.
|
||
|
|
Object.keys(this.optionFromEnv).forEach(function (envname) {
|
||
|
|
var val = env[envname];
|
||
|
|
if (val === undefined)
|
||
|
|
return;
|
||
|
|
var option = self.optionFromEnv[envname];
|
||
|
|
if (opts[option.key] !== undefined)
|
||
|
|
return;
|
||
|
|
var takesArg = self.optionTakesArg(option);
|
||
|
|
if (takesArg) {
|
||
|
|
addOpt(option, envname, option.key, val, 'env');
|
||
|
|
} else if (val !== '') {
|
||
|
|
// Boolean envvar handling:
|
||
|
|
// - VAR=<empty-string> not set (as if the VAR was not set)
|
||
|
|
// - VAR=0 false
|
||
|
|
// - anything else true
|
||
|
|
addOpt(option, envname, option.key, (val !== '0'), 'env');
|
||
|
|
}
|
||
|
|
});
|
||
|
|
|
||
|
|
// Apply default values.
|
||
|
|
this.options.forEach(function (o) {
|
||
|
|
if (opts[o.key] === undefined) {
|
||
|
|
if (o.default !== undefined) {
|
||
|
|
opts[o.key] = o.default;
|
||
|
|
} else if (o.type && optionTypes[o.type].default !== undefined) {
|
||
|
|
opts[o.key] = optionTypes[o.type].default;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
});
|
||
|
|
|
||
|
|
opts._order = _order;
|
||
|
|
opts._args = _args;
|
||
|
|
return opts;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return help output for the current options.
|
||
|
|
*
|
||
|
|
* E.g.: if the current options are:
|
||
|
|
* [{names: ['help', 'h'], type: 'bool', help: 'Show help and exit.'}]
|
||
|
|
* then this would return:
|
||
|
|
* ' -h, --help Show help and exit.\n'
|
||
|
|
*
|
||
|
|
* @param config {Object} Config for controlling the option help output.
|
||
|
|
* - indent {Number|String} Default 4. An indent/prefix to use for
|
||
|
|
* each option line.
|
||
|
|
* - nameSort {String} Default is 'length'. By default the names are
|
||
|
|
* sorted to put the short opts first (i.e. '-h, --help' preferred
|
||
|
|
* to '--help, -h'). Set to 'none' to not do this sorting.
|
||
|
|
* - maxCol {Number} Default 80. Note that long tokens in a help string
|
||
|
|
* can go past this.
|
||
|
|
* - helpCol {Number} Set to specify a specific column at which
|
||
|
|
* option help will be aligned. By default this is determined
|
||
|
|
* automatically.
|
||
|
|
* - minHelpCol {Number} Default 20.
|
||
|
|
* - maxHelpCol {Number} Default 40.
|
||
|
|
* - includeEnv {Boolean} Default false. If true, a note stating the `env`
|
||
|
|
* envvar (if specified for this option) will be appended to the help
|
||
|
|
* output.
|
||
|
|
* - includeDefault {Boolean} Default false. If true, a note stating
|
||
|
|
* the `default` for this option, if any, will be appended to the help
|
||
|
|
* output.
|
||
|
|
* - helpWrap {Boolean} Default true. Wrap help text in helpCol..maxCol
|
||
|
|
* bounds.
|
||
|
|
* @returns {String}
|
||
|
|
*/
|
||
|
|
Parser.prototype.help = function help(config) {
|
||
|
|
config = config || {};
|
||
|
|
assert.object(config, 'config');
|
||
|
|
|
||
|
|
var indent = makeIndent(config.indent, 4, 'config.indent');
|
||
|
|
var headingIndent = makeIndent(config.headingIndent,
|
||
|
|
Math.round(indent.length / 2), 'config.headingIndent');
|
||
|
|
|
||
|
|
assert.optionalString(config.nameSort, 'config.nameSort');
|
||
|
|
var nameSort = config.nameSort || 'length';
|
||
|
|
assert.ok(~['length', 'none'].indexOf(nameSort),
|
||
|
|
'invalid "config.nameSort"');
|
||
|
|
assert.optionalNumber(config.maxCol, 'config.maxCol');
|
||
|
|
assert.optionalNumber(config.maxHelpCol, 'config.maxHelpCol');
|
||
|
|
assert.optionalNumber(config.minHelpCol, 'config.minHelpCol');
|
||
|
|
assert.optionalNumber(config.helpCol, 'config.helpCol');
|
||
|
|
assert.optionalBool(config.includeEnv, 'config.includeEnv');
|
||
|
|
assert.optionalBool(config.includeDefault, 'config.includeDefault');
|
||
|
|
assert.optionalBool(config.helpWrap, 'config.helpWrap');
|
||
|
|
var maxCol = config.maxCol || 80;
|
||
|
|
var minHelpCol = config.minHelpCol || 20;
|
||
|
|
var maxHelpCol = config.maxHelpCol || 40;
|
||
|
|
|
||
|
|
var lines = [];
|
||
|
|
var maxWidth = 0;
|
||
|
|
this.options.forEach(function (o) {
|
||
|
|
if (o.hidden) {
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
if (o.group !== undefined && o.group !== null) {
|
||
|
|
// We deal with groups in the next pass
|
||
|
|
lines.push(null);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
var type = optionTypes[o.type];
|
||
|
|
var arg = o.helpArg || type.helpArg || 'ARG';
|
||
|
|
var line = '';
|
||
|
|
var names = o.names.slice();
|
||
|
|
if (nameSort === 'length') {
|
||
|
|
names.sort(function (a, b) {
|
||
|
|
if (a.length < b.length)
|
||
|
|
return -1;
|
||
|
|
else if (b.length < a.length)
|
||
|
|
return 1;
|
||
|
|
else
|
||
|
|
return 0;
|
||
|
|
})
|
||
|
|
}
|
||
|
|
names.forEach(function (name, i) {
|
||
|
|
if (i > 0)
|
||
|
|
line += ', ';
|
||
|
|
if (name.length === 1) {
|
||
|
|
line += '-' + name
|
||
|
|
if (type.takesArg)
|
||
|
|
line += ' ' + arg;
|
||
|
|
} else {
|
||
|
|
line += '--' + name
|
||
|
|
if (type.takesArg)
|
||
|
|
line += '=' + arg;
|
||
|
|
}
|
||
|
|
});
|
||
|
|
maxWidth = Math.max(maxWidth, line.length);
|
||
|
|
lines.push(line);
|
||
|
|
});
|
||
|
|
|
||
|
|
// Add help strings.
|
||
|
|
var helpCol = config.helpCol;
|
||
|
|
if (!helpCol) {
|
||
|
|
helpCol = maxWidth + indent.length + 2;
|
||
|
|
helpCol = Math.min(Math.max(helpCol, minHelpCol), maxHelpCol);
|
||
|
|
}
|
||
|
|
var i = -1;
|
||
|
|
this.options.forEach(function (o) {
|
||
|
|
if (o.hidden) {
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
i++;
|
||
|
|
|
||
|
|
if (o.group !== undefined && o.group !== null) {
|
||
|
|
if (o.group === '') {
|
||
|
|
// Support a empty string "group" to have a blank line between
|
||
|
|
// sets of options.
|
||
|
|
lines[i] = '';
|
||
|
|
} else {
|
||
|
|
// Render the group heading with the heading-specific indent.
|
||
|
|
lines[i] = (i === 0 ? '' : '\n') + headingIndent +
|
||
|
|
o.group + ':';
|
||
|
|
}
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
var helpDefault;
|
||
|
|
if (config.includeDefault) {
|
||
|
|
if (o.default !== undefined) {
|
||
|
|
helpDefault = format('Default: %j', o.default);
|
||
|
|
} else if (o.type && optionTypes[o.type].default !== undefined) {
|
||
|
|
helpDefault = format('Default: %j',
|
||
|
|
optionTypes[o.type].default);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
var line = lines[i] = indent + lines[i];
|
||
|
|
if (!o.help && !(config.includeEnv && o.env) && !helpDefault) {
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
var n = helpCol - line.length;
|
||
|
|
if (n >= 0) {
|
||
|
|
line += space(n);
|
||
|
|
} else {
|
||
|
|
line += '\n' + space(helpCol);
|
||
|
|
}
|
||
|
|
|
||
|
|
var helpEnv = '';
|
||
|
|
if (o.env && o.env.length && config.includeEnv) {
|
||
|
|
helpEnv += 'Environment: ';
|
||
|
|
var type = optionTypes[o.type];
|
||
|
|
var arg = o.helpArg || type.helpArg || 'ARG';
|
||
|
|
var envs = (Array.isArray(o.env) ? o.env : [o.env]).map(
|
||
|
|
function (e) {
|
||
|
|
if (type.takesArg) {
|
||
|
|
return e + '=' + arg;
|
||
|
|
} else {
|
||
|
|
return e + '=1';
|
||
|
|
}
|
||
|
|
}
|
||
|
|
);
|
||
|
|
helpEnv += envs.join(', ');
|
||
|
|
}
|
||
|
|
var help = (o.help || '').trim();
|
||
|
|
if (o.helpWrap !== false && config.helpWrap !== false) {
|
||
|
|
// Wrap help description normally.
|
||
|
|
if (help.length && !~'.!?"\''.indexOf(help.slice(-1))) {
|
||
|
|
help += '.';
|
||
|
|
}
|
||
|
|
if (help.length) {
|
||
|
|
help += ' ';
|
||
|
|
}
|
||
|
|
help += helpEnv;
|
||
|
|
if (helpDefault) {
|
||
|
|
if (helpEnv) {
|
||
|
|
help += '. ';
|
||
|
|
}
|
||
|
|
help += helpDefault;
|
||
|
|
}
|
||
|
|
line += textwrap(help, maxCol - helpCol).join(
|
||
|
|
'\n' + space(helpCol));
|
||
|
|
} else {
|
||
|
|
// Do not wrap help description, but indent newlines appropriately.
|
||
|
|
var helpLines = help.split('\n').filter(
|
||
|
|
function (ln) { return ln.length });
|
||
|
|
if (helpEnv !== '') {
|
||
|
|
helpLines.push(helpEnv);
|
||
|
|
}
|
||
|
|
if (helpDefault) {
|
||
|
|
helpLines.push(helpDefault);
|
||
|
|
}
|
||
|
|
line += helpLines.join('\n' + space(helpCol));
|
||
|
|
}
|
||
|
|
|
||
|
|
lines[i] = line;
|
||
|
|
});
|
||
|
|
|
||
|
|
var rv = '';
|
||
|
|
if (lines.length > 0) {
|
||
|
|
rv = lines.join('\n') + '\n';
|
||
|
|
}
|
||
|
|
return rv;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return a string suitable for a Bash completion file for this tool.
|
||
|
|
*
|
||
|
|
* @param args.name {String} The tool name.
|
||
|
|
* @param args.specExtra {String} Optional. Extra Bash code content to add
|
||
|
|
* to the end of the "spec". Typically this is used to append Bash
|
||
|
|
* "complete_TYPE" functions for custom option types. See
|
||
|
|
* "examples/ddcompletion.js" for an example.
|
||
|
|
* @param args.argtypes {Array} Optional. Array of completion types for
|
||
|
|
* positional args (i.e. non-options). E.g.
|
||
|
|
* argtypes = ['fruit', 'veggie', 'file']
|
||
|
|
* will result in completion of fruits for the first arg, veggies for the
|
||
|
|
* second, and filenames for the third and subsequent positional args.
|
||
|
|
* If not given, positional args will use Bash's 'default' completion.
|
||
|
|
* See `specExtra` for providing Bash `complete_TYPE` functions, e.g.
|
||
|
|
* `complete_fruit` and `complete_veggie` in this example.
|
||
|
|
*/
|
||
|
|
Parser.prototype.bashCompletion = function bashCompletion(args) {
|
||
|
|
assert.object(args, 'args');
|
||
|
|
assert.string(args.name, 'args.name');
|
||
|
|
assert.optionalString(args.specExtra, 'args.specExtra');
|
||
|
|
assert.optionalArrayOfString(args.argtypes, 'args.argtypes');
|
||
|
|
|
||
|
|
return bashCompletionFromOptions({
|
||
|
|
name: args.name,
|
||
|
|
specExtra: args.specExtra,
|
||
|
|
argtypes: args.argtypes,
|
||
|
|
options: this.options
|
||
|
|
});
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
// ---- Bash completion
|
||
|
|
|
||
|
|
const BASH_COMPLETION_TEMPLATE_PATH = path.join(
|
||
|
|
__dirname, '../etc/dashdash.bash_completion.in');
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return the Bash completion "spec" (the string value for the "{{spec}}"
|
||
|
|
* var in the "dashdash.bash_completion.in" template) for this tool.
|
||
|
|
*
|
||
|
|
* The "spec" is Bash code that defines the CLI options and subcmds for
|
||
|
|
* the template's completion code. It looks something like this:
|
||
|
|
*
|
||
|
|
* local cmd_shortopts="-J ..."
|
||
|
|
* local cmd_longopts="--help ..."
|
||
|
|
* local cmd_optargs="-p=tritonprofile ..."
|
||
|
|
*
|
||
|
|
* @param args.options {Array} The array of dashdash option specs.
|
||
|
|
* @param args.context {String} Optional. A context string for the "local cmd*"
|
||
|
|
* vars in the spec. By default it is the empty string. When used to
|
||
|
|
* scope for completion on a *sub-command* (e.g. for "git log" on a "git"
|
||
|
|
* tool), then it would have a value (e.g. "__log"). See
|
||
|
|
* <http://github.com/trentm/node-cmdln> Bash completion for details.
|
||
|
|
* @param opts.includeHidden {Boolean} Optional. Default false. By default
|
||
|
|
* hidden options and subcmds are "excluded". Here excluded means they
|
||
|
|
* won't be offered as a completion, but if used, their argument type
|
||
|
|
* will be completed. "Hidden" options and subcmds are ones with the
|
||
|
|
* `hidden: true` attribute to exclude them from default help output.
|
||
|
|
* @param args.argtypes {Array} Optional. Array of completion types for
|
||
|
|
* positional args (i.e. non-options). E.g.
|
||
|
|
* argtypes = ['fruit', 'veggie', 'file']
|
||
|
|
* will result in completion of fruits for the first arg, veggies for the
|
||
|
|
* second, and filenames for the third and subsequent positional args.
|
||
|
|
* If not given, positional args will use Bash's 'default' completion.
|
||
|
|
* See `specExtra` for providing Bash `complete_TYPE` functions, e.g.
|
||
|
|
* `complete_fruit` and `complete_veggie` in this example.
|
||
|
|
*/
|
||
|
|
function bashCompletionSpecFromOptions(args) {
|
||
|
|
assert.object(args, 'args');
|
||
|
|
assert.object(args.options, 'args.options');
|
||
|
|
assert.optionalString(args.context, 'args.context');
|
||
|
|
assert.optionalBool(args.includeHidden, 'args.includeHidden');
|
||
|
|
assert.optionalArrayOfString(args.argtypes, 'args.argtypes');
|
||
|
|
|
||
|
|
var context = args.context || '';
|
||
|
|
var includeHidden = (args.includeHidden === undefined
|
||
|
|
? false : args.includeHidden);
|
||
|
|
|
||
|
|
var spec = [];
|
||
|
|
var shortopts = [];
|
||
|
|
var longopts = [];
|
||
|
|
var optargs = [];
|
||
|
|
(args.options || []).forEach(function (o) {
|
||
|
|
if (o.group !== undefined && o.group !== null) {
|
||
|
|
// Skip group headers.
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
var optNames = o.names || [o.name];
|
||
|
|
var optType = getOptionType(o.type);
|
||
|
|
if (optType.takesArg) {
|
||
|
|
var completionType = o.completionType ||
|
||
|
|
optType.completionType || o.type;
|
||
|
|
optNames.forEach(function (optName) {
|
||
|
|
if (optName.length === 1) {
|
||
|
|
if (includeHidden || !o.hidden) {
|
||
|
|
shortopts.push('-' + optName);
|
||
|
|
}
|
||
|
|
// Include even hidden options in `optargs` so that bash
|
||
|
|
// completion of its arg still works.
|
||
|
|
optargs.push('-' + optName + '=' + completionType);
|
||
|
|
} else {
|
||
|
|
if (includeHidden || !o.hidden) {
|
||
|
|
longopts.push('--' + optName);
|
||
|
|
}
|
||
|
|
optargs.push('--' + optName + '=' + completionType);
|
||
|
|
}
|
||
|
|
});
|
||
|
|
} else {
|
||
|
|
optNames.forEach(function (optName) {
|
||
|
|
if (includeHidden || !o.hidden) {
|
||
|
|
if (optName.length === 1) {
|
||
|
|
shortopts.push('-' + optName);
|
||
|
|
} else {
|
||
|
|
longopts.push('--' + optName);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
});
|
||
|
|
}
|
||
|
|
});
|
||
|
|
|
||
|
|
spec.push(format('local cmd%s_shortopts="%s"',
|
||
|
|
context, shortopts.sort().join(' ')));
|
||
|
|
spec.push(format('local cmd%s_longopts="%s"',
|
||
|
|
context, longopts.sort().join(' ')));
|
||
|
|
spec.push(format('local cmd%s_optargs="%s"',
|
||
|
|
context, optargs.sort().join(' ')));
|
||
|
|
if (args.argtypes) {
|
||
|
|
spec.push(format('local cmd%s_argtypes="%s"',
|
||
|
|
context, args.argtypes.join(' ')));
|
||
|
|
}
|
||
|
|
return spec.join('\n');
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return a string suitable for a Bash completion file for this tool.
|
||
|
|
*
|
||
|
|
* @param args.name {String} The tool name.
|
||
|
|
* @param args.options {Array} The array of dashdash option specs.
|
||
|
|
* @param args.specExtra {String} Optional. Extra Bash code content to add
|
||
|
|
* to the end of the "spec". Typically this is used to append Bash
|
||
|
|
* "complete_TYPE" functions for custom option types. See
|
||
|
|
* "examples/ddcompletion.js" for an example.
|
||
|
|
* @param args.argtypes {Array} Optional. Array of completion types for
|
||
|
|
* positional args (i.e. non-options). E.g.
|
||
|
|
* argtypes = ['fruit', 'veggie', 'file']
|
||
|
|
* will result in completion of fruits for the first arg, veggies for the
|
||
|
|
* second, and filenames for the third and subsequent positional args.
|
||
|
|
* If not given, positional args will use Bash's 'default' completion.
|
||
|
|
* See `specExtra` for providing Bash `complete_TYPE` functions, e.g.
|
||
|
|
* `complete_fruit` and `complete_veggie` in this example.
|
||
|
|
*/
|
||
|
|
function bashCompletionFromOptions(args) {
|
||
|
|
assert.object(args, 'args');
|
||
|
|
assert.object(args.options, 'args.options');
|
||
|
|
assert.string(args.name, 'args.name');
|
||
|
|
assert.optionalString(args.specExtra, 'args.specExtra');
|
||
|
|
assert.optionalArrayOfString(args.argtypes, 'args.argtypes');
|
||
|
|
|
||
|
|
// Gather template data.
|
||
|
|
var data = {
|
||
|
|
name: args.name,
|
||
|
|
date: new Date(),
|
||
|
|
spec: bashCompletionSpecFromOptions({
|
||
|
|
options: args.options,
|
||
|
|
argtypes: args.argtypes
|
||
|
|
}),
|
||
|
|
};
|
||
|
|
if (args.specExtra) {
|
||
|
|
data.spec += '\n\n' + args.specExtra;
|
||
|
|
}
|
||
|
|
|
||
|
|
// Render template.
|
||
|
|
var template = fs.readFileSync(BASH_COMPLETION_TEMPLATE_PATH, 'utf8');
|
||
|
|
return renderTemplate(template, data);
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
// ---- exports
|
||
|
|
|
||
|
|
function createParser(config) {
|
||
|
|
return new Parser(config);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Parse argv with the given options.
|
||
|
|
*
|
||
|
|
* @param config {Object} A merge of all the available fields from
|
||
|
|
* `dashdash.Parser` and `dashdash.Parser.parse`: options, interspersed,
|
||
|
|
* argv, env, slice.
|
||
|
|
*/
|
||
|
|
function parse(config) {
|
||
|
|
assert.object(config, 'config');
|
||
|
|
assert.optionalArrayOfString(config.argv, 'config.argv');
|
||
|
|
assert.optionalObject(config.env, 'config.env');
|
||
|
|
var config = shallowCopy(config);
|
||
|
|
var argv = config.argv;
|
||
|
|
delete config.argv;
|
||
|
|
var env = config.env;
|
||
|
|
delete config.env;
|
||
|
|
|
||
|
|
var parser = new Parser(config);
|
||
|
|
return parser.parse({argv: argv, env: env});
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Add a new option type.
|
||
|
|
*
|
||
|
|
* @params optionType {Object}:
|
||
|
|
* - name {String} Required.
|
||
|
|
* - takesArg {Boolean} Required. Whether this type of option takes an
|
||
|
|
* argument on process.argv. Typically this is true for all but the
|
||
|
|
* "bool" type.
|
||
|
|
* - helpArg {String} Required iff `takesArg === true`. The string to
|
||
|
|
* show in generated help for options of this type.
|
||
|
|
* - parseArg {Function} Require. `function (option, optstr, arg)` parser
|
||
|
|
* that takes a string argument and returns an instance of the
|
||
|
|
* appropriate type, or throws an error if the arg is invalid.
|
||
|
|
* - array {Boolean} Optional. Set to true if this is an 'arrayOf' type
|
||
|
|
* that collects multiple usages of the option in process.argv and
|
||
|
|
* puts results in an array.
|
||
|
|
* - arrayFlatten {Boolean} Optional. XXX
|
||
|
|
* - default Optional. Default value for options of this type, if no
|
||
|
|
* default is specified in the option type usage.
|
||
|
|
*/
|
||
|
|
function addOptionType(optionType) {
|
||
|
|
assert.object(optionType, 'optionType');
|
||
|
|
assert.string(optionType.name, 'optionType.name');
|
||
|
|
assert.bool(optionType.takesArg, 'optionType.takesArg');
|
||
|
|
if (optionType.takesArg) {
|
||
|
|
assert.string(optionType.helpArg, 'optionType.helpArg');
|
||
|
|
}
|
||
|
|
assert.func(optionType.parseArg, 'optionType.parseArg');
|
||
|
|
assert.optionalBool(optionType.array, 'optionType.array');
|
||
|
|
assert.optionalBool(optionType.arrayFlatten, 'optionType.arrayFlatten');
|
||
|
|
|
||
|
|
optionTypes[optionType.name] = {
|
||
|
|
takesArg: optionType.takesArg,
|
||
|
|
helpArg: optionType.helpArg,
|
||
|
|
parseArg: optionType.parseArg,
|
||
|
|
array: optionType.array,
|
||
|
|
arrayFlatten: optionType.arrayFlatten,
|
||
|
|
default: optionType.default
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
function getOptionType(name) {
|
||
|
|
assert.string(name, 'name');
|
||
|
|
return optionTypes[name];
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
module.exports = {
|
||
|
|
createParser: createParser,
|
||
|
|
Parser: Parser,
|
||
|
|
parse: parse,
|
||
|
|
addOptionType: addOptionType,
|
||
|
|
getOptionType: getOptionType,
|
||
|
|
|
||
|
|
// Bash completion-related exports
|
||
|
|
BASH_COMPLETION_TEMPLATE_PATH: BASH_COMPLETION_TEMPLATE_PATH,
|
||
|
|
bashCompletionFromOptions: bashCompletionFromOptions,
|
||
|
|
bashCompletionSpecFromOptions: bashCompletionSpecFromOptions,
|
||
|
|
|
||
|
|
// Export the parseFoo parsers because they might be useful as primitives
|
||
|
|
// for custom option types.
|
||
|
|
parseBool: parseBool,
|
||
|
|
parseString: parseString,
|
||
|
|
parseNumber: parseNumber,
|
||
|
|
parseInteger: parseInteger,
|
||
|
|
parsePositiveInteger: parsePositiveInteger,
|
||
|
|
parseDate: parseDate
|
||
|
|
};
|