Fix seaneagan#40

Author: seaneagan

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## Unreleased
 
   - Add `name` parameter to `Option` and `Flag` ( #102 )
+  - Add option groups ( #40 )
 
 ## 0.6.1
 

README.md

@@ -27,6 +27,7 @@ main(arguments) => new Script(greet).execute(arguments);
 greet(
     @Rest(help: 'Name(s) to greet.')
     List<String> who, {
+      @Group.start('Output');
       @Option(help: 'How many !\'s to append.')
       int enthusiasm : 0,
       @Flag(abbr: 'l', help: 'Put names on separate lines.')
@@ -61,28 +62,36 @@ $ greet.dart --help
 
 Description:
 
-  Print a configurable greeting
+  Print a configurable greeting.
 
 Usage:
 
-  greet.dart [options] [WHO]...
+  greet.dart [options] [<who>...]
+
+    <who>    Name(s) to greet.
 
 Options:
 
-      --salutation=<greeting>    Alternate <greeting> to greet with e.g. "Hi".
-      --enthusiasm               How many !'s to append.
-  -l, --line-mode                Put names on separate lines.
-      --completion               Tab completion for this command.
+      --completion         Tab completion for this command.
+
+            [install]      Install completion script to .bashrc/.zshrc.
+            [print]        Print completion script to stdout.
+            [uninstall]    Uninstall completion script from .bashrc/.zshrc.
+
+  -h, --help               Print this usage information.
+
+  Output:
 
-            [install]            Install completion script to .bashrc/.zshrc.
-            [print]              Print completion script to stdout.
-            [uninstall]          Uninstall completion script from .bashrc/.zshrc.
+      --enthusiasm         How many !'s to append.
+                           (defaults to "0")
 
-  -h, --help                     Print this usage information.
+  -l, --line-mode          Put names on separate lines.
+      --greeting           Alternate word to greet with e.g. "Hi".
+                           (defaults to "Hello")
 
 Examples:
 
-  greet.dart --salutation Hi --enthusiasm 3 Bob # enthusiastic
+  greet.dart --greeting Hi --enthusiasm 3 Bob # enthusiastic
 
 ```
 

example/greet.dart

@@ -6,10 +6,11 @@ main(arguments) => new Script(greet).execute(arguments);
 
 // All metadata annotations are optional.
 @Command(help: 'Print a configurable greeting.', plugins: const [const Completion()])
-@ArgExample('--salutation Hi --enthusiasm 3 Bob', help: 'enthusiastic')
+@ArgExample('--greeting Hi --enthusiasm 3 Bob', help: 'enthusiastic')
 greet(
     @Rest(valueHelp: 'who', help: 'Name(s) to greet.')
     List<String> who, {
+      @Group.start(title: 'Output')
       @Option(help: 'How many !\'s to append.')
       int enthusiasm : 0,
       @Flag(abbr: 'l', help: 'Put names on separate lines.')

lib/src/annotations.dart

@@ -128,3 +128,33 @@ class SubCommand extends BaseCommand {
   const SubCommand({help, bool allowTrailingOptions, this.hide})
       : super(help: help, allowTrailingOptions: allowTrailingOptions);
 }
+
+/// An annotation which defines a group of options.
+///
+/// The group of options will be separated from other options in help text,
+/// and may have a [title] and [help] as well.
+///
+/// See [new Group] and [new Group.start] for different ways to define groups.
+abstract class Group implements HelpAnnotation {
+
+  /// The title to display above the [help] for this group.
+  String get title;
+
+  /// Whether to hide this group.
+  bool get hide;
+
+  /// Marks a `Map<String, dynamic>` [Option] parameter as receiving values for
+  /// multiple options as enumerated by [getOptions].
+  const factory Group(
+      Iterable<Option> getOptions(),
+      {String title,
+       help,
+       bool hide}) = CombinedGroup;
+
+  /// Use [Group.start] to mark a `Map<String, dynamic>` [Option] parameter as starting a group which
+  /// continues until the next [Group] parameter.
+  const factory Group.start(
+      {String title,
+      help,
+      bool hide}) = StartGroup;
+}

lib/src/group_annotations.dart

@@ -0,0 +1,33 @@
+
+import '../unscripted.dart';
+import 'util.dart';
+
+class GroupMarker extends HelpAnnotation implements Group {
+
+  final String title;
+  final bool hide;
+
+  const GroupMarker({
+      this.title,
+      help,
+      this.hide})
+      : super(help: help);
+}
+
+class StartGroup extends GroupMarker {
+  const StartGroup({
+    String title,
+    help,
+    bool hide}) : super(title: title, help: help, hide: hide);
+}
+
+class CombinedGroup extends GroupMarker {
+  const CombinedGroup(
+    this.getOptions,
+    {String title,
+     help,
+     bool hide}) : super(title: title, help: help, hide: hide);
+
+  /// Whether to hide this group.
+  final Function getOptions;
+}

lib/src/plugins/help/option_help.dart

@@ -23,9 +23,11 @@ import 'util.dart';
  * spaces and wrapping to the next line to keep the cells correctly lined up.
  */
 class OptionHelp {
-  static const NUM_COLUMNS = 3; // Abbreviation, long name, help.
+  static const numColumns = 3; // Abbreviation, long name, help.
 
-  /** The parser this is generating usage for. */
+  static const gutterWidth = 4; // Width of gutter between columns.
+
+  /** The usage this is generating usage for. */
   final Usage usage;
 
   /** The working buffer for the generated usage text. */
@@ -41,7 +43,7 @@ class OptionHelp {
   /** The width in characters of each column. */
   List<int> columnWidths;
 
-  /** The width in characters of each column. */
+  /** The formatters of each column. */
   List<Function> columnFormatters = [abbrFormatter, optionPen, helpFormatter];
 
   static String abbrFormatter(String help) {
@@ -86,47 +88,65 @@ class OptionHelp {
 
     calculateColumnWidths();
 
-    usage.options.forEach((name, option) {
-      if (option.hide != null && option.hide) return;
+    usage.optionGroups.asMap().forEach((index, optionGroup) {
+      if (optionGroup.hide != null && optionGroup.hide) return;
+
+      var title = optionGroup.title != null
+          ? getGroupTitle(optionGroup.title)
+          : index == 0
+              ? null
+              : '_' * (columnWidths.fold(0, (prev, next) => prev + next) - gutterWidth);
+      if (title != null) {
+        if (buffer.isNotEmpty) buffer.write("\n");
+        write(0, title, format: titlePen);
+        newline();
+        newline();
+      }
 
-      write(0, getAbbreviation(option));
-      write(1, getLongOption(name, option));
+      optionGroup.options.forEach((name, option) {
+        if (option.hide != null && option.hide) return;
 
-      var help = getHelp(option.help);
-      if (help != null) {
-        write(2, help);
-      }
+        write(0, getAbbreviation(option));
+        write(1, getLongOption(name, option));
 
-      if (option.allowed is Map) {
-        var allowedValues = getAllowedValues(option).toList(growable: false);
-        allowedValues.sort();
-        newline();
-        for (var name in allowedValues) {
-          write(1, getAllowedTitle(name));
-          write(2, option.allowed[name]);
+        var help = getHelp(option.help);
+        if (help != null) {
+          write(2, help);
         }
-        newline();
-      } else if (getAllowedValues(option) != null) {
-        write(2, buildAllowedList(option));
-      } else if (option.defaultsTo != null) {
-        var defaultsTo = option is Flag && option.defaultsTo == true ?
-            'on' :
-            option is! Flag ? option.defaultsTo : null;
-        if(defaultsTo != null) {
-          write(2, '(defaults to "$defaultsTo")');
+
+        if (option.allowed is Map) {
+          var allowedValues = getAllowedValues(option).toList(growable: false);
+          allowedValues.sort();
+          newline();
+          for (var name in allowedValues) {
+            write(1, getAllowedTitle(name));
+            write(2, option.allowed[name]);
+          }
+          newline();
+        } else if (getAllowedValues(option) != null) {
+          write(2, buildAllowedList(option));
+        } else if (option.defaultsTo != null) {
+          var defaultsTo = option is Flag && option.defaultsTo == true ?
+              'on' :
+              option is! Flag ? option.defaultsTo : null;
+          if(defaultsTo != null) {
+            write(2, '(defaults to "$defaultsTo")');
+          }
         }
-      }
 
-      // 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();
+        // 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 getGroupTitle(String name) => '$name:';
+
   Iterable<String> getAllowedValues(Option option) {
     var allowed = option.allowed;
     if(allowed is Iterable) return allowed;
@@ -164,23 +184,30 @@ class OptionHelp {
   void calculateColumnWidths() {
     int abbr = 0;
     int title = 0;
-    usage.options.forEach((name, option) {
-      // Make room in the first column if there are abbreviations.
-      abbr = max(abbr, getAbbreviation(option).length);
+    usage.optionGroups.forEach((optionGroup) {
+      if (optionGroup.hide != null && optionGroup.hide) return;
+
+      // Make room for the group title.
+      title = max(title, getGroupTitle(optionGroup.title).length);
 
-      // Make room for the option.
-      title = max(title, getLongOption(name, option).length);
+      optionGroup.options.forEach((name, option) {
+        // Make room in the first column if there are abbreviations.
+        abbr = max(abbr, getAbbreviation(option).length);
 
-      // Make room for the allowed help.
-      if (option.allowed is Map) {
-        for (var allowed in option.allowed.keys) {
-          title = max(title, getAllowedTitle(allowed).length);
+        // Make room for the option.
+        title = max(title, getLongOption(name, option).length);
+
+        // Make room for the allowed help.
+        if (option.allowed is Map) {
+          for (var allowed in option.allowed.keys) {
+            title = max(title, getAllowedTitle(allowed).length);
+          }
         }
-      }
+      });
     });
 
     // Leave a gutter between the columns.
-    title += 4;
+    title += gutterWidth;
     columnWidths = [abbr, title];
   }
 
@@ -190,24 +217,24 @@ class OptionHelp {
     numHelpLines = 0;
   }
 
-  void write(int column, String text) {
+  void write(int column, String text, {format(String)}) {
     var lines = text.split('\n');
 
     // Strip leading and trailing empty lines.
-    while (lines.length > 0 && lines[0].trim() == '') {
-      lines.removeRange(0, 1);
+    while (lines.isNotEmpty && lines.first.trim() == '') {
+      lines.removeAt(0);
     }
 
-    while (lines.length > 0 && lines[lines.length - 1].trim() == '') {
+    while (lines.isNotEmpty && lines.last.trim() == '') {
       lines.removeLast();
     }
 
     for (var line in lines) {
-      writeLine(column, line);
+      writeLine(column, line, format: format);
     }
   }
 
-  void writeLine(int column, String text) {
+  void writeLine(int column, String text, {format(String)}) {
     // Write any pending newlines.
     while (newlinesNeeded > 0) {
       buffer.write('\n');
@@ -217,15 +244,17 @@ class OptionHelp {
     // 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) {
+      if (currentColumn < numColumns - 1) {
         buffer.write(' ' * columnWidths[currentColumn]);
       } else {
         buffer.write('\n');
       }
-      currentColumn = (currentColumn + 1) % NUM_COLUMNS;
+      currentColumn = (currentColumn + 1) % numColumns;
     }
 
-    var formatted = columnFormatters[column](text);
+    var formatter = format != null ? format : columnFormatters[column];
+
+    var formatted = formatter(text);
     buffer.write(formatted);
 
     if (column < columnWidths.length) {
@@ -234,14 +263,14 @@ class OptionHelp {
     }
 
     // Advance to the next column.
-    currentColumn = (currentColumn + 1) % NUM_COLUMNS;
+    currentColumn = (currentColumn + 1) % numColumns;
 
     // If we reached the last column, we need to wrap to the next line.
-    if (column == NUM_COLUMNS - 1) newlinesNeeded++;
+    if (column == numColumns - 1) newlinesNeeded++;
 
     // Keep track of how many consecutive lines we've written in the last
     // column.
-    if (column == NUM_COLUMNS - 1) {
+    if (column == numColumns - 1) {
       numHelpLines++;
     } else {
       numHelpLines = 0;