l0bsterssg

formatter.js (22025B)

---

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