--- /dev/null
+/**
+ * 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];
+}
+
+
+/**
+ * Return a synopsis string for the given option spec.
+ *
+ * Examples:
+ * > synopsisFromOpt({names: ['help', 'h'], type: 'bool'});
+ * '[ --help | -h ]'
+ * > synopsisFromOpt({name: 'file', type: 'string', helpArg: 'FILE'});
+ * '[ --file=FILE ]'
+ */
+function synopsisFromOpt(o) {
+ assert.object(o, 'o');
+
+ if (o.hasOwnProperty('group')) {
+ return null;
+ }
+ var names = o.names || [o.name];
+ // `type` here could be undefined if, for example, the command has a
+ // dashdash option spec with a bogus 'type'.
+ var type = getOptionType(o.type);
+ var helpArg = o.helpArg || (type && type.helpArg) || 'ARG';
+ var parts = [];
+ names.forEach(function (name) {
+ var part = (name.length === 1 ? '-' : '--') + name;
+ if (type && type.takesArg) {
+ part += (name.length === 1 ? ' ' + helpArg : '=' + helpArg);
+ }
+ parts.push(part);
+ });
+ return ('[ ' + parts.join(' | ') + ' ]');
+};
+
+
+module.exports = {
+ createParser: createParser,
+ Parser: Parser,
+ parse: parse,
+ addOptionType: addOptionType,
+ getOptionType: getOptionType,
+ synopsisFromOpt: synopsisFromOpt,
+
+ // 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
+};
Code Review / simantics / district.git / blobdiff