Add command support to args.

pkg/args/lib/src/usage.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library args.src.usage;
+
+import 'dart:math';
+
+import '../args.dart';
+
+/**
+ * Takes an [ArgParser] and generates a string of usage (i.e. help) text for its
+ * defined options. Internally, it works like a tabular printer. The output is
+ * divided into three horizontal columns, like so:
+ *
+ *     -h, --help  Prints the usage information
+ *     |  |        |                                 |
+ *
+ * It builds the usage text up one column at a time and handles padding with
+ * spaces and wrapping to the next line to keep the cells correctly lined up.
+ */
+class Usage {
+  static const NUM_COLUMNS = 3; // Abbreviation, long name, help.
+
+  /** The parser this is generating usage for. */
+  final ArgParser args;
+
+  /** The working buffer for the generated usage text. */
+  StringBuffer buffer;
+
+  /**
+   * The column that the "cursor" is currently on. If the next call to
+   * [write()] is not for this column, it will correctly handle advancing to
+   * the next column (and possibly the next row).
+   */
+  int currentColumn = 0;
+
+  /** The width in characters of each column. */
+  List<int> columnWidths;
+
+  /**
+   * The number of sequential lines of text that have been written to the last
+   * column (which shows help info). We track this so that help text that spans
+   * multiple lines can be padded with a blank line after it for separation.
+   * Meanwhile, sequential options with single-line help will be compacted next
+   * to each other.
+   */
+  int numHelpLines = 0;
+
+  /**
+   * How many newlines need to be rendered before the next bit of text can be
+   * written. We do this lazily so that the last bit of usage doesn't have
+   * dangling newlines. We only write newlines right *before* we write some
+   * real content.
+   */
+  int newlinesNeeded = 0;
+
+  Usage(this.args);
+
+  /**
+   * Generates a string displaying usage information for the defined options.
+   * This is basically the help text shown on the command line.
+   */
+  String generate() {
+    buffer = new StringBuffer();
+
+    calculateColumnWidths();
+
+    args.options.forEach((name, option) {
+      write(0, getAbbreviation(option));
+      write(1, getLongOption(option));
+
+      if (option.help != null) write(2, option.help);
+
+      if (option.allowedHelp != null) {
+        var allowedNames = option.allowedHelp.keys.toList();
+        allowedNames.sort();
+        newline();
+        for (var name in allowedNames) {
+          write(1, getAllowedTitle(name));
+          write(2, option.allowedHelp[name]);
+        }
+        newline();
+      } else if (option.allowed != null) {
+        write(2, buildAllowedList(option));
+      } else if (option.defaultValue != null) {
+        if (option.isFlag && option.defaultValue == true) {
+          write(2, '(defaults to on)');
+        } else if (!option.isFlag) {
+          write(2, '(defaults to "${option.defaultValue}")');
+        }
+      }
+
+      // If any given option displays more than one line of text on the right
+      // column (i.e. help, default value, allowed options, etc.) then put a
+      // blank line after it. This gives space where it's useful while still
+      // keeping simple one-line options clumped together.
+      if (numHelpLines > 1) newline();
+    });
+
+    return buffer.toString();
+  }
+
+  String getAbbreviation(Option option) {
+    if (option.abbreviation != null) {
+      return '-${option.abbreviation}, ';
+    } else {
+      return '';
+    }
+  }
+
+  String getLongOption(Option option) {
+    if (option.negatable) {
+      return '--[no-]${option.name}';
+    } else {
+      return '--${option.name}';
+    }
+  }
+
+  String getAllowedTitle(String allowed) {
+    return '      [$allowed]';
+  }
+
+  void calculateColumnWidths() {
+    int abbr = 0;
+    int title = 0;
+    args.options.forEach((name, option) {
+      // Make room in the first column if there are abbreviations.
+      abbr = max(abbr, getAbbreviation(option).length);
+
+      // Make room for the option.
+      title = max(title, getLongOption(option).length);
+
+      // Make room for the allowed help.
+      if (option.allowedHelp != null) {
+        for (var allowed in option.allowedHelp.keys) {
+          title = max(title, getAllowedTitle(allowed).length);
+        }
+      }
+    });
+
+    // Leave a gutter between the columns.
+    title += 4;
+    columnWidths = [abbr, title];
+  }
+
+  newline() {
+    newlinesNeeded++;
+    currentColumn = 0;
+    numHelpLines = 0;
+  }
+
+  write(int column, String text) {
+    var lines = text.split('\n');
+
+    // Strip leading and trailing empty lines.
+    while (lines.length > 0 && lines[0].trim() == '') {
+      lines.removeRange(0, 1);
+    }
+
+    while (lines.length > 0 && lines[lines.length - 1].trim() == '') {
+      lines.removeLast();
+    }
+
+    for (var line in lines) {
+      writeLine(column, line);
+    }
+  }
+
+  writeLine(int column, String text) {
+    // Write any pending newlines.
+    while (newlinesNeeded > 0) {
+      buffer.add('\n');
+      newlinesNeeded--;
+    }
+
+    // Advance until we are at the right column (which may mean wrapping around
+    // to the next line.
+    while (currentColumn != column) {
+      if (currentColumn < NUM_COLUMNS - 1) {
+        buffer.add(padRight('', columnWidths[currentColumn]));
+      } else {
+        buffer.add('\n');
+      }
+      currentColumn = (currentColumn + 1) % NUM_COLUMNS;
+    }
+
+    if (column < columnWidths.length) {
+      // Fixed-size column, so pad it.
+      buffer.add(padRight(text, columnWidths[column]));
+    } else {
+      // The last column, so just write it.
+      buffer.add(text);
+    }
+
+    // Advance to the next column.
+    currentColumn = (currentColumn + 1) % NUM_COLUMNS;
+
+    // If we reached the last column, we need to wrap to the next line.
+    if (column == NUM_COLUMNS - 1) newlinesNeeded++;
+
+    // Keep track of how many consecutive lines we've written in the last
+    // column.
+    if (column == NUM_COLUMNS - 1) {
+      numHelpLines++;
+    } else {
+      numHelpLines = 0;
+    }
+  }
+
+  buildAllowedList(Option option) {
+    var allowedBuffer = new StringBuffer();
+    allowedBuffer.add('[');
+    bool first = true;
+    for (var allowed in option.allowed) {
+      if (!first) allowedBuffer.add(', ');
+      allowedBuffer.add(allowed);
+      if (allowed == option.defaultValue) {
+        allowedBuffer.add(' (default)');
+      }
+      first = false;
+    }
+    allowedBuffer.add(']');
+    return allowedBuffer.toString();
+  }
+}
+
+/** Pads [source] to [length] by adding spaces at the end. */
+String padRight(String source, int length) {
+  final result = new StringBuffer();
+  result.add(source);
+
+  while (result.length < length) {
+    result.add(' ');
+  }
+
+  return result.toString();
+}