/**
|
* class HelpFormatter
|
*
|
* Formatter for generating usage messages and argument help strings. Only the
|
* name of this class is considered a public API. All the methods provided by
|
* the class are considered an implementation detail.
|
*
|
* Do not call in your code, use this class only for inherits your own forvatter
|
*
|
* ToDo add [additonal formatters][1]
|
*
|
* [1]:http://docs.python.org/dev/library/argparse.html#formatter-class
|
**/
|
'use strict';
|
|
var sprintf = require('sprintf-js').sprintf;
|
|
// Constants
|
var c = require('../const');
|
|
var $$ = require('../utils');
|
|
|
/*:nodoc:* internal
|
* new Support(parent, heding)
|
* - parent (object): parent section
|
* - heading (string): header string
|
*
|
**/
|
function Section(parent, heading) {
|
this._parent = parent;
|
this._heading = heading;
|
this._items = [];
|
}
|
|
/*:nodoc:* internal
|
* Section#addItem(callback) -> Void
|
* - callback (array): tuple with function and args
|
*
|
* Add function for single element
|
**/
|
Section.prototype.addItem = function (callback) {
|
this._items.push(callback);
|
};
|
|
/*:nodoc:* internal
|
* Section#formatHelp(formatter) -> string
|
* - formatter (HelpFormatter): current formatter
|
*
|
* Form help section string
|
*
|
**/
|
Section.prototype.formatHelp = function (formatter) {
|
var itemHelp, heading;
|
|
// format the indented section
|
if (this._parent) {
|
formatter._indent();
|
}
|
|
itemHelp = this._items.map(function (item) {
|
var obj, func, args;
|
|
obj = formatter;
|
func = item[0];
|
args = item[1];
|
return func.apply(obj, args);
|
});
|
itemHelp = formatter._joinParts(itemHelp);
|
|
if (this._parent) {
|
formatter._dedent();
|
}
|
|
// return nothing if the section was empty
|
if (!itemHelp) {
|
return '';
|
}
|
|
// add the heading if the section was non-empty
|
heading = '';
|
if (this._heading && this._heading !== c.SUPPRESS) {
|
var currentIndent = formatter.currentIndent;
|
heading = $$.repeat(' ', currentIndent) + this._heading + ':' + c.EOL;
|
}
|
|
// join the section-initialize newline, the heading and the help
|
return formatter._joinParts([ c.EOL, heading, itemHelp, c.EOL ]);
|
};
|
|
/**
|
* new HelpFormatter(options)
|
*
|
* #### Options:
|
* - `prog`: program name
|
* - `indentIncriment`: indent step, default value 2
|
* - `maxHelpPosition`: max help position, default value = 24
|
* - `width`: line width
|
*
|
**/
|
var HelpFormatter = module.exports = function HelpFormatter(options) {
|
options = options || {};
|
|
this._prog = options.prog;
|
|
this._maxHelpPosition = options.maxHelpPosition || 24;
|
this._width = (options.width || ((process.env.COLUMNS || 80) - 2));
|
|
this._currentIndent = 0;
|
this._indentIncriment = options.indentIncriment || 2;
|
this._level = 0;
|
this._actionMaxLength = 0;
|
|
this._rootSection = new Section(null);
|
this._currentSection = this._rootSection;
|
|
this._whitespaceMatcher = new RegExp('\\s+', 'g');
|
this._longBreakMatcher = new RegExp(c.EOL + c.EOL + c.EOL + '+', 'g');
|
};
|
|
HelpFormatter.prototype._indent = function () {
|
this._currentIndent += this._indentIncriment;
|
this._level += 1;
|
};
|
|
HelpFormatter.prototype._dedent = function () {
|
this._currentIndent -= this._indentIncriment;
|
this._level -= 1;
|
if (this._currentIndent < 0) {
|
throw new Error('Indent decreased below 0.');
|
}
|
};
|
|
HelpFormatter.prototype._addItem = function (func, args) {
|
this._currentSection.addItem([ func, args ]);
|
};
|
|
//
|
// Message building methods
|
//
|
|
/**
|
* HelpFormatter#startSection(heading) -> Void
|
* - heading (string): header string
|
*
|
* Start new help section
|
*
|
* See alse [code example][1]
|
*
|
* ##### Example
|
*
|
* formatter.startSection(actionGroup.title);
|
* formatter.addText(actionGroup.description);
|
* formatter.addArguments(actionGroup._groupActions);
|
* formatter.endSection();
|
*
|
**/
|
HelpFormatter.prototype.startSection = function (heading) {
|
this._indent();
|
var section = new Section(this._currentSection, heading);
|
var func = section.formatHelp.bind(section);
|
this._addItem(func, [ this ]);
|
this._currentSection = section;
|
};
|
|
/**
|
* HelpFormatter#endSection -> Void
|
*
|
* End help section
|
*
|
* ##### Example
|
*
|
* formatter.startSection(actionGroup.title);
|
* formatter.addText(actionGroup.description);
|
* formatter.addArguments(actionGroup._groupActions);
|
* formatter.endSection();
|
**/
|
HelpFormatter.prototype.endSection = function () {
|
this._currentSection = this._currentSection._parent;
|
this._dedent();
|
};
|
|
/**
|
* HelpFormatter#addText(text) -> Void
|
* - text (string): plain text
|
*
|
* Add plain text into current section
|
*
|
* ##### Example
|
*
|
* formatter.startSection(actionGroup.title);
|
* formatter.addText(actionGroup.description);
|
* formatter.addArguments(actionGroup._groupActions);
|
* formatter.endSection();
|
*
|
**/
|
HelpFormatter.prototype.addText = function (text) {
|
if (text && text !== c.SUPPRESS) {
|
this._addItem(this._formatText, [ text ]);
|
}
|
};
|
|
/**
|
* HelpFormatter#addUsage(usage, actions, groups, prefix) -> Void
|
* - usage (string): usage text
|
* - actions (array): actions list
|
* - groups (array): groups list
|
* - prefix (string): usage prefix
|
*
|
* Add usage data into current section
|
*
|
* ##### Example
|
*
|
* formatter.addUsage(this.usage, this._actions, []);
|
* return formatter.formatHelp();
|
*
|
**/
|
HelpFormatter.prototype.addUsage = function (usage, actions, groups, prefix) {
|
if (usage !== c.SUPPRESS) {
|
this._addItem(this._formatUsage, [ usage, actions, groups, prefix ]);
|
}
|
};
|
|
/**
|
* HelpFormatter#addArgument(action) -> Void
|
* - action (object): action
|
*
|
* Add argument into current section
|
*
|
* Single variant of [[HelpFormatter#addArguments]]
|
**/
|
HelpFormatter.prototype.addArgument = function (action) {
|
if (action.help !== c.SUPPRESS) {
|
var self = this;
|
|
// find all invocations
|
var invocations = [ this._formatActionInvocation(action) ];
|
var invocationLength = invocations[0].length;
|
|
var actionLength;
|
|
if (action._getSubactions) {
|
this._indent();
|
action._getSubactions().forEach(function (subaction) {
|
|
var invocationNew = self._formatActionInvocation(subaction);
|
invocations.push(invocationNew);
|
invocationLength = Math.max(invocationLength, invocationNew.length);
|
|
});
|
this._dedent();
|
}
|
|
// update the maximum item length
|
actionLength = invocationLength + this._currentIndent;
|
this._actionMaxLength = Math.max(this._actionMaxLength, actionLength);
|
|
// add the item to the list
|
this._addItem(this._formatAction, [ action ]);
|
}
|
};
|
|
/**
|
* HelpFormatter#addArguments(actions) -> Void
|
* - actions (array): actions list
|
*
|
* Mass add arguments into current section
|
*
|
* ##### Example
|
*
|
* formatter.startSection(actionGroup.title);
|
* formatter.addText(actionGroup.description);
|
* formatter.addArguments(actionGroup._groupActions);
|
* formatter.endSection();
|
*
|
**/
|
HelpFormatter.prototype.addArguments = function (actions) {
|
var self = this;
|
actions.forEach(function (action) {
|
self.addArgument(action);
|
});
|
};
|
|
//
|
// Help-formatting methods
|
//
|
|
/**
|
* HelpFormatter#formatHelp -> string
|
*
|
* Format help
|
*
|
* ##### Example
|
*
|
* formatter.addText(this.epilog);
|
* return formatter.formatHelp();
|
*
|
**/
|
HelpFormatter.prototype.formatHelp = function () {
|
var help = this._rootSection.formatHelp(this);
|
if (help) {
|
help = help.replace(this._longBreakMatcher, c.EOL + c.EOL);
|
help = $$.trimChars(help, c.EOL) + c.EOL;
|
}
|
return help;
|
};
|
|
HelpFormatter.prototype._joinParts = function (partStrings) {
|
return partStrings.filter(function (part) {
|
return (part && part !== c.SUPPRESS);
|
}).join('');
|
};
|
|
HelpFormatter.prototype._formatUsage = function (usage, actions, groups, prefix) {
|
if (!prefix && typeof prefix !== 'string') {
|
prefix = 'usage: ';
|
}
|
|
actions = actions || [];
|
groups = groups || [];
|
|
|
// if usage is specified, use that
|
if (usage) {
|
usage = sprintf(usage, { prog: this._prog });
|
|
// if no optionals or positionals are available, usage is just prog
|
} else if (!usage && actions.length === 0) {
|
usage = this._prog;
|
|
// if optionals and positionals are available, calculate usage
|
} else if (!usage) {
|
var prog = this._prog;
|
var optionals = [];
|
var positionals = [];
|
var actionUsage;
|
var textWidth;
|
|
// split optionals from positionals
|
actions.forEach(function (action) {
|
if (action.isOptional()) {
|
optionals.push(action);
|
} else {
|
positionals.push(action);
|
}
|
});
|
|
// build full usage string
|
actionUsage = this._formatActionsUsage([].concat(optionals, positionals), groups);
|
usage = [ prog, actionUsage ].join(' ');
|
|
// wrap the usage parts if it's too long
|
textWidth = this._width - this._currentIndent;
|
if ((prefix.length + usage.length) > textWidth) {
|
|
// break usage into wrappable parts
|
var regexpPart = new RegExp('\\(.*?\\)+|\\[.*?\\]+|\\S+', 'g');
|
var optionalUsage = this._formatActionsUsage(optionals, groups);
|
var positionalUsage = this._formatActionsUsage(positionals, groups);
|
|
|
var optionalParts = optionalUsage.match(regexpPart);
|
var positionalParts = positionalUsage.match(regexpPart) || [];
|
|
if (optionalParts.join(' ') !== optionalUsage) {
|
throw new Error('assert "optionalParts.join(\' \') === optionalUsage"');
|
}
|
if (positionalParts.join(' ') !== positionalUsage) {
|
throw new Error('assert "positionalParts.join(\' \') === positionalUsage"');
|
}
|
|
// helper for wrapping lines
|
/*eslint-disable func-style*/ // node 0.10 compat
|
var _getLines = function (parts, indent, prefix) {
|
var lines = [];
|
var line = [];
|
|
var lineLength = prefix ? prefix.length - 1 : indent.length - 1;
|
|
parts.forEach(function (part) {
|
if (lineLength + 1 + part.length > textWidth) {
|
lines.push(indent + line.join(' '));
|
line = [];
|
lineLength = indent.length - 1;
|
}
|
line.push(part);
|
lineLength += part.length + 1;
|
});
|
|
if (line) {
|
lines.push(indent + line.join(' '));
|
}
|
if (prefix) {
|
lines[0] = lines[0].substr(indent.length);
|
}
|
return lines;
|
};
|
|
var lines, indent, parts;
|
// if prog is short, follow it with optionals or positionals
|
if (prefix.length + prog.length <= 0.75 * textWidth) {
|
indent = $$.repeat(' ', (prefix.length + prog.length + 1));
|
if (optionalParts) {
|
lines = [].concat(
|
_getLines([ prog ].concat(optionalParts), indent, prefix),
|
_getLines(positionalParts, indent)
|
);
|
} else if (positionalParts) {
|
lines = _getLines([ prog ].concat(positionalParts), indent, prefix);
|
} else {
|
lines = [ prog ];
|
}
|
|
// if prog is long, put it on its own line
|
} else {
|
indent = $$.repeat(' ', prefix.length);
|
parts = optionalParts.concat(positionalParts);
|
lines = _getLines(parts, indent);
|
if (lines.length > 1) {
|
lines = [].concat(
|
_getLines(optionalParts, indent),
|
_getLines(positionalParts, indent)
|
);
|
}
|
lines = [ prog ].concat(lines);
|
}
|
// join lines into usage
|
usage = lines.join(c.EOL);
|
}
|
}
|
|
// prefix with 'usage:'
|
return prefix + usage + c.EOL + c.EOL;
|
};
|
|
HelpFormatter.prototype._formatActionsUsage = function (actions, groups) {
|
// find group indices and identify actions in groups
|
var groupActions = [];
|
var inserts = [];
|
var self = this;
|
|
groups.forEach(function (group) {
|
var end;
|
var i;
|
|
var start = actions.indexOf(group._groupActions[0]);
|
if (start >= 0) {
|
end = start + group._groupActions.length;
|
|
//if (actions.slice(start, end) === group._groupActions) {
|
if ($$.arrayEqual(actions.slice(start, end), group._groupActions)) {
|
group._groupActions.forEach(function (action) {
|
groupActions.push(action);
|
});
|
|
if (!group.required) {
|
if (inserts[start]) {
|
inserts[start] += ' [';
|
} else {
|
inserts[start] = '[';
|
}
|
inserts[end] = ']';
|
} else {
|
if (inserts[start]) {
|
inserts[start] += ' (';
|
} else {
|
inserts[start] = '(';
|
}
|
inserts[end] = ')';
|
}
|
for (i = start + 1; i < end; i += 1) {
|
inserts[i] = '|';
|
}
|
}
|
}
|
});
|
|
// collect all actions format strings
|
var parts = [];
|
|
actions.forEach(function (action, actionIndex) {
|
var part;
|
var optionString;
|
var argsDefault;
|
var argsString;
|
|
// suppressed arguments are marked with None
|
// remove | separators for suppressed arguments
|
if (action.help === c.SUPPRESS) {
|
parts.push(null);
|
if (inserts[actionIndex] === '|') {
|
inserts.splice(actionIndex, actionIndex);
|
} else if (inserts[actionIndex + 1] === '|') {
|
inserts.splice(actionIndex + 1, actionIndex + 1);
|
}
|
|
// produce all arg strings
|
} else if (!action.isOptional()) {
|
part = self._formatArgs(action, action.dest);
|
|
// if it's in a group, strip the outer []
|
if (groupActions.indexOf(action) >= 0) {
|
if (part[0] === '[' && part[part.length - 1] === ']') {
|
part = part.slice(1, -1);
|
}
|
}
|
// add the action string to the list
|
parts.push(part);
|
|
// produce the first way to invoke the option in brackets
|
} else {
|
optionString = action.optionStrings[0];
|
|
// if the Optional doesn't take a value, format is: -s or --long
|
if (action.nargs === 0) {
|
part = '' + optionString;
|
|
// if the Optional takes a value, format is: -s ARGS or --long ARGS
|
} else {
|
argsDefault = action.dest.toUpperCase();
|
argsString = self._formatArgs(action, argsDefault);
|
part = optionString + ' ' + argsString;
|
}
|
// make it look optional if it's not required or in a group
|
if (!action.required && groupActions.indexOf(action) < 0) {
|
part = '[' + part + ']';
|
}
|
// add the action string to the list
|
parts.push(part);
|
}
|
});
|
|
// insert things at the necessary indices
|
for (var i = inserts.length - 1; i >= 0; --i) {
|
if (inserts[i] !== null) {
|
parts.splice(i, 0, inserts[i]);
|
}
|
}
|
|
// join all the action items with spaces
|
var text = parts.filter(function (part) {
|
return !!part;
|
}).join(' ');
|
|
// clean up separators for mutually exclusive groups
|
text = text.replace(/([\[(]) /g, '$1'); // remove spaces
|
text = text.replace(/ ([\])])/g, '$1');
|
text = text.replace(/\[ *\]/g, ''); // remove empty groups
|
text = text.replace(/\( *\)/g, '');
|
text = text.replace(/\(([^|]*)\)/g, '$1'); // remove () from single action groups
|
|
text = text.trim();
|
|
// return the text
|
return text;
|
};
|
|
HelpFormatter.prototype._formatText = function (text) {
|
text = sprintf(text, { prog: this._prog });
|
var textWidth = this._width - this._currentIndent;
|
var indentIncriment = $$.repeat(' ', this._currentIndent);
|
return this._fillText(text, textWidth, indentIncriment) + c.EOL + c.EOL;
|
};
|
|
HelpFormatter.prototype._formatAction = function (action) {
|
var self = this;
|
|
var helpText;
|
var helpLines;
|
var parts;
|
var indentFirst;
|
|
// determine the required width and the entry label
|
var helpPosition = Math.min(this._actionMaxLength + 2, this._maxHelpPosition);
|
var helpWidth = this._width - helpPosition;
|
var actionWidth = helpPosition - this._currentIndent - 2;
|
var actionHeader = this._formatActionInvocation(action);
|
|
// no help; start on same line and add a final newline
|
if (!action.help) {
|
actionHeader = $$.repeat(' ', this._currentIndent) + actionHeader + c.EOL;
|
|
// short action name; start on the same line and pad two spaces
|
} else if (actionHeader.length <= actionWidth) {
|
actionHeader = $$.repeat(' ', this._currentIndent) +
|
actionHeader +
|
' ' +
|
$$.repeat(' ', actionWidth - actionHeader.length);
|
indentFirst = 0;
|
|
// long action name; start on the next line
|
} else {
|
actionHeader = $$.repeat(' ', this._currentIndent) + actionHeader + c.EOL;
|
indentFirst = helpPosition;
|
}
|
|
// collect the pieces of the action help
|
parts = [ actionHeader ];
|
|
// if there was help for the action, add lines of help text
|
if (action.help) {
|
helpText = this._expandHelp(action);
|
helpLines = this._splitLines(helpText, helpWidth);
|
parts.push($$.repeat(' ', indentFirst) + helpLines[0] + c.EOL);
|
helpLines.slice(1).forEach(function (line) {
|
parts.push($$.repeat(' ', helpPosition) + line + c.EOL);
|
});
|
|
// or add a newline if the description doesn't end with one
|
} else if (actionHeader.charAt(actionHeader.length - 1) !== c.EOL) {
|
parts.push(c.EOL);
|
}
|
// if there are any sub-actions, add their help as well
|
if (action._getSubactions) {
|
this._indent();
|
action._getSubactions().forEach(function (subaction) {
|
parts.push(self._formatAction(subaction));
|
});
|
this._dedent();
|
}
|
// return a single string
|
return this._joinParts(parts);
|
};
|
|
HelpFormatter.prototype._formatActionInvocation = function (action) {
|
if (!action.isOptional()) {
|
var format_func = this._metavarFormatter(action, action.dest);
|
var metavars = format_func(1);
|
return metavars[0];
|
}
|
|
var parts = [];
|
var argsDefault;
|
var argsString;
|
|
// if the Optional doesn't take a value, format is: -s, --long
|
if (action.nargs === 0) {
|
parts = parts.concat(action.optionStrings);
|
|
// if the Optional takes a value, format is: -s ARGS, --long ARGS
|
} else {
|
argsDefault = action.dest.toUpperCase();
|
argsString = this._formatArgs(action, argsDefault);
|
action.optionStrings.forEach(function (optionString) {
|
parts.push(optionString + ' ' + argsString);
|
});
|
}
|
return parts.join(', ');
|
};
|
|
HelpFormatter.prototype._metavarFormatter = function (action, metavarDefault) {
|
var result;
|
|
if (action.metavar || action.metavar === '') {
|
result = action.metavar;
|
} else if (action.choices) {
|
var choices = action.choices;
|
|
if (typeof choices === 'string') {
|
choices = choices.split('').join(', ');
|
} else if (Array.isArray(choices)) {
|
choices = choices.join(',');
|
} else {
|
choices = Object.keys(choices).join(',');
|
}
|
result = '{' + choices + '}';
|
} else {
|
result = metavarDefault;
|
}
|
|
return function (size) {
|
if (Array.isArray(result)) {
|
return result;
|
}
|
|
var metavars = [];
|
for (var i = 0; i < size; i += 1) {
|
metavars.push(result);
|
}
|
return metavars;
|
};
|
};
|
|
HelpFormatter.prototype._formatArgs = function (action, metavarDefault) {
|
var result;
|
var metavars;
|
|
var buildMetavar = this._metavarFormatter(action, metavarDefault);
|
|
switch (action.nargs) {
|
/*eslint-disable no-undefined*/
|
case undefined:
|
case null:
|
metavars = buildMetavar(1);
|
result = '' + metavars[0];
|
break;
|
case c.OPTIONAL:
|
metavars = buildMetavar(1);
|
result = '[' + metavars[0] + ']';
|
break;
|
case c.ZERO_OR_MORE:
|
metavars = buildMetavar(2);
|
result = '[' + metavars[0] + ' [' + metavars[1] + ' ...]]';
|
break;
|
case c.ONE_OR_MORE:
|
metavars = buildMetavar(2);
|
result = '' + metavars[0] + ' [' + metavars[1] + ' ...]';
|
break;
|
case c.REMAINDER:
|
result = '...';
|
break;
|
case c.PARSER:
|
metavars = buildMetavar(1);
|
result = metavars[0] + ' ...';
|
break;
|
default:
|
metavars = buildMetavar(action.nargs);
|
result = metavars.join(' ');
|
}
|
return result;
|
};
|
|
HelpFormatter.prototype._expandHelp = function (action) {
|
var params = { prog: this._prog };
|
|
Object.keys(action).forEach(function (actionProperty) {
|
var actionValue = action[actionProperty];
|
|
if (actionValue !== c.SUPPRESS) {
|
params[actionProperty] = actionValue;
|
}
|
});
|
|
if (params.choices) {
|
if (typeof params.choices === 'string') {
|
params.choices = params.choices.split('').join(', ');
|
} else if (Array.isArray(params.choices)) {
|
params.choices = params.choices.join(', ');
|
} else {
|
params.choices = Object.keys(params.choices).join(', ');
|
}
|
}
|
|
return sprintf(this._getHelpString(action), params);
|
};
|
|
HelpFormatter.prototype._splitLines = function (text, width) {
|
var lines = [];
|
var delimiters = [ ' ', '.', ',', '!', '?' ];
|
var re = new RegExp('[' + delimiters.join('') + '][^' + delimiters.join('') + ']*$');
|
|
text = text.replace(/[\n\|\t]/g, ' ');
|
|
text = text.trim();
|
text = text.replace(this._whitespaceMatcher, ' ');
|
|
// Wraps the single paragraph in text (a string) so every line
|
// is at most width characters long.
|
text.split(c.EOL).forEach(function (line) {
|
if (width >= line.length) {
|
lines.push(line);
|
return;
|
}
|
|
var wrapStart = 0;
|
var wrapEnd = width;
|
var delimiterIndex = 0;
|
while (wrapEnd <= line.length) {
|
if (wrapEnd !== line.length && delimiters.indexOf(line[wrapEnd] < -1)) {
|
delimiterIndex = (re.exec(line.substring(wrapStart, wrapEnd)) || {}).index;
|
wrapEnd = wrapStart + delimiterIndex + 1;
|
}
|
lines.push(line.substring(wrapStart, wrapEnd));
|
wrapStart = wrapEnd;
|
wrapEnd += width;
|
}
|
if (wrapStart < line.length) {
|
lines.push(line.substring(wrapStart, wrapEnd));
|
}
|
});
|
|
return lines;
|
};
|
|
HelpFormatter.prototype._fillText = function (text, width, indent) {
|
var lines = this._splitLines(text, width);
|
lines = lines.map(function (line) {
|
return indent + line;
|
});
|
return lines.join(c.EOL);
|
};
|
|
HelpFormatter.prototype._getHelpString = function (action) {
|
return action.help;
|
};
|
