Added support for multi-valued options (options that can occur more than once).

lib/args/args.dart

 // Copyright (c) 2012, 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.
 
 /**
  * This library lets you define parsers for parsing raw command-line arguments
  * into a set of options and values using [GNU][] and [POSIX][] style options.
  *
  * ## Defining options ##
  *
@@ skipping 105 matching lines @@
  * you define:
  *
  *     parser.addFlag('verbose', abbr: 'v');
  *     parser.addFlag('french', abbr: 'f');
  *     parser.addFlag('iambic-pentameter', abbr: 'i');
  *
  * Then all three flags could be set using:
  *
  *     -vfi
  *
+ * By default, an option has only a single value, with later option values
+ * overriding earlier ones; for example:
+ *
+ *     var parser = new ArgParser();
+ *     parser.addOption('mode');
+ *     var results = parser.parse(['--mode', 'on', '--mode', 'off']);
+ *     print(results['mode']); // prints 'off'
+ *
+ * If you need multiple values, set the [allowMultiple] flag. In that
+ * case the option can occur multiple times and when parsing arguments a
+ * List of values will be returned:
+ *
+ *     var parser = new ArgParser();
+ *     parser.addOption('mode', allowMultiple: true);
+ *     var results = parser.parse(['--mode', 'on', '--mode', 'off']);
+ *     print(results['mode']); // prints '[on, off]'
+ *
  * ## Usage ##
  *
  * This library can also be used to automatically generate nice usage help
  * text like you get when you run a program with `--help`. To use this, you
  * will also want to provide some help text when you create your options. To
  * define help text for the entire option, do:
  *
  *     parser.addOption('mode', help: 'The compiler configuration',
  *         allowed: ['debug', 'release']);
  *     parser.addFlag('verbose', help: 'Show additional diagnostic info');
@@ skipping 71 matching lines @@
   }
 
   /**
    * Defines a value-taking option. Throws an [IllegalArgumentException] if:
    *
    * * There is already an option with name [name].
    * * There is already an option using abbreviation [abbr].
    */
   void addOption(String name, [String abbr, String help, List<String> allowed,
       Map<String, String> allowedHelp, String defaultsTo,
-      void callback(bool value)]) {
+      void callback(bool value), bool allowMultiple = false]) {
     _addOption(name, abbr, help, allowed, allowedHelp, defaultsTo,
-        callback, isFlag: false);
+        callback, isFlag: false, allowMultiple: allowMultiple);
   }
 
   void _addOption(String name, String abbr, String help, List<String> allowed,
       Map<String, String> allowedHelp, defaultsTo,
-      void callback(bool value), [bool isFlag, bool negatable = false]) {
+      void callback(bool value), [bool isFlag, bool negatable = false,
+      bool allowMultiple = false]) {
     // Make sure the name isn't in use.
     if (_options.containsKey(name)) {
       throw new IllegalArgumentException('Duplicate option "$name".');
     }
 
     // Make sure the abbreviation isn't too long or in use.
     if (abbr != null) {
       if (abbr.length > 1) {
         throw new IllegalArgumentException(
             'Abbreviation "$abbr" is longer than one character.');
       }
 
       var existing = _findByAbbr(abbr);
       if (existing != null) {
         throw new IllegalArgumentException(
             'Abbreviation "$abbr" is already used by "${existing.name}".');
       }
     }
 
     _options[name] = new _Option(name, abbr, help, allowed, allowedHelp,
-        defaultsTo, callback, isFlag: isFlag, negatable: negatable);
+        defaultsTo, callback, isFlag: isFlag, negatable: negatable,
+        allowMultiple: allowMultiple);
     _optionNames.add(name);
   }
 
   /**
    * 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) {
     _args = args;
     _current = 0;
     var results = {};
 
     // Initialize flags to their defaults.
     _options.forEach((name, option) {
-      results[name] = option.defaultValue;
+      if (option.allowMultiple) {
+        results[name] = [];
+      } else {
+        results[name] = option.defaultValue;
+      }
     });
 
     // Parse the args.
     for (_current = 0; _current < args.length; _current++) {
       var arg = args[_current];
 
       if (arg == '--') {
         // Reached the argument terminator, so stop here.
         _current++;
         break;
       }
 
       // Try to parse the current argument as an option. Note that the order
       // here matters.
       if (_parseSoloOption(results)) continue;
       if (_parseAbbreviation(results)) continue;
       if (_parseLongOption(results)) continue;
 
       // If we got here, the argument doesn't look like an option, so stop.
       break;
     }
 
-    // Invoke the callbacks.
+    // Set unspecified multivalued arguments to their default value,
+    // if any, and invoke the callbacks.
     for (var name in _optionNames) {
       var option = _options[name];
+      if (option.allowMultiple &&
+          results[name].length == 0 && 
+          option.defaultValue != null) {
+        results[name].add(option.defaultValue);
+      }
       if (option.callback != null) option.callback(results[name]);
     }
 
     // Add in the leftover arguments we didn't parse.
     return new ArgResults(results,
         _args.getRange(_current, _args.length - _current));
   }
 
   /**
    * Generates a string displaying usage information for the defined options.
@@ skipping 12 matching lines @@
   }
 
   /** Validates and stores [value] as the value for [option]. */
   _setOption(Map results, _Option option, value) {
     // See if it's one of the allowed values.
     if (option.allowed != null) {
       _validate(option.allowed.some((allow) => allow == value),
           '"$value" is not an allowed value for option "${option.name}".');
     }
 
-    results[option.name] = value;
+    if (option.allowMultiple) {
+      results[option.name].add(value);
+    } else {
+      results[option.name] = value;
+    }
   }
 
   /**
    * Pulls the value for [option] from the next argument in [_args] (where the
    * current option is at index [_current]. Validates that there is a valid
    * value there.
    */
   void _readNextArgAsValue(Map results, _Option option) {
     _current++;
     // Take the option argument from the next command line arg.
@@ skipping 161 matching lines @@
 class _Option {
   final String name;
   final String abbreviation;
   final List allowed;
   final defaultValue;
   final Function callback;
   final String help;
   final Map<String, String> allowedHelp;
   final bool isFlag;
   final bool negatable;
+  final bool allowMultiple;
 
   _Option(this.name, this.abbreviation, this.help, this.allowed,
       this.allowedHelp, this.defaultValue, this.callback, [this.isFlag,
-      this.negatable]);
+      this.negatable, this.allowMultiple = false]);
 }
 
 /**
  * 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
  *     |  |        |                                 |
  *
@@ skipping 201 matching lines @@
       allowedBuffer.add(allowed);
       if (allowed == option.defaultValue) {
         allowedBuffer.add(' (default)');
       }
       first = false;
     }
     allowedBuffer.add(']');
     return allowedBuffer.toString();
   }
 }