Ignore unhandled arguments instead of stopping parsing.

pkg/args/lib/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 59 matching lines @@
  * by calling [ArgParser.parse()] with a set of arguments:
  *
  *     var results = parser.parse(['some', 'command', 'line', 'args']);
  *
  * These will usually come from `new Options().arguments`, but you can pass in
  * any list of strings. It returns an instance of [ArgResults]. This is a
  * map-like object that will return the value of any parsed option.
  *
  *     var parser = new ArgParser();
  *     parser.addOption('mode');
- *     parser.addFlag('verbose', defaultsTo: true);
- *     var results = parser.parse('['--mode', 'debug', 'something', 'else']);
+ *     parser.addFlag('verbose', abbr: 'v');
+ *     var results = parser.parse('['--mode', 'debug', 'skip', '-v', 'me']);
  *
  *     print(results['mode']); // debug
  *     print(results['verbose']); // true
  *
- * The [parse()] method will stop as soon as it reaches `--` or anything that
- * it doesn't recognize as an option, flag, or option value. If there are still
- * arguments left, they will be provided to you in
+ * The [parse()] method will ignore any arguments it doesn't recognize and stop
+ * if it reaches `--`. Any unhandled arguments will be provided to you in
  * [ArgResults.rest].
  *
- *     print(results.rest); // ['something', 'else']
+ *     print(results.rest); // ['skip', 'me']
  *
  * ## Specifying options ##
  *
  * To actually pass in options and flags on the command line, use GNU or POSIX
  * style. If you define an option like:
  *
  *     parser.addOption('name', abbr: 'n');
  *
  * Then a value for it can be specified on the command line using any of:
  *
@@ skipping 70 matching lines @@
  * Will display something like:
  *
  *     --mode            The compiler configuration
  *                       [debug, release]
  *
  *     --[no-]verbose    Show additional diagnostic info
  *     --arch            The architecture to compile for
  *
  *           [arm]       ARM Holding 32-bit chip
  *           [ia32]      Intel x86
- * 
+ *
  * To assist the formatting of the usage help, single line help text will
  * be followed by a single new line. Options with multi-line help text
  * will be followed by two new lines. This provides spatial diversity between
  * options.
  *
  * [posix]: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_02
  * [gnu]: http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces
  */
 library args;
 
 import 'dart:math';
 
-// TODO(rnystrom): Use "package:" URL here when test.dart can handle pub.
 import 'src/utils.dart';
 
 /**
  * A class for taking a list of raw command line arguments and parsing out
  * options and flags from them.
  */
 class ArgParser {
   static final _SOLO_OPT = new RegExp(r'^-([a-zA-Z0-9])$');
   static final _ABBR_OPT = new RegExp(r'^-([a-zA-Z0-9]+)(.*)$');
   static final _LONG_OPT = new RegExp(r'^--([a-zA-Z\-_0-9]+)(=(.*))?$');
@@ skipping 73 matching lines @@
   }
 
   /**
    * 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 = {};
+    var rest = [];
 
     // Initialize flags to their defaults.
     _options.forEach((name, option) {
       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;
+      // If we got here, the argument doesn't look like an option, so ignore it.
+      rest.add(arg);
     }
 
     // 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));
+    rest.addAll(_args.getRange(_current, _args.length - _current));
+
+    return new ArgResults(results, rest);
   }
 
   /**
    * Generates a string displaying usage information for the defined options.
    * This is basically the help text shown on the command line.
    */
   String getUsage() {
     return new _Usage(this).generate();
   }
 
@@ skipping 432 matching lines @@
       allowedBuffer.add(allowed);
       if (allowed == option.defaultValue) {
         allowedBuffer.add(' (default)');
       }
       first = false;
     }
     allowedBuffer.add(']');
     return allowedBuffer.toString();
   }
 }