Added the continueParsing option to ArgParser.

pkg/args/lib/src/parser.dart

 // Copyright (c) 2013, 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.parser;
 
 import '../args.dart';
 
 final _SOLO_OPT = new RegExp(r'^-([a-zA-Z0-9])$');
 final _ABBR_OPT = new RegExp(r'^-([a-zA-Z0-9]+)(.*)$');
 final _LONG_OPT = new RegExp(r'^--([a-zA-Z\-_0-9]+)(=(.*))?$');
 
 /**
  * The actual parsing class. Unlike [ArgParser] which is really more an "arg
  * grammar", this is the class that does the parsing and holds the mutable
  * state required during a parse.
+ *
+ * If [parseAllOptions] 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 command parameters.
+ *
+ * [parseAllOptions] is false by default, so when a non-option, non-command
+ * argument is encountered, it and any remaining arguments are passed to the
+ * leafmost command.
+ *
+ * An argument that looks like an option, but does not match any option will
+ * throw a [FormatException], regardless of the value of [parseAllOptions].

[Bob Nystrom, 2013/06/20 00:33:36]

Redundant with ArgParser docs. Remove, I think.

[Andrei Mouravski, 2013/06/22 00:54:02]

Done.

  */
 class Parser {
   /**
    * If parser is parsing a command's options, this will be the name of the
    * command. For top-level results, this returns `null`.
    */
   final String commandName;
 
   /**
    * The parser for the supercommand of this command parser, or `null` if this
    * is the top-level parser.
    */
   final Parser parent;
 
+  /** If `true`, parser will continue after it sees a non-option argument. */
+  final bool parseAllOptions;
+
   /** The grammar being parsed. */
   final ArgParser grammar;
 
   /** The arguments being parsed. */
   final List<String> args;
 
+  /** The remaining non-option, non-command arguments. */
+  List<String> rest;
+
   /** The accumulated parsed options. */
   final Map results = {};
 
-  Parser(this.commandName, this.grammar, this.args, [this.parent]);
+  Parser(this.commandName, this.grammar, this.args,
+      [this.parseAllOptions = false, this.parent, rest])
+      : this.rest = rest == null ? [] : rest;

[Bob Nystrom, 2013/06/20 00:33:36]

How about having the field be:

final rest = <String>[];

and then in the constructor body, do if (rest != null) this.rest.addAll(rest);

That way the caller doesn't have to copy.

[Andrei Mouravski, 2013/06/22 00:54:02]

Done.

 
   /** The current argument being parsed. */
   String get current => args[0];
 
   /** Parses the arguments. This can only be called once. */
   ArgResults parse() {
     var commandResults = null;
 
     // Initialize flags to their defaults.
     grammar.options.forEach((name, option) {
       if (option.allowMultiple) {
         results[name] = [];
       } else {
         results[name] = option.defaultValue;
       }
     });
 
     // Parse the args.
     while (args.length > 0) {
       if (current == '--') {
         // Reached the argument terminator, so stop here.
         args.removeAt(0);
         break;
       }
 
       // Try to parse the current argument as a command. This happens before
       // options so that commands can have option-like names.
       var command = grammar.commands[current];
       if (command != null) {
+        validate(rest.isEmpty, 'Cannot specify arguments before a command.');
         var commandName = args.removeAt(0);
-        var commandParser = new Parser(commandName, command, args, this);
+        var commandParser = new Parser(commandName, command, args,
+            parseAllOptions, this, rest.toList());
         commandResults = commandParser.parse();
-        continue;
+
+        // All remaining arguments were passed to command so clear them here.
+        rest.clear();
+        break;
       }
 
       // Try to parse the current argument as an option. Note that the order
       // here matters.
-      if (parseSoloOption()) continue;
-      if (parseAbbreviation(this)) continue;
-      if (parseLongOption()) continue;
+      if (isCurrentArgAnOption) {
+        if (parseSoloOption()) continue;
+        if (parseAbbreviation(this)) continue;
+        if (parseLongOption()) continue;
+        throw new FormatException(
+            'Could not find an option or flag "${args[0]}".');

[Bob Nystrom, 2013/06/20 00:33:36]

Why is this throw needed? Shouldn't it have already thrown?

[Andrei Mouravski, 2013/06/22 00:54:02]

Because I'm more lenient inside the parse functions and this catches things that
look like options but aren't.

[Bob Nystrom, 2013/06/24 15:53:20]

*Why* are you being more lenient? Those functions should immediately throw if
they match their regex but can't find an appropriate option.
Why aren't those already caught like they were before?

[Andrei Mouravski, 2013/06/24 20:41:03]

Done.

+      }
 
-      // If we got here, the argument doesn't look like an option, so stop.
-      break;
+      // This argument is neither option nor command, so stop parsing unless
+      // the [parseAllOptions] option is set.
+      if (!parseAllOptions) break;
+      rest.add(args.removeAt(0));
     }
 
     // Set unspecified multivalued arguments to their default value,
     // if any, and invoke the callbacks.
     grammar.options.forEach((name, option) {
       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 to the innermost command.
-    var rest = args.toList();
+    rest.addAll(args.toList());
     args.clear();
     return new ArgResults(results, commandName, commandResults, rest);
   }
 
   /**
    * Pulls the value for [option] from the second argument in [args]. Validates
    * that there is a valid value there.
    */
   void readNextArgAsValue(Option option) {
     // Take the option argument from the next command line arg.
     validate(args.length > 0,
         'Missing argument for "${option.name}".');
 
     // Make sure it isn't an option itself.
     validate(!_ABBR_OPT.hasMatch(current) && !_LONG_OPT.hasMatch(current),
         'Missing argument for "${option.name}".');
 
     setOption(results, option, current);
     args.removeAt(0);
   }
 
+  /** Returns `true` if the current argument looks like an option. */
+  bool get isCurrentArgAnOption => [_SOLO_OPT, _ABBR_OPT, _LONG_OPT].any(
+      (re) => re.firstMatch(current) != null);
+
   /**
    * Tries to parse the current argument as a "solo" option, which is a single
    * hyphen followed by a single letter. We treat this differently than
    * collapsed abbreviations (like "-abc") to handle the possible value that
    * may follow it.
    */
   bool parseSoloOption() {
     var soloOpt = _SOLO_OPT.firstMatch(current);
     if (soloOpt == null) return false;
 
     var option = grammar.findByAbbreviation(soloOpt[1]);
     if (option == null) {
       // Walk up to the parent command if possible.
-      validate(parent != null,
+      return tryParseOnParent((p) => p.parseSoloOption(),
           'Could not find an option or flag "-${soloOpt[1]}".');
-      return parent.parseSoloOption();
     }
 
     args.removeAt(0);
 
     if (option.isFlag) {
       setOption(results, option, true);
     } else {
       readNextArgAsValue(option);
     }
 
     return true;
   }
 
   /**
    * Tries to parse the current argument as a series of collapsed abbreviations
    * (like "-abc") or a single abbreviation with the value directly attached
    * to it (like "-mrelease").
    */
   bool parseAbbreviation(Parser innermostCommand) {
     var abbrOpt = _ABBR_OPT.firstMatch(current);
     if (abbrOpt == null) return false;
 
     // If the first character is the abbreviation for a non-flag option, then
     // the rest is the value.
     var c = abbrOpt[1].substring(0, 1);
     var first = grammar.findByAbbreviation(c);
     if (first == null) {
       // Walk up to the parent command if possible.
-      validate(parent != null,
+      return tryParseOnParent((p) => p.parseAbbreviation(innermostCommand),
           'Could not find an option with short name "-$c".');
-      return parent.parseAbbreviation(innermostCommand);
     } else if (!first.isFlag) {
       // The first character is a non-flag option, so the rest must be the
       // value.
       var value = '${abbrOpt[1].substring(1)}${abbrOpt[2]}';
       setOption(results, first, value);
     } else {
       // If we got some non-flag characters, then it must be a value, but
       // if we got here, it's a flag, which is wrong.
       validate(abbrOpt[2] == '',
         'Option "-$c" is a flag and cannot handle value '
@@ skipping 10 matching lines @@
     }
 
     args.removeAt(0);
     return true;
   }
 
   void parseShortFlag(String c) {
     var option = grammar.findByAbbreviation(c);
     if (option == null) {
       // Walk up to the parent command if possible.
-      validate(parent != null,
+      tryParseOnParent((p) => p.parseShortFlag(c),
           'Could not find an option with short name "-$c".');
-      parent.parseShortFlag(c);
       return;
     }
 
     // In a list of short options, only the first can be a non-flag. If
     // we get here we've checked that already.
     validate(option.isFlag,
         'Option "-$c" must be a flag to be in a collapsed "-".');
 
     setOption(results, option, true);
   }
@@ skipping 21 matching lines @@
       } else {
         // Option like --foo, so look for the value as the next arg.
         readNextArgAsValue(option);
       }
     } else if (name.startsWith('no-')) {
       // See if it's a negated flag.
       name = name.substring('no-'.length);
       option = grammar.options[name];
       if (option == null) {
         // Walk up to the parent command if possible.
-        validate(parent != null, 'Could not find an option named "$name".');
-        return parent.parseLongOption();
+        return tryParseOnParent((p) => p.parseLongOption(),
+            'Could not find an option named "$name".');
       }
 
       args.removeAt(0);
       validate(option.isFlag, 'Cannot negate non-flag option "$name".');
       validate(option.negatable, 'Cannot negate option "$name".');
 
       setOption(results, option, false);
     } else {
       // Walk up to the parent command if possible.
-      validate(parent != null, 'Could not find an option named "$name".');
-      return parent.parseLongOption();
+      return tryParseOnParent((p) => p.parseLongOption(),
+          'Could not find an option named "$name".');
     }
 
     return true;
   }
 
   /**
    * Called during parsing to validate the arguments. Throws a
    * [FormatException] if [condition] is `false`.
    */
   validate(bool condition, String message) {
     if (!condition) throw new FormatException(message);
   }
 
+  /**
+   * Tries to run parseFunc recursively on this parser's parent parser.
+   *
+   * Returns `true` if the parse succeeded on any ancestor of this parser.
+   * Returns `false` if no [Parser] accepted the [parseFunc] and
+   * [parseAllOptions] is true.
+   * Throws a [FormatException] exception otherwise.

[Bob Nystrom, 2013/06/20 00:33:36]

This documents *what* it does, but not *why* it does that.

[Andrei Mouravski, 2013/06/22 00:54:02]

Done.

+   */
+  bool tryParseOnParent(bool parseFunc(Parser p), String message) {
+    if (parent != null) {
+      return parseFunc(parent);
+    } else if (parseAllOptions) {
+      return false;

[Bob Nystrom, 2013/06/20 00:33:36]

What's this case for? If we can't parse it, shouldn't it always fail? We only
get here if it's an option.

[Andrei Mouravski, 2013/06/22 00:54:02]

It's to fall through when parsing.

+    } else {
+      throw new FormatException(message);
+    }
+  }
+
   /** 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.any((allow) => allow == value),
           '"$value" is not an allowed value for option "${option.name}".');
     }
 
     if (option.allowMultiple) {
       results[option.name].add(value);
     } else {
       results[option.name] = value;
     }
   }
 }