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 155 matching lines @@
  *     $ 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");
  *     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"
  *     print(results.command['a']); // true
  *
  * ## 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
@@ skipping 53 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;
 }