Allow passing in an existing ArgParser for a command.

pkg/args/lib/args.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.
 
 /**
  * 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.
  *
  * ## Installing ##
  *
@@ skipping 151 matching lines @@
  *
  * In addition to *options*, you can also define *commands*. A command is a
  * named argument that has its own set of options. For example, when you run:
  *
  *     $ git commit -a
  *
  * The executable is `git`, the command is `commit`, and the `-a` option is an
  * option passed to the command. You can add a command like so:
  *
  *     var parser = new ArgParser();
- *     var command = parser.addCommand("commit");
+ *     var command = parser.addCommand('commit');
+ *
+ * It returns another [ArgParser] which you can then use to define options
+ * specific to that command. If you already have an [ArgParser] for the
+ * command's options, you can pass it to [addCommand]:
+ *
+ *     var parser = new ArgParser();
+ *     var command = new ArgParser();
+ *     parser.addCommand('commit', command);
+ *
+ * The [ArgParser] for a command can then define whatever options or flags:
+ *
  *     command.addFlag('all', abbr: 'a');
  *
- * It returns another [ArgParser] which you can use to define options and
- * subcommands on that command. When an argument list is parsed, you can then
- * determine which command was entered and what options were provided for it.
+ * You can add multiple commands to the same parser so that a user can select
+ * one from a range of possible commands. When an argument list is parsed,
+ * you can then determine which command was entered and what options were
+ * provided for it.
  *
  *     var results = parser.parse(['commit', '-a']);
  *     print(results.command.name); // "commit"
  *     print(results.command['a']); // true
  *
+ * Options for a command must appear after the command in the argument list.
+ * For example, given the above parser, "git -a commit" is *not* valid. The
+ * parser will try to find the right-most command that accepts an option. For
+ * example:
+ *
+ *     var parser = new ArgParser();
+ *     parser.addFlag('all', abbr: 'a');
+ *     var command = new ArgParser().addCommand('commit');
+ *     parser.addFlag('all', abbr: 'a');
+ *     var results = parser.parse(['commit', '-a']);
+ *     print(results.command['a']); // true
+ *
+ * Here, both the top-level parser and the "commit" command can accept a "-a"
+ * (which is probably a bad command line interface, admittedly). In that case,
+ * when "-a" appears after "commit", it will be applied to that command. If it
+ * appears to the left of "commit", it will be given to the top-level parser.
+ *
  * ## Displaying 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 48 matching lines @@
 
   /**
    * The commands that have been defined for this parser.
    */
   final Map<String, ArgParser> commands = <String, ArgParser>{};
 
   /** Creates a new ArgParser. */
   ArgParser();
 
   /**
-   * Defines a command. A command is a named argument which may in turn
-   * define its own options and subcommands. Returns an [ArgParser] that can
-   * be used to define the command's options.
+   * 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 addCommand(String name, [ArgParser parser]) {
     // Make sure the name isn't in use.
     if (commands.containsKey(name)) {
       throw new ArgumentError('Duplicate command "$name".');
     }
 
-    var command = new ArgParser();
-    commands[name] = command;
-    return command;
+    if (parser == null) parser = new ArgParser();
+    commands[name] = parser;
+    return parser;
   }
 
   /**
    * Defines a flag. Throws an [ArgumentError] if:
    *
    * * There is already an option named [name].
    * * There is already an option using abbreviation [abbr].
    */
   void addFlag(String name, {String abbr, String help, bool defaultsTo: false,
       bool negatable: true, void callback(bool value)}) {
@@ skipping 154 matching lines @@
           'Could not find an option named "$name".');
     }
 
     return _options[name];
   }
 
   /** Get the names of the options as an [Iterable]. */
   Iterable<String> get options => _options.keys;
 }