Add a CommandRunner class for dispatching commands to args.

pkg/args/README.md

Index: pkg/args/README.md
diff --git a/pkg/args/README.md b/pkg/args/README.md
index 9baf1fb5f9f8a94e2841e6c973af3d50193d8f64..937791d09596a7d7fe5ec659683b057158151ec9 100644
--- a/pkg/args/README.md
+++ b/pkg/args/README.md
@@ -197,6 +197,63 @@ Here, both the top-level parser and the `"commit"` command can accept a `"-a"`
 `"-a"` appears after `"commit"`, it is applied to that command. If it appears to
 the left of `"commit"`, it is given to the top-level parser.
 
+## Dispatching Commands
+
+If you're writing a command-based application, you can use the [CommandRunner][]
+and [Command][] classes to help structure it. [CommandRunner][] has built-in
+support for dispatching to [Command][]s based on command-line arguments, as well
+as handling `--help` flags and invalid arguments. For example:
+
+    var runner = new CommandRunner("git", "Distributed version control.");
+    runner.addCommand(new CommitCommand());
+    runner.addCommand(new StashCommand());
+    runner.run(['commit', '-a']); // Calls [CommitCommand.run()]
+
+Custom commands are defined by extending the [Command][] class. For example:
+
+    class CommitCommand extends Command {
+      // The [name] and [description] fields must be set by every subclass.

[Bob Nystrom, 2014/12/11 20:25:30]

This is confusing. You aren't setting fields here, you're defining them. You
could make these settable fields in the base class, but I think making them
getters here is clearer.

[nweiz, 2014/12/11 23:55:24]

Changed "set" to "defined". I still find defining constant-valued getters to be
perverse.

[Bob Nystrom, 2014/12/12 18:13:22]

That still isn't correct. Subclasses don't have to define a field. They have to
define a getter, and a field is just one way to do that.
I still find defining constant-valued instance fields to be even more perverse.
:)

From the perspective of a caller, all it cares is that any instance of Command
responds to .name. It doesn't care if that's a getter whose body is a literal,
some calculation, or a field. From the caller's perspective, it's just an
argument-less member invocation.

If you have some class that implements that, and every instance of the class
returns the same value, then a getter that returns that value seems like the
natural way to express that to me. It makes it clear to the reader that all
instances of the class have the same behavior (since it's a getter) and that
they all return the same value (since the body is just a literal).

Fields are a property of each individual instance, but here, "my name is
'commit'" is true for all instances of the CommitCommand class. If you have some
concept that you want to share across all instances of a class, a member is the
natural way to express it.
 
It's also faster and uses less memory.

[nweiz, 2014/12/16 02:07:44]

Changed to "property" which matches dartdoc.
I'm tired of rehashing this argument over and over. I've stopped complaining
when you use a property style I don't like; will you do the same for me?

[Bob Nystrom, 2014/12/16 16:50:41]

Property is perfect, thanks. I just don't want users to be confused about how to
subclass this.
OK, fair enough. :)

+      final String name = "commit";
+      final String description = "Record changes to the repository.";
+
+      CommitCommand() {
+        // [argParser] is automatically created by the parent class.
+        argParser.addFlag('all', abbr: 'a');
+      }
+
+      void run() {

[Bob Nystrom, 2014/12/11 20:25:30]

It would be good to mention how asynchrony is handled.

[nweiz, 2014/12/11 23:55:24]

Done.

+        // [options] is set before [run()] is called and contains the options
+        // passed to this command.
+        print(options['all']);
+      }
+    }
+
+Commands can also have subcommands, which are added with [addSubcommand][]. A
+command with subcommands can't run its own code, so [run][] doesn't need to be

[Bob Nystrom, 2014/12/11 20:25:30]

Why can't parent commands also be run?

[nweiz, 2014/12/11 23:55:24]

Because the pub command runner didn't support it and it wasn't trivial to add.
In particular, it's tricky to detect the difference between a runnable branch
command and a non-runnable one. I think it's a tractable problem, but not one I
wanted to deal with in this CL.

[Bob Nystrom, 2014/12/12 18:13:22]

This CL isn't urgent, though, is it?

I could be wrong but my intuition is that allowing branch commands to be run
will simplify the API because it will let you get rid of some duplication
between CommandRunner and Command.

[nweiz, 2014/12/16 02:07:43]

Well, it's blocking further work on the development server. But also this is a
minimal set of functionality for this feature, or at least minimal that supports
pub. Even if I were definitely planning to add that functionality, I'd want to
do it in a separate CL for minimality purposes.
I don't follow your reasoning. The only API difference is that a branch command
which implements [run] will have it run; how does that help duplication?

[Bob Nystrom, 2014/12/16 16:50:41]

I was thinking it might make it more natural for CommandRunner to subclass
Command but I didn't look into it in detail. I'm fine with doing this in another
patch. I just want to make sure this patch doesn't make that (potential) later
work harder.

+implemented. For example:
+
+    class StashCommand extends Command {
+      final String name = "stash";
+      final String description = "Stash changes in the working directory.";
+
+      StashCommand() {
+        addSubcommand(new StashSaveCommand());
+        addSubcommand(new StashListCommand());
+      }
+    }
+
+[CommandRunner][] will automatically add a `help` command that displays usage

[Bob Nystrom, 2014/12/11 20:25:30]

Present tense.

[nweiz, 2014/12/11 23:55:23]

Done.

+information for commands, as well as support for the `--help` flag for all
+commands. If it encounters an error parsing the arguments or processing a
+command, it will throw a [UsageError][]; the `main()` method should catch these

[Bob Nystrom, 2014/12/11 20:25:30]

"the" -> "your".

[nweiz, 2014/12/11 23:55:24]

Done.

+and print them appropriately. For example:
+
+    runner.run(arguments).catchError((error) {
+      if (error is! UsageError) throw error;
+      print(error);
+      exit(64); // Exit code 64 indicates a usage error.
+    });
+
 ## Displaying usage
 
 You can automatically generate nice help text, suitable for use as the output of
@@ -240,11 +297,16 @@ The resulting string looks something like this:
 
 [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
-[ArgParser]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgParser
-[ArgResults]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgResults
-[addOption]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgParser#id_addOption
-[addFlag]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgParser#id_addFlag
-[parse]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgParser#id_parse
-[rest]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgResults#id_rest
-[addCommand]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgParser#id_addCommand
-[getUsage]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/args/args.ArgParser#id_getUsage
+[ArgParser]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgParser
+[ArgResults]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgResults
+[CommandRunner]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.CommandRunner
+[Command]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.Command
+[UsageError]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.UsageError
+[addOption]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgParser@id_addOption
+[addFlag]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgParser@id_addFlag
+[parse]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgParser@id_parse
+[rest]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgResults@id_rest
+[addCommand]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgParser@id_addCommand
+[getUsage]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.ArgParser@id_getUsage
+[addSubcommand]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.Command@id_addSubcommand
+[run]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.Command@id_run