Add support for separators.

lib/src/arg_parser.dart

Index: lib/src/arg_parser.dart
diff --git a/lib/src/arg_parser.dart b/lib/src/arg_parser.dart
index 49d6aa6bbf6dc4d7a965536049fd8c305e87006e..8728a2910dcfcb3484d10465412ea5ec2e4e3745 100644
--- a/lib/src/arg_parser.dart
+++ b/lib/src/arg_parser.dart
@@ -16,10 +16,15 @@ import 'usage.dart';
 class ArgParser {
   final Map<String, Option> _options;
   final Map<String, ArgParser> _commands;
+  final List _optionsAndSeparators;
 
   /// The options that have been defined for this parser.
   final Map<String, Option> options;
 
+  /// A list of the [Option]s in [options] intermingled with [String]
+  /// separators.
+  final List optionsAndSeparators;

[Bob Nystrom, 2015/05/21 16:43:16]

This is kind of gross.

It might be time to consider creating a real class hierarchy for Option:

class Option {}
class SingleOption extends Option {}
class MultipleOption extends Option {}
class Flag extends Option {}
class Separator extends Option {}

Then call this orderedOptions, or just not expose it publicly at all.

[nweiz, 2015/05/21 19:22:27]

I thought about that, but Separators are really not options, both in the sense
of semantics and of utility. Almost anything people do with options wouldn't
make sense with separators. If we put separators in [options], every use of it
in ArgParser and Parser (or in users' external code) would have to add an
exception to ignore separators. That seems like a way bigger hassle than
dynamically typing this field.

[Bob Nystrom, 2015/05/21 19:42:27]

True. It might be possible to come up with a name that represents the union of
options and separators, like "section" or something. <shrug>
Oh, true. I wasn't thinking of actually putting the separators in the options
map.

How about just making optionalsAndSeparators private? It's really the name
that's most egregious.

[nweiz, 2015/05/21 19:52:37]

Done.

+
   /// The commands that have been defined for this parser.
   final Map<String, ArgParser> commands;
 
@@ -34,15 +39,17 @@ class ArgParser {
   /// This allows options to be specified after regular arguments. Defaults to
   /// `false`.
   factory ArgParser({bool allowTrailingOptions}) => new ArgParser._(
-      <String, Option>{}, <String, ArgParser>{},
+      <String, Option>{}, <String, ArgParser>{}, [],
       allowTrailingOptions: allowTrailingOptions);
 
   ArgParser._(Map<String, Option> options, Map<String, ArgParser> commands,
-      {bool allowTrailingOptions})
+          List optionsAndSeparators, {bool allowTrailingOptions})
       : this._options = options,
         this.options = new UnmodifiableMapView(options),
         this._commands = commands,
         this.commands = new UnmodifiableMapView(commands),
+        this._optionsAndSeparators = optionsAndSeparators,
+        this.optionsAndSeparators = new UnmodifiableListView(optionsAndSeparators),

[Bob Nystrom, 2015/05/21 16:43:16]

Long line.

[nweiz, 2015/05/21 19:22:27]

Done.

         this.allowTrailingOptions = allowTrailingOptions != null
             ? allowTrailingOptions
             : false;
@@ -110,9 +117,21 @@ class ArgParser {
       }
     }
 
-    _options[name] = newOption(name, abbr, help, valueHelp, allowed,
+    var option = newOption(name, abbr, help, valueHelp, allowed,
         allowedHelp, defaultsTo, callback, type,
         negatable: negatable, splitCommas: splitCommas, hide: hide);
+    _options[name] = option;
+    _optionsAndSeparators.add(option);
+  }
+
+  /// Adds a separator line to the usage.
+  ///
+  /// The separator goes between the options that have added before this is
+  /// called and the options that are added after. This only the arg parser's
+  /// usage text, not its parsing. Separators can be used to group options
+  /// together visually.

[Bob Nystrom, 2015/05/21 16:43:16]

This paragraph is kind of choppy. How about just:

"In the usage text for the parser, this will appear between any options added
before this call and ones added after it."

[nweiz, 2015/05/21 19:22:27]

Done.

+  void addSeparator(String text) {
+    _optionsAndSeparators.add(text);
   }
 
   /// Parses [args], a list of command-line arguments, matches them against the