+++ /dev/null
-/**
- * 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;
-};
projects / dotfiles / .git / blobdiff