| /** |
| * 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; |
| }; |