Add support for separators.

lib/src/arg_parser.dart

 // Copyright (c) 2014, 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.arg_parser;
 
 import 'dart:collection';
 
 import 'arg_results.dart';
 import 'option.dart';
 import 'parser.dart';
 import 'usage.dart';
 
 /// A class for taking a list of raw command line arguments and parsing out
 /// options and flags from them.
 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;
 
   /// Whether or not this parser parses options that appear after non-option
   /// arguments.
   final bool allowTrailingOptions;
 
   /// Creates a new ArgParser.
   ///
   /// If [allowTrailingOptions] is set, the parser will continue parsing even
   /// after it finds an argument that is neither an option nor a command.
   /// 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;
 
   /// Defines a command.
   ///
   /// A command is a named argument which may in turn define its own options and
   /// subcommands using the given parser. If [parser] is omitted, implicitly
   /// creates a new one. Returns the parser for the command.
   ArgParser addCommand(String name, [ArgParser parser]) {
@@ skipping 47 matching lines @@
 
     // Make sure the abbreviation isn't too long or in use.
     if (abbr != null) {
       var existing = findByAbbreviation(abbr);
       if (existing != null) {
         throw new ArgumentError(
             'Abbreviation "$abbr" is already used by "${existing.name}".');
       }
     }
 
-    _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
   /// flags and options defined by this parser, and returns the result.
   ArgResults parse(List<String> args) =>
       new Parser(null, this, args.toList(), null, null).parse();
 
   /// Generates a string displaying usage information for the defined options.
   ///
   /// This is basically the help text shown on the command line.
@@ skipping 14 matching lines @@
     return options[option].defaultValue;
   }
 
   /// Finds the option whose abbreviation is [abbr], or `null` if no option has
   /// that abbreviation.
   Option findByAbbreviation(String abbr) {
     return options.values.firstWhere((option) => option.abbreviation == abbr,
         orElse: () => null);
   }
 }