Improve the docs for CommandRunner (#148)
diff --git a/README.md b/README.md
index e2d777b..7d5fe5e 100644
--- a/README.md
+++ b/README.md
@@ -270,16 +270,36 @@
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:
+as handling `--help` flags and invalid arguments.
+
+When using the [CommandRunner][] it replaces the [ArgParser][].
+
+In the following example we build a dart application called `dgit` that takes commands `commit` and `stash`.
+
+The [CommandRunner][] takes an `executableName` which is used to generate the help message.
+
+e.g.
+`dgit commit -a`
+
+File `dgit.dart`
```dart
-var runner = CommandRunner("git", "Distributed version control.")
- ..addCommand(CommitCommand())
- ..addCommand(StashCommand())
- ..run(['commit', '-a']); // Calls [CommitCommand.run()]
+
+void main(List<String> args){
+ var runner = CommandRunner("dgit", "A dart implementation of distributed version control.")
+ ..addCommand(CommitCommand())
+ ..addCommand(StashCommand())
+ ..run(args);
```
-Custom commands are defined by extending the [Command][] class. For example:
+When the above `run(args)` line executes it parses the command line args looking for one of the commands (`commit` or `stash`).
+
+
+
+If the [CommandRunner][] finds a matching command then the [CommandRunner][] calls the overridden `run()` method on the matching command (e.g. CommitCommand().run).
+
+
+Commands are defined by extending the [Command][] class. For example:
```dart
class CommitCommand extends Command {
@@ -289,18 +309,45 @@
final description = "Record changes to the repository.";
CommitCommand() {
+ // we can add command specific arguments here.
// [argParser] is automatically created by the parent class.
argParser.addFlag('all', abbr: 'a');
}
// [run] may also return a Future.
void run() {
- // [argResults] is set before [run()] is called and contains the options
+ // [argResults] is set before [run()] is called and contains the flags/options
// passed to this command.
print(argResults['all']);
}
}
```
+### CommandRunner Arguments
+The [CommandRunner][] allows you to specify both global args as well as command specific arguments (and even sub-command specific arguments).
+
+#### Global Arguments
+Add argments directly to the [CommandRunner] to specify global arguments:
+
+Adding global arguments
+```dart
+var runner = CommandRunner('dgit', "A dart implementation of distributed version control.");
+// add global flag
+runner.addFlag('verbose', abbr: 'v', help: 'increase logging');
+```
+
+#### Command specific Arguments
+Add arguments to each [Command][] to specify [Command][] specific arguments.
+
+```dart
+
+ CommitCommand() {
+ // we can add command specific arguments here.
+ // [argParser] is automatically created by the parent class.
+ argParser.addFlag('all', abbr: 'a');
+ }
+
+```
+### SubCommands
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
@@ -318,6 +365,7 @@
}
```
+### Default Help Command
[CommandRunner][] automatically adds a `help` command that displays usage
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
