Allow passing in an existing ArgParser for a command.

pkg/args/lib/args.dart

Index: pkg/args/lib/args.dart
diff --git a/pkg/args/lib/args.dart b/pkg/args/lib/args.dart
index be1a6efa4d819550aee0c9a8819d7c361ac5c2a3..182ec0a8be3fcd638f3d0446dded1c542db6923f 100644
--- a/pkg/args/lib/args.dart
+++ b/pkg/args/lib/args.dart
@@ -173,8 +173,16 @@
  *     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.
+ * subcommands on 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();
+ *     command.addFlag('all', abbr: 'a');
+ *     parser.addCommand("commit", command);
+ *
+ * When an argument list is parsed, you can then determine which command was
+ * entered and what options were provided for it.

[gram, 2013/05/21 23:11:07]

Can you elaborate more here? Can an argparser have more than one command? Can a
command line have more than one command? How are the arguments then split
between multiple commands? What if there is ambiguity?

It's cool that we have this feature but there is a lot left out in this
description.

[Bob Nystrom, 2013/05/21 23:20:15]

There's lots of tests for these cases, but little docs.
Added some more docs.

  *
  *     var results = parser.parse(['commit', '-a']);
  *     print(results.command.name); // "commit"
@@ -248,19 +256,21 @@ class 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;
   }
 
   /**