4 * Formatter for generating usage messages and argument help strings. Only the
5 * name of this class is considered a public API. All the methods provided by
6 * the class are considered an implementation detail.
8 * Do not call in your code, use this class only for inherits your own forvatter
10 * ToDo add [additonal formatters][1]
12 * [1]:http://docs.python.org/dev/library/argparse.html#formatter-class
16 var sprintf = require('sprintf-js').sprintf;
19 var c = require('../const');
21 var $$ = require('../utils');
25 * new Support(parent, heding)
26 * - parent (object): parent section
27 * - heading (string): header string
30 function Section(parent, heading) {
31 this._parent = parent;
32 this._heading = heading;
37 * Section#addItem(callback) -> Void
38 * - callback (array): tuple with function and args
40 * Add function for single element
42 Section.prototype.addItem = function (callback) {
43 this._items.push(callback);
47 * Section#formatHelp(formatter) -> string
48 * - formatter (HelpFormatter): current formatter
50 * Form help section string
53 Section.prototype.formatHelp = function (formatter) {
54 var itemHelp, heading;
56 // format the indented section
61 itemHelp = this._items.map(function (item) {
67 return func.apply(obj, args);
69 itemHelp = formatter._joinParts(itemHelp);
75 // return nothing if the section was empty
80 // add the heading if the section was non-empty
82 if (this._heading && this._heading !== c.SUPPRESS) {
83 var currentIndent = formatter.currentIndent;
84 heading = $$.repeat(' ', currentIndent) + this._heading + ':' + c.EOL;
87 // join the section-initialize newline, the heading and the help
88 return formatter._joinParts([ c.EOL, heading, itemHelp, c.EOL ]);
92 * new HelpFormatter(options)
95 * - `prog`: program name
96 * - `indentIncriment`: indent step, default value 2
97 * - `maxHelpPosition`: max help position, default value = 24
98 * - `width`: line width
101 var HelpFormatter = module.exports = function HelpFormatter(options) {
102 options = options || {};
104 this._prog = options.prog;
106 this._maxHelpPosition = options.maxHelpPosition || 24;
107 this._width = (options.width || ((process.env.COLUMNS || 80) - 2));
109 this._currentIndent = 0;
110 this._indentIncriment = options.indentIncriment || 2;
112 this._actionMaxLength = 0;
114 this._rootSection = new Section(null);
115 this._currentSection = this._rootSection;
117 this._whitespaceMatcher = new RegExp('\\s+', 'g');
118 this._longBreakMatcher = new RegExp(c.EOL + c.EOL + c.EOL + '+', 'g');
121 HelpFormatter.prototype._indent = function () {
122 this._currentIndent += this._indentIncriment;
126 HelpFormatter.prototype._dedent = function () {
127 this._currentIndent -= this._indentIncriment;
129 if (this._currentIndent < 0) {
130 throw new Error('Indent decreased below 0.');
134 HelpFormatter.prototype._addItem = function (func, args) {
135 this._currentSection.addItem([ func, args ]);
139 // Message building methods
143 * HelpFormatter#startSection(heading) -> Void
144 * - heading (string): header string
146 * Start new help section
148 * See alse [code example][1]
152 * formatter.startSection(actionGroup.title);
153 * formatter.addText(actionGroup.description);
154 * formatter.addArguments(actionGroup._groupActions);
155 * formatter.endSection();
158 HelpFormatter.prototype.startSection = function (heading) {
160 var section = new Section(this._currentSection, heading);
161 var func = section.formatHelp.bind(section);
162 this._addItem(func, [ this ]);
163 this._currentSection = section;
167 * HelpFormatter#endSection -> Void
173 * formatter.startSection(actionGroup.title);
174 * formatter.addText(actionGroup.description);
175 * formatter.addArguments(actionGroup._groupActions);
176 * formatter.endSection();
178 HelpFormatter.prototype.endSection = function () {
179 this._currentSection = this._currentSection._parent;
184 * HelpFormatter#addText(text) -> Void
185 * - text (string): plain text
187 * Add plain text into current section
191 * formatter.startSection(actionGroup.title);
192 * formatter.addText(actionGroup.description);
193 * formatter.addArguments(actionGroup._groupActions);
194 * formatter.endSection();
197 HelpFormatter.prototype.addText = function (text) {
198 if (text && text !== c.SUPPRESS) {
199 this._addItem(this._formatText, [ text ]);
204 * HelpFormatter#addUsage(usage, actions, groups, prefix) -> Void
205 * - usage (string): usage text
206 * - actions (array): actions list
207 * - groups (array): groups list
208 * - prefix (string): usage prefix
210 * Add usage data into current section
214 * formatter.addUsage(this.usage, this._actions, []);
215 * return formatter.formatHelp();
218 HelpFormatter.prototype.addUsage = function (usage, actions, groups, prefix) {
219 if (usage !== c.SUPPRESS) {
220 this._addItem(this._formatUsage, [ usage, actions, groups, prefix ]);
225 * HelpFormatter#addArgument(action) -> Void
226 * - action (object): action
228 * Add argument into current section
230 * Single variant of [[HelpFormatter#addArguments]]
232 HelpFormatter.prototype.addArgument = function (action) {
233 if (action.help !== c.SUPPRESS) {
236 // find all invocations
237 var invocations = [ this._formatActionInvocation(action) ];
238 var invocationLength = invocations[0].length;
242 if (action._getSubactions) {
244 action._getSubactions().forEach(function (subaction) {
246 var invocationNew = self._formatActionInvocation(subaction);
247 invocations.push(invocationNew);
248 invocationLength = Math.max(invocationLength, invocationNew.length);
254 // update the maximum item length
255 actionLength = invocationLength + this._currentIndent;
256 this._actionMaxLength = Math.max(this._actionMaxLength, actionLength);
258 // add the item to the list
259 this._addItem(this._formatAction, [ action ]);
264 * HelpFormatter#addArguments(actions) -> Void
265 * - actions (array): actions list
267 * Mass add arguments into current section
271 * formatter.startSection(actionGroup.title);
272 * formatter.addText(actionGroup.description);
273 * formatter.addArguments(actionGroup._groupActions);
274 * formatter.endSection();
277 HelpFormatter.prototype.addArguments = function (actions) {
279 actions.forEach(function (action) {
280 self.addArgument(action);
285 // Help-formatting methods
289 * HelpFormatter#formatHelp -> string
295 * formatter.addText(this.epilog);
296 * return formatter.formatHelp();
299 HelpFormatter.prototype.formatHelp = function () {
300 var help = this._rootSection.formatHelp(this);
302 help = help.replace(this._longBreakMatcher, c.EOL + c.EOL);
303 help = $$.trimChars(help, c.EOL) + c.EOL;
308 HelpFormatter.prototype._joinParts = function (partStrings) {
309 return partStrings.filter(function (part) {
310 return (part && part !== c.SUPPRESS);
314 HelpFormatter.prototype._formatUsage = function (usage, actions, groups, prefix) {
315 if (!prefix && typeof prefix !== 'string') {
319 actions = actions || [];
320 groups = groups || [];
323 // if usage is specified, use that
325 usage = sprintf(usage, { prog: this._prog });
327 // if no optionals or positionals are available, usage is just prog
328 } else if (!usage && actions.length === 0) {
331 // if optionals and positionals are available, calculate usage
333 var prog = this._prog;
335 var positionals = [];
339 // split optionals from positionals
340 actions.forEach(function (action) {
341 if (action.isOptional()) {
342 optionals.push(action);
344 positionals.push(action);
348 // build full usage string
349 actionUsage = this._formatActionsUsage([].concat(optionals, positionals), groups);
350 usage = [ prog, actionUsage ].join(' ');
352 // wrap the usage parts if it's too long
353 textWidth = this._width - this._currentIndent;
354 if ((prefix.length + usage.length) > textWidth) {
356 // break usage into wrappable parts
357 var regexpPart = new RegExp('\\(.*?\\)+|\\[.*?\\]+|\\S+', 'g');
358 var optionalUsage = this._formatActionsUsage(optionals, groups);
359 var positionalUsage = this._formatActionsUsage(positionals, groups);
362 var optionalParts = optionalUsage.match(regexpPart);
363 var positionalParts = positionalUsage.match(regexpPart) || [];
365 if (optionalParts.join(' ') !== optionalUsage) {
366 throw new Error('assert "optionalParts.join(\' \') === optionalUsage"');
368 if (positionalParts.join(' ') !== positionalUsage) {
369 throw new Error('assert "positionalParts.join(\' \') === positionalUsage"');
372 // helper for wrapping lines
373 /*eslint-disable func-style*/ // node 0.10 compat
374 var _getLines = function (parts, indent, prefix) {
378 var lineLength = prefix ? prefix.length - 1 : indent.length - 1;
380 parts.forEach(function (part) {
381 if (lineLength + 1 + part.length > textWidth) {
382 lines.push(indent + line.join(' '));
384 lineLength = indent.length - 1;
387 lineLength += part.length + 1;
391 lines.push(indent + line.join(' '));
394 lines[0] = lines[0].substr(indent.length);
399 var lines, indent, parts;
400 // if prog is short, follow it with optionals or positionals
401 if (prefix.length + prog.length <= 0.75 * textWidth) {
402 indent = $$.repeat(' ', (prefix.length + prog.length + 1));
405 _getLines([ prog ].concat(optionalParts), indent, prefix),
406 _getLines(positionalParts, indent)
408 } else if (positionalParts) {
409 lines = _getLines([ prog ].concat(positionalParts), indent, prefix);
414 // if prog is long, put it on its own line
416 indent = $$.repeat(' ', prefix.length);
417 parts = optionalParts + positionalParts;
418 lines = _getLines(parts, indent);
419 if (lines.length > 1) {
421 _getLines(optionalParts, indent),
422 _getLines(positionalParts, indent)
425 lines = [ prog ] + lines;
427 // join lines into usage
428 usage = lines.join(c.EOL);
432 // prefix with 'usage:'
433 return prefix + usage + c.EOL + c.EOL;
436 HelpFormatter.prototype._formatActionsUsage = function (actions, groups) {
437 // find group indices and identify actions in groups
438 var groupActions = [];
442 groups.forEach(function (group) {
446 var start = actions.indexOf(group._groupActions[0]);
448 end = start + group._groupActions.length;
450 //if (actions.slice(start, end) === group._groupActions) {
451 if ($$.arrayEqual(actions.slice(start, end), group._groupActions)) {
452 group._groupActions.forEach(function (action) {
453 groupActions.push(action);
456 if (!group.required) {
457 if (inserts[start]) {
458 inserts[start] += ' [';
460 inserts[start] = '[';
464 if (inserts[start]) {
465 inserts[start] += ' (';
467 inserts[start] = '(';
471 for (i = start + 1; i < end; i += 1) {
478 // collect all actions format strings
481 actions.forEach(function (action, actionIndex) {
487 // suppressed arguments are marked with None
488 // remove | separators for suppressed arguments
489 if (action.help === c.SUPPRESS) {
491 if (inserts[actionIndex] === '|') {
492 inserts.splice(actionIndex, actionIndex);
493 } else if (inserts[actionIndex + 1] === '|') {
494 inserts.splice(actionIndex + 1, actionIndex + 1);
497 // produce all arg strings
498 } else if (!action.isOptional()) {
499 part = self._formatArgs(action, action.dest);
501 // if it's in a group, strip the outer []
502 if (groupActions.indexOf(action) >= 0) {
503 if (part[0] === '[' && part[part.length - 1] === ']') {
504 part = part.slice(1, -1);
507 // add the action string to the list
510 // produce the first way to invoke the option in brackets
512 optionString = action.optionStrings[0];
514 // if the Optional doesn't take a value, format is: -s or --long
515 if (action.nargs === 0) {
516 part = '' + optionString;
518 // if the Optional takes a value, format is: -s ARGS or --long ARGS
520 argsDefault = action.dest.toUpperCase();
521 argsString = self._formatArgs(action, argsDefault);
522 part = optionString + ' ' + argsString;
524 // make it look optional if it's not required or in a group
525 if (!action.required && groupActions.indexOf(action) < 0) {
526 part = '[' + part + ']';
528 // add the action string to the list
533 // insert things at the necessary indices
534 for (var i = inserts.length - 1; i >= 0; --i) {
535 if (inserts[i] !== null) {
536 parts.splice(i, 0, inserts[i]);
540 // join all the action items with spaces
541 var text = parts.filter(function (part) {
545 // clean up separators for mutually exclusive groups
546 text = text.replace(/([\[(]) /g, '$1'); // remove spaces
547 text = text.replace(/ ([\])])/g, '$1');
548 text = text.replace(/\[ *\]/g, ''); // remove empty groups
549 text = text.replace(/\( *\)/g, '');
550 text = text.replace(/\(([^|]*)\)/g, '$1'); // remove () from single action groups
558 HelpFormatter.prototype._formatText = function (text) {
559 text = sprintf(text, { prog: this._prog });
560 var textWidth = this._width - this._currentIndent;
561 var indentIncriment = $$.repeat(' ', this._currentIndent);
562 return this._fillText(text, textWidth, indentIncriment) + c.EOL + c.EOL;
565 HelpFormatter.prototype._formatAction = function (action) {
573 // determine the required width and the entry label
574 var helpPosition = Math.min(this._actionMaxLength + 2, this._maxHelpPosition);
575 var helpWidth = this._width - helpPosition;
576 var actionWidth = helpPosition - this._currentIndent - 2;
577 var actionHeader = this._formatActionInvocation(action);
579 // no help; start on same line and add a final newline
581 actionHeader = $$.repeat(' ', this._currentIndent) + actionHeader + c.EOL;
583 // short action name; start on the same line and pad two spaces
584 } else if (actionHeader.length <= actionWidth) {
585 actionHeader = $$.repeat(' ', this._currentIndent) +
588 $$.repeat(' ', actionWidth - actionHeader.length);
591 // long action name; start on the next line
593 actionHeader = $$.repeat(' ', this._currentIndent) + actionHeader + c.EOL;
594 indentFirst = helpPosition;
597 // collect the pieces of the action help
598 parts = [ actionHeader ];
600 // if there was help for the action, add lines of help text
602 helpText = this._expandHelp(action);
603 helpLines = this._splitLines(helpText, helpWidth);
604 parts.push($$.repeat(' ', indentFirst) + helpLines[0] + c.EOL);
605 helpLines.slice(1).forEach(function (line) {
606 parts.push($$.repeat(' ', helpPosition) + line + c.EOL);
609 // or add a newline if the description doesn't end with one
610 } else if (actionHeader.charAt(actionHeader.length - 1) !== c.EOL) {
613 // if there are any sub-actions, add their help as well
614 if (action._getSubactions) {
616 action._getSubactions().forEach(function (subaction) {
617 parts.push(self._formatAction(subaction));
621 // return a single string
622 return this._joinParts(parts);
625 HelpFormatter.prototype._formatActionInvocation = function (action) {
626 if (!action.isOptional()) {
627 var format_func = this._metavarFormatter(action, action.dest);
628 var metavars = format_func(1);
636 // if the Optional doesn't take a value, format is: -s, --long
637 if (action.nargs === 0) {
638 parts = parts.concat(action.optionStrings);
640 // if the Optional takes a value, format is: -s ARGS, --long ARGS
642 argsDefault = action.dest.toUpperCase();
643 argsString = this._formatArgs(action, argsDefault);
644 action.optionStrings.forEach(function (optionString) {
645 parts.push(optionString + ' ' + argsString);
648 return parts.join(', ');
651 HelpFormatter.prototype._metavarFormatter = function (action, metavarDefault) {
654 if (action.metavar || action.metavar === '') {
655 result = action.metavar;
656 } else if (action.choices) {
657 var choices = action.choices;
659 if (typeof choices === 'string') {
660 choices = choices.split('').join(', ');
661 } else if (Array.isArray(choices)) {
662 choices = choices.join(',');
664 choices = Object.keys(choices).join(',');
666 result = '{' + choices + '}';
668 result = metavarDefault;
671 return function (size) {
672 if (Array.isArray(result)) {
677 for (var i = 0; i < size; i += 1) {
678 metavars.push(result);
684 HelpFormatter.prototype._formatArgs = function (action, metavarDefault) {
688 var buildMetavar = this._metavarFormatter(action, metavarDefault);
690 switch (action.nargs) {
691 /*eslint-disable no-undefined*/
694 metavars = buildMetavar(1);
695 result = '' + metavars[0];
698 metavars = buildMetavar(1);
699 result = '[' + metavars[0] + ']';
702 metavars = buildMetavar(2);
703 result = '[' + metavars[0] + ' [' + metavars[1] + ' ...]]';
706 metavars = buildMetavar(2);
707 result = '' + metavars[0] + ' [' + metavars[1] + ' ...]';
713 metavars = buildMetavar(1);
714 result = metavars[0] + ' ...';
717 metavars = buildMetavar(action.nargs);
718 result = metavars.join(' ');
723 HelpFormatter.prototype._expandHelp = function (action) {
724 var params = { prog: this._prog };
726 Object.keys(action).forEach(function (actionProperty) {
727 var actionValue = action[actionProperty];
729 if (actionValue !== c.SUPPRESS) {
730 params[actionProperty] = actionValue;
734 if (params.choices) {
735 if (typeof params.choices === 'string') {
736 params.choices = params.choices.split('').join(', ');
737 } else if (Array.isArray(params.choices)) {
738 params.choices = params.choices.join(', ');
740 params.choices = Object.keys(params.choices).join(', ');
744 return sprintf(this._getHelpString(action), params);
747 HelpFormatter.prototype._splitLines = function (text, width) {
749 var delimiters = [ ' ', '.', ',', '!', '?' ];
750 var re = new RegExp('[' + delimiters.join('') + '][^' + delimiters.join('') + ']*$');
752 text = text.replace(/[\n\|\t]/g, ' ');
755 text = text.replace(this._whitespaceMatcher, ' ');
757 // Wraps the single paragraph in text (a string) so every line
758 // is at most width characters long.
759 text.split(c.EOL).forEach(function (line) {
760 if (width >= line.length) {
767 var delimiterIndex = 0;
768 while (wrapEnd <= line.length) {
769 if (wrapEnd !== line.length && delimiters.indexOf(line[wrapEnd] < -1)) {
770 delimiterIndex = (re.exec(line.substring(wrapStart, wrapEnd)) || {}).index;
771 wrapEnd = wrapStart + delimiterIndex + 1;
773 lines.push(line.substring(wrapStart, wrapEnd));
777 if (wrapStart < line.length) {
778 lines.push(line.substring(wrapStart, wrapEnd));
785 HelpFormatter.prototype._fillText = function (text, width, indent) {
786 var lines = this._splitLines(text, width);
787 lines = lines.map(function (line) {
788 return indent + line;
790 return lines.join(c.EOL);
793 HelpFormatter.prototype._getHelpString = function (action) {